FleetbaseFleetbase

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": {
    "street1": "10 Bayfront Avenue",
    "city": "Singapore",
    "postal_code": "018956",
    "country": "SG"
  },
  "dropoff": {
    "street1": "80 Mandai Lake Rd",
    "city": "Singapore",
    "postal_code": "729826",
    "country": "SG"
  },
  "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.

Entities are appended by default; with entities_mode replace the list sent becomes the payload's full list (entries with the id of one of its entities update it, entries without one are created, and entities left out are deleted). A cod_amount of 0 is kept, clearing the cash to collect; other empty values are ignored as before.

When the payload belongs to an order, the order's status decides what can still change, as for Update an Order: a locked change returns 422 { "error": "...", "locked": { "<field>": "<reason>" } } and nothing is written, and an accepted change broadcasts order.changed. Requires Fleet-Ops with fleetbase/fleetops#394 (release v0.6.72).

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

Entities, packages, or items for the payload. Appended to its entities, or with entities_mode replace, the payload's full list.

entities_modeenumoptionalDefault: append

replace (or sync) makes entities the payload's full list: entries with the id of one of the payload's entities update it, entries without one are created, and entities left out are deleted. One of append, replace.

typestringoptional

Payload type.

providerstringoptional

Provider identifier associated with the payload.

cod_amountcurrencyoptional

Cash-on-delivery amount. 0 is kept and clears the cash to collect.

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 '{
    "pickup": {
        "street1": "10 Bayfront Avenue",
        "city": "Singapore",
        "postal_code": "018956",
        "country": "SG"
    },
    "dropoff": {
        "street1": "80 Mandai Lake Rd",
        "city": "Singapore",
        "postal_code": "729826",
        "country": "SG"
    },
    "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_…"
Payloads | Fleetbase