Cart

Carts hold the products a storefront customer intends to purchase. Use cart endpoints to create or retrieve a cart, add or update line items, apply or preview promo codes and promotions, empty the cart, and prepare it for checkout. A cart is `open` while it's being shopped, `checked_out` once an order was placed from it, and `cleared` when the customer emptied it. Closed carts keep their items as a record, and every cart endpoint only works on open carts: an ID of a checked-out or cleared cart resolves to the device's open cart (a different ID), or a new one. Always continue with the `id` the response returns.

The Cart object

A cart stores storefront products selected for checkout, including quantities, variants, addons, scheduling, and pricing totals.

Attributes

idstringoptional

Public identifier of the cart.

customer_idstringoptional

Customer identifier associated with the cart.

currencycurrencyoptional

Cart currency code.

subtotalintegeroptional

Cart subtotal.

total_itemsintegeroptional

Total quantity of items in the cart.

total_unique_itemsintegeroptional

Number of unique cart line items.

itemsarray of objectsoptional

Cart line items. Each item's store gives the store it is bought from: id, name, logo_url, backdrop_url, online, currency, and its clock, timezone and utc_offset (minutes east of UTC), to show a booked item's scheduled_at in the store's time.

eventsarray of objectsoptional

Cart event history.

discount_codestringoptional

Promo codes applied to the cart, comma separated. Prefer promo_codes.

promo_codesarray of stringsoptional

Promo codes applied to the cart with Apply Promotion Code to Cart. They are used automatically at checkout.

expires_attimestampoptional

Time the cart expires.

created_attimestampoptional

Time the cart was created.

updated_attimestampoptional

Time the cart was last updated.

The Cart object

{
  "id": "cart_8Xk2mQ1",
  "customer_id": "customer_4sW9kP2",
  "currency": "USD",
  "subtotal": 4200,
  "total_items": 3,
  "total_unique_items": 2,
  "items": [],
  "events": [],
  "discount_code": "SUMMER25",
  "promo_codes": [
    "SUMMER25"
  ],
  "expires_at": "2026-05-08T09:30:00Z",
  "created_at": "2026-05-07T09:30:00Z",
  "updated_at": "2026-05-07T09:30:00Z"
}

GET/v1/carts

Retrieve or Create Cart

Creates a new, anonymous open cart. To continue a device's cart, use Retrieve a Cart with the device's unique identifier instead. Use the returned cart ID for subsequent cart operations.

GET/v1/carts

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

POST/v1/carts

Add Item to Cart

Adds a product to a cart and creates or updates the matching cart line item. Include quantity, variants, addons, scheduling, or store location details when needed.

Body parameters

quantityintegeroptional

Quantity of the product to add. Defaults to 1.

variantsarray of objectsoptional

Selected product variant data to store on the cart line item.

addonsarray of objectsoptional

Selected product addon data to store on the cart line item.

scheduled_attimestampoptional

Scheduled fulfillment time for the line item.

store_locationstringoptional

Public ID of a location belonging to the product's store, or a food truck ID (food_truck_…) to order from that truck, which also sets the line's location. A location from another store returns 400. Network carts reject cross-store location substitution.

catalogstringoptional

Catalog public ID the product is ordered from (for example a food truck's menu). The catalog's price and availability apply; a product that's unavailable in the catalog returns 400.

POST/v1/carts

curl -X POST https://api.fleetbase.io/v1/carts \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "addons": [],
  "quantity": 1,
  "variants": []
}'

GET/v1/carts/promotions

Preview Cart Promotions

Previews the discounts the cart currently qualifies for: the storefront's automatic promotions plus the promo codes applied to the cart. Pass pickup and service_quote so delivery discounts are priced. Customer rules (first order only, per-customer limits) are only checked when a Customer-Token is sent, and every rule is checked again at checkout.

Returns { "discount", "discount_subtotal", "discount_delivery", "applied": [...], "rejected": [...] }. Each applied entry has promotion, name, type, code, amount and delivery_amount (minor units). Each rejected entry is { "code", "reason" }.

Query parameters

pickupbooleanoptional

Price the cart as a pickup order (no delivery discounts).

service_quotestringoptional

Delivery service quote public ID, used to price free delivery promotions.

GET/v1/carts/promotions

curl https://api.fleetbase.io/v1/carts/promotions?pickup=false&service_quote={{service_quote_id}} \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"

POST/v1/carts/promo-code

Apply Promotion Code to Cart

Applies a promo code to the cart after checking that it can be used on it. Codes are case insensitive. On success it returns { "cart": Cart, "promotions": preview } (see Preview Cart Promotions) and stores the code in the cart's promo_codes; codes applied to a cart are used automatically at checkout.

A code that cannot be applied returns 400 with the reason, e.g. Promotion code "SUMMER" cannot be applied (invalid_code). and "reason": "invalid_code". Reasons: invalid_code, not_applicable, not_active, usage_limit_reached, customer_usage_limit_reached, budget_exhausted, currency_mismatch, first_order_only, min_subtotal, min_items, no_eligible_items, pickup_order, no_discount. A code that is valid but loses to a better combination of promotions is kept on the cart and reported in promotions.rejected as not_combinable.

Body parameters

codestringrequired

The promo code to apply.

pickupbooleanoptional

Price the cart as a pickup order when validating the code.

service_quotestringoptional

Delivery service quote public ID, for free delivery codes.

POST/v1/carts/promo-code

curl -X POST https://api.fleetbase.io/v1/carts/promo-code \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{
  "code": "{{promo_code}}"
}'

DELETE/v1/carts/promo-code

Remove Promotion Code from Cart

Removes a promo code from the cart and returns { "cart": Cart, "promotions": preview }. Removing a code that is not on the cart is not an error.

DELETE/v1/carts/promo-code

curl -X DELETE https://api.fleetbase.io/v1/carts/promo-code \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"

GET/v1/carts

Retrieve a Cart

Retrieves an open cart by its public ID or by a unique identifier (such as a device ID). An unknown unique identifier creates a new cart with that identifier. The ID of a cart that was checked out or cleared resolves to the device's open cart, so the returned id can differ from the one requested.

GET/v1/carts

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

PUT/v1/carts

Update item in Cart

Updates a line item already in the cart. Send any of quantity, variants, addons or scheduled_at; omitted fields are left unchanged. The response returns the updated cart.

{lineItemId} can also be the product ID of a line. The line keeps the price of the catalog it was added from.

Body parameters

quantityintegeroptional

New quantity for the line item.

variantsarray of objectsoptional

Selected product variant data for the line item.

addonsarray of objectsoptional

Selected product add-on data for the line item.

scheduled_attimestampoptional

ISO 8601 timestamp for scheduled fulfillment.

PUT/v1/carts

curl -X PUT https://api.fleetbase.io/v1/carts \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "quantity": 2
}'

DELETE/v1/carts

Remove item from cart

Removes a line item or product from a cart. The response returns the updated cart after the item is removed.

DELETE/v1/carts

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

PUT/v1/carts/empty

Empty cart

Clears the cart. A cart with items is marked cleared (its items are kept as a record) and the response is the device's open cart, a different cart, or a new one for an anonymous cart. Continue with the returned id. An already empty cart is returned unchanged.

PUT/v1/carts/empty

curl -X PUT https://api.fleetbase.io/v1/carts/empty \
  -H "Authorization: Bearer flb_live_…"

DELETE/v1/carts

Delete Cart

Deletes an open cart and returns []. The ID of a cart that was checked out or cleared resolves to the device's open cart, which is the one deleted.

DELETE/v1/carts

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