Payloads

Payloads describe what an order is carrying and where it moves from pickup to dropoff. Use payload endpoints to manage shipment contents, payment details, and the entities attached to an order.

The Payload object

A payload describes what an order moves and where it moves through. It links pickup, dropoff, return, waypoints, entities, cash-on-delivery settings, and metadata.

Attributes

idstringoptional

Public payload identifier.

current_waypointstringoptional

Public ID of the current waypoint, when one is set.

pickupobjectoptional

Pickup place for the payload.

dropoffobjectoptional

Dropoff place for the payload.

returnobjectoptional

Return place for the payload.

waypointsarray of objectsoptional

Ordered waypoint resources for the payload.

entitiesarray of objectsoptional

Entity resources attached to the payload.

cod_amountcurrencyoptional

Cash-on-delivery amount.

cod_currencycurrencyoptional

Three-letter currency code for cash-on-delivery.

cod_payment_methodstringoptional

Cash-on-delivery payment method.

payment_methodstringoptional

Payment method associated with the payload.

metaobjectoptional

Additional payload metadata.

updated_attimestampoptional

Timestamp when the payload was last updated.

created_attimestampoptional

Timestamp when the payload was created.

The Payload object

{
  "id": "payload_x9Z2Lm8QpA",
  "current_waypoint": "place_1A2b3C4d5E",
  "pickup": {
    "id": "place_1A2b3C4d5E",
    "name": "Warehouse 7"
  },
  "dropoff": {
    "id": "place_9Z8y7X6w5V",
    "name": "Customer Dock"
  },
  "return": null,
  "waypoints": [],
  "entities": [],
  "cod_amount": null,
  "cod_currency": null,
  "cod_payment_method": null,
  "payment_method": null,
  "meta": {},
  "updated_at": "2026-05-07T08:30:00.000000Z",
  "created_at": "2026-05-07T08:30:00.000000Z"
}

POST/v1/payloads

Create a Payload

Creates a payload containing route endpoints and optional entities. Provide either pickup/dropoff endpoints or a waypoint list, then attach entities as needed.

Body parameters

pickupobjectoptional

Pickup place data, address string, or place ID for the payload.

dropoffobjectoptional

Dropoff place data, address string, or place ID for the payload.

returnobjectoptional

Optional return place data, address string, or place ID for the payload.

waypointsarray of objectsoptional

Ordered route stops for the payload.

entitiesarray of objectsoptional

Entities, packages, or items attached to the payload.

typestringrequired

Payload type. Required when creating a payload.

providerstringoptional

Provider identifier associated with the payload.

cod_amountcurrencyoptional

Cash-on-delivery amount.

cod_currencycurrencyoptional

Three-letter currency code for cod_amount. Required when cod_amount is supplied.

cod_payment_methodenumoptional

Cash-on-delivery payment method. Required when cod_amount is supplied. One of card, check, cash, bank_transfer.

metaobjectoptional

Additional payload metadata.

POST/v1/payloads

curl -X POST https://api.fleetbase.io/v1/payloads \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "pickup": "10 Bayfront Avenue, Singapore 018956",
  "dropoff": "80 Mandai Lake Rd, Singapore 729826",
  "type": "food_delivery"
}'

Other ways to call this

201 OK

{
  "id": "payload_oz5R9Z6",
  "current_waypoint": null,
  "pickup": null,
  "dropoff": null,
  "return": null,
  "waypoints": [],
  "entities": [],
  "cod_amount": null,
  "cod_currency": null,
  "cod_payment_method": null,
  "meta": [],
  "updated_at": "2023-12-27T09:40:21.000000Z",
  "created_at": "2023-12-27T09:40:21.000000Z"
}

GET/v1/payloads/:id

Retrieve a Payload

Retrieve a Payload.

GET/v1/payloads/:id

curl https://api.fleetbase.io/v1/payloads/:id \
  -H "Authorization: Bearer flb_live_…"

GET/v1/payloads

Query Payloads

Returns payloads for the current company. Use pagination and sort parameters to page through payload records.

Query parameters

limitintegeroptional

Maximum number of payloads to return.

offsetintegeroptional

Number of payloads to skip before returning results.

sortstringoptional

Sort expression for the payload query.

GET/v1/payloads

curl https://api.fleetbase.io/v1/payloads?limit=25&offset=0&sort=created_at \
  -H "Authorization: Bearer flb_live_…"

PUT/v1/payloads/:id

Update a Payload

Updates a payload's route endpoints, waypoints, entities, cash-on-delivery settings, or metadata. The response returns the updated payload with route and entity data.

Body parameters

pickupobjectoptional

Replacement pickup place data, address string, or place ID for the payload.

dropoffobjectoptional

Replacement dropoff place data, address string, or place ID for the payload.

returnobjectoptional

Replacement return place data, address string, or place ID for the payload.

waypointsarray of objectsoptional

Replacement waypoint list. Sending route endpoint fields without waypoints removes existing waypoints.

entitiesarray of objectsoptional

Replacement entities, packages, or items attached to the payload.

typestringoptional

Payload type.

providerstringoptional

Provider identifier associated with the payload.

cod_amountcurrencyoptional

Cash-on-delivery amount.

cod_currencycurrencyoptional

Three-letter currency code for cod_amount.

cod_payment_methodenumoptional

Cash-on-delivery payment method. One of card, check, cash, bank_transfer.

metaobjectoptional

Additional payload metadata.

PUT/v1/payloads/:id

curl -X PUT https://api.fleetbase.io/v1/payloads/:id \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "entities": [
        {
            "name": "UltraHD 4K Smart TV",
            "description": "65-inch high-definition smart TV with vibrant colors and a sleek design.",
            "currency": "USD",
            "price": 1200.00
        },
        {
            "name": "Bluetooth Wireless Headphones",
            "description": "Noise-cancelling, over-ear headphones with long-lasting battery life.",
            "currency": "USD",
            "price": 250.00
        },
        {
            "name": "Smart Fitness Watch",
            "description": "Water-resistant fitness watch with heart rate monitor and GPS tracking.",
            "currency": "USD",
            "price": 199.99
        }
    ]
}'

DELETE/v1/payloads/:id

Delete a Payload

Delete a Payload.

DELETE/v1/payloads/:id

curl -X DELETE https://api.fleetbase.io/v1/payloads/:id \
  -H "Authorization: Bearer flb_live_…"