Shipments API

The Shipments API manages the complete shipment lifecycle from booking to delivery. Use this API to create shipments, retrieve details, update information, and track packages.

Overview

The Shipments API provides:

Shipment creation from quotes or direct booking
Label generation in multiple formats (PDF, PNG, ZPL)
Status tracking with real-time updates
Document management for BOLs, PODs, and customs forms
Pickup scheduling and delivery confirmation

Endpoints

Method	Endpoint	Description
POST	`/book-shipment`	Create a new shipment
POST	`/book/{loadId}`	Book from quote using load ID
GET	`/shipments`	List user's shipments
GET	`/tracking/lookup/{loadId}`	Get shipment details
POST	`/update-shipment/{loadId}`	Update shipment information
GET	`/tracking`	Get shipments in transit
POST	`/track/get-documents`	Get shipment documents

Create Shipment

Create a new shipment either from a quote or with direct booking.

From Quote

POST /book-shipmenthttp

POST https://ship.flashamericas.com/api/v1/book-shipment
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Create from quotejson

{
"quoteId": "550e8400-e29b-41d4-a716-446655440000",
"selectedRate": {
  "provider": "FEDEX",
  "service": "FEDEX_GROUND"
},
"shipperInfo": {
  "companyName": "Acme Corp",
  "contactName": "John Smith",
  "phone": "214-555-0123",
  "email": "john@acme.com"
},
"consigneeInfo": {
  "companyName": "Customer Corp",
  "contactName": "Jane Doe",
  "phone": "713-555-0456",
  "email": "jane@customer.com"
},
"reference": "ORDER-12345",
"instructions": "Call before delivery",
"pickupDate": "2025-02-20",
"labelFormat": "PDF"
}

Direct Booking

Direct shipment creationjson

{
"originAddress": {
  "address1": "123 Main Street",
  "city": "Dallas",
  "state": "TX",
  "postalCode": "75201",
  "country": "US"
},
"destinationAddress": {
  "address1": "456 Oak Avenue",
  "city": "Houston",
  "state": "TX",
  "postalCode": "77001",
  "country": "US"
},
"cargo": [
  {
    "weight": 25.5,
    "length": 18,
    "width": 12,
    "height": 10,
    "quantity": 1,
    "description": "Electronics"
  }
],
"service": {
  "provider": "FEDEX",
  "service": "FEDEX_GROUND"
},
"shipperInfo": {
  "companyName": "Acme Corp",
  "contactName": "John Smith",
  "phone": "214-555-0123",
  "email": "john@acme.com"
},
"consigneeInfo": {
  "companyName": "Customer Corp", 
  "contactName": "Jane Doe",
  "phone": "713-555-0456",
  "email": "jane@customer.com"
},
"shipDate": "2025-02-20",
"reference": "ORDER-12345"
}

Response

Shipment creation responsejson

{
"success": true,
"data": {
  "shipmentId": "660e8400-e29b-41d4-a716-446655440001",
  "trackingNumber": "1234567890",
  "proNumber": "PRO123456", 
  "status": "PENDING",
  "provider": "FEDEX",
  "service": "FEDEX_GROUND",
  "labels": [
    {
      "type": "SHIPPING_LABEL",
      "format": "PDF",
      "url": "https://api.flashamericas.com/documents/label_123.pdf",
      "expires": "2025-01-22T10:30:00Z"
    }
  ],
  "estimatedPickup": "2025-02-20T15:00:00Z",
  "estimatedDelivery": "2025-02-21T17:00:00Z",
  "totalCost": 12.45,
  "currency": "USD",
  "createdAt": "2025-01-15T10:30:00Z"
}
}

List Shipments

Retrieve a paginated list of shipments with optional filtering.

Request

GET /shipmentshttp

GET https://ship.flashamericas.com/api/v1/shipments?page=1&limit=25&status=IN_TRANSIT
Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (max: 100, default: 25)
`status`	string	Filter by status
`provider`	string	Filter by carrier
`trackingNumber`	string	Search by tracking number
`reference`	string	Search by reference
`createdAfter`	string	ISO date filter
`createdBefore`	string	ISO date filter
`sort`	string	Sort field (createdAt, totalCost, etc.)
`order`	string	Sort order (asc, desc)

Response

Shipments list responsejson

{
"success": true,
"data": [
  {
    "shipmentId": "660e8400-e29b-41d4-a716-446655440001",
    "trackingNumber": "1234567890",
    "status": "IN_TRANSIT",
    "provider": "FEDEX",
    "service": "FEDEX_GROUND",
    "totalCost": 12.45,
    "currency": "USD",
    "estimatedDelivery": "2025-02-21T17:00:00Z",
    "createdAt": "2025-01-15T10:30:00Z"
  },
  {
    "shipmentId": "770e8400-e29b-41d4-a716-446655440002", 
    "trackingNumber": "0987654321",
    "status": "DELIVERED",
    "provider": "UPS",
    "service": "UPS_GROUND",
    "totalCost": 15.75,
    "currency": "USD",
    "actualDelivery": "2025-01-14T16:30:00Z",
    "createdAt": "2025-01-13T09:15:00Z"
  }
],
"meta": {
  "pagination": {
    "page": 1,
    "limit": 25,
    "total": 150,
    "pages": 6,
    "hasNext": true,
    "hasPrev": false
  }
}
}

Get Shipment Details

Retrieve complete information for a specific shipment.

Request

GET /tracking/lookup/{loadId}http

GET https://ship.flashamericas.com/api/v1/tracking/lookup/660e8400-e29b-41d4-a716-446655440001
Authorization: Bearer YOUR_API_KEY

Response

Shipment details responsejson

{
"success": true,
"data": {
  "shipmentId": "660e8400-e29b-41d4-a716-446655440001",
  "trackingNumber": "1234567890",
  "proNumber": "PRO123456",
  "status": "IN_TRANSIT",
  "provider": "FEDEX",
  "service": "FEDEX_GROUND",
  "originAddress": {
    "address1": "123 Main Street",
    "city": "Dallas",
    "state": "TX",
    "postalCode": "75201",
    "country": "US"
  },
  "destinationAddress": {
    "address1": "456 Oak Avenue",
    "city": "Houston", 
    "state": "TX",
    "postalCode": "77001",
    "country": "US"
  },
  "cargo": [
    {
      "weight": 25.5,
      "length": 18,
      "width": 12,
      "height": 10,
      "quantity": 1,
      "description": "Electronics"
    }
  ],
  "shipperInfo": {
    "companyName": "Acme Corp",
    "contactName": "John Smith",
    "phone": "214-555-0123",
    "email": "john@acme.com"
  },
  "consigneeInfo": {
    "companyName": "Customer Corp",
    "contactName": "Jane Doe",
    "phone": "713-555-0456", 
    "email": "jane@customer.com"
  },
  "reference": "ORDER-12345",
  "instructions": "Call before delivery",
  "totalCost": 12.45,
  "currency": "USD",
  "estimatedPickup": "2025-02-20T15:00:00Z",
  "estimatedDelivery": "2025-02-21T17:00:00Z",
  "actualPickup": "2025-02-20T14:30:00Z",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-02-20T14:35:00Z"
}
}

Update Shipment

Update shipment information before pickup.

Request

POST /update-shipment/{loadId}http

POST https://ship.flashamericas.com/api/v1/update-shipment/660e8400-e29b-41d4-a716-446655440001
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Update shipment requestjson

{
"reference": "ORDER-12345-UPDATED",
"instructions": "Leave at front door if no answer",
"consigneeInfo": {
  "companyName": "Customer Corp",
  "contactName": "Jane Doe",
  "phone": "713-555-0456",
  "email": "jane.doe@newdomain.com"
}
}

Response

Update shipment responsejson

{
"success": true,
"data": {
  "shipmentId": "660e8400-e29b-41d4-a716-446655440001",
  "status": "PENDING",
  "reference": "ORDER-12345-UPDATED",
  "instructions": "Leave at front door if no answer",
  "updatedAt": "2025-01-15T11:00:00Z"
}
}

Cancel Shipment

Cancel a shipment before pickup.

Request

POST /update-shipment/{loadId}http

POST https://ship.flashamericas.com/api/v1/update-shipment/660e8400-e29b-41d4-a716-446655440001
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Cancel shipment requestjson

{
"reason": "Customer requested cancellation",
"refundRequested": true
}

Response

Cancel shipment responsejson

{
"success": true,
"data": {
  "shipmentId": "660e8400-e29b-41d4-a716-446655440001",
  "status": "CANCELLED",
  "cancellationReason": "Customer requested cancellation",
  "refundAmount": 12.45,
  "refundStatus": "PROCESSING",
  "cancelledAt": "2025-01-15T11:30:00Z"
}
}

Get Documents

Retrieve all documents associated with a shipment.

Request

POST /track/get-documentshttp

POST https://ship.flashamericas.com/api/v1/track/get-documents
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body

Get documents requestjson

{
"loadId": "660e8400-e29b-41d4-a716-446655440001"
}

Response

Documents responsejson

{
"success": true,
"data": [
  {
    "documentId": "doc_123456",
    "type": "SHIPPING_LABEL",
    "format": "PDF",
    "url": "https://api.flashamericas.com/documents/label_123.pdf",
    "createdAt": "2025-01-15T10:30:00Z",
    "expires": "2025-01-22T10:30:00Z"
  },
  {
    "documentId": "doc_234567",
    "type": "BOL",
    "format": "PDF", 
    "url": "https://api.flashamericas.com/documents/bol_234.pdf",
    "createdAt": "2025-02-20T14:30:00Z",
    "expires": "2025-02-27T14:30:00Z"
  },
  {
    "documentId": "doc_345678",
    "type": "POD",
    "format": "PDF",
    "url": "https://api.flashamericas.com/documents/pod_345.pdf",
    "createdAt": "2025-02-21T16:45:00Z",
    "expires": "2025-02-28T16:45:00Z"
  }
]
}

Shipment Status

Shipments progress through several status states:

Status	Description
`PENDING`	Shipment created, awaiting pickup
`PICKUP_SCHEDULED`	Pickup has been scheduled
`PICKED_UP`	Package has been picked up
`IN_TRANSIT`	Package is in transit
`OUT_FOR_DELIVERY`	Package is out for delivery
`DELIVERED`	Package has been delivered
`EXCEPTION`	Delivery exception occurred
`CANCELLED`	Shipment was cancelled
`RETURNED`	Package is being returned

Label Formats

Shipping labels are available in multiple formats:

Format	Description	Use Case
`PDF`	Portable Document Format	Standard printing, email
`PNG`	Portable Network Graphics	Web display, mobile apps
`ZPL`	Zebra Programming Language	Thermal printers
`EPL`	Eltron Programming Language	Thermal printers

Examples

Create Shipment from Quote

Book shipment from quotejavascript

// First, get a quote
const quoteResponse = await fetch('https://ship.flashamericas.com/api/v1/quote-shipment', {
method: 'POST',
headers: {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
},
body: JSON.stringify(quoteRequest)
});

const quote = await quoteResponse.json();

// Select the best rate
const selectedRate = quote.data.rates[0];

// Create shipment
const shipmentResponse = await fetch('https://ship.flashamericas.com/api/v1/book-shipment', {
method: 'POST',
headers: {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
},
body: JSON.stringify({
  quoteId: quote.data.quoteId,
  selectedRate: {
    provider: selectedRate.provider,
    service: selectedRate.service
  },
  shipperInfo: {
    companyName: "Acme Corp",
    contactName: "John Smith",
    phone: "214-555-0123",
    email: "john@acme.com"
  },
  consigneeInfo: {
    companyName: "Customer Corp",
    contactName: "Jane Doe",
    phone: "713-555-0456",
    email: "jane@customer.com"
  },
  reference: "ORDER-12345"
})
});

const shipment = await shipmentResponse.json();
console.log('Shipment created:', shipment.data.shipmentId);
console.log('Tracking number:', shipment.data.trackingNumber);

List Recent Shipments

Get recent shipmentsjavascript

const response = await fetch('https://ship.flashamericas.com/api/v1/shipments?limit=10&sort=createdAt&order=desc', {
headers: {
  'Authorization': 'Bearer YOUR_API_KEY'
}
});

const shipments = await response.json();

shipments.data.forEach(shipment => {
console.log(`${shipment.trackingNumber}: ${shipment.status}`);
});

Download Shipping Label

Download labeljavascript

const response = await fetch('https://ship.flashamericas.com/api/v1/track/get-documents', {
method: 'POST',
headers: {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
},
body: JSON.stringify({ loadId: shipmentId })
});

const documents = await response.json();

// Download PDF label
const labelDoc = documents.data.find(doc => doc.type === 'SHIPPING_LABEL' && doc.format === 'PDF');
window.open(labelDoc.url, '_blank');

Error Handling

Common Errors

Shipment not foundjson

{
"success": false,
"error": {
  "code": "SHIPMENT_NOT_FOUND",
  "message": "Shipment not found"
}
}

Cannot modify shipped packagejson

{
"success": false,
"error": {
  "code": "SHIPMENT_IMMUTABLE",
  "message": "Cannot modify shipment after pickup",
  "details": {
    "status": "PICKED_UP",
    "pickedUpAt": "2025-02-20T14:30:00Z"
  }
}
}

Best Practices

Store shipment IDs - Keep track of shipment IDs for future reference
Check status before updates - Only modify shipments in PENDING status
Download labels immediately - Label URLs expire after 7 days
Handle exceptions - Monitor shipment status for delivery exceptions
Use webhooks - Set up webhooks for real-time status updates

Webhooks

Configure webhooks to receive real-time shipment updates:

Shipment webhook payloadjson

{
"eventId": "evt_550e8400-e29b-41d4-a716-446655440000",
"eventType": "shipment.picked_up",
"timestamp": "2025-02-20T14:30:00Z",
"data": {
  "shipmentId": "660e8400-e29b-41d4-a716-446655440001",
  "trackingNumber": "1234567890",
  "status": "PICKED_UP",
  "provider": "FEDEX",
  "location": {
    "city": "Dallas",
    "state": "TX",
    "country": "US"
  }
}
}

Next Steps

Track shipments for real-time updates
Set up webhooks for automatic notifications
Download documents for labels and BOLs
View examples for complete integration code

Shipments API

Overview

Endpoints

Create Shipment

From Quote

Direct Booking

Response

List Shipments

Request

Query Parameters

Response

Get Shipment Details

Request

Response

Update Shipment

Request

Response

Cancel Shipment

Request

Response

Get Documents

Request

Request Body

Response

Shipment Status

Label Formats

Examples

Create Shipment from Quote

List Recent Shipments

Download Shipping Label

Error Handling

Common Errors

Best Practices

Webhooks

Next Steps

On this page