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.

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.

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

Retrieves the current cart or creates a new cart when no cart identifier is supplied. 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. Network carts reject cross-store location substitution.

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/{id}

Retrieve a Cart

Retrieves an existing cart by its unique identifier. If the cart is still active, the response includes its current line items and totals.

GET/v1/carts/{id}

curl https://api.fleetbase.io/v1/carts/{id} \
  -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.

Body parameters

quantityintegeroptional

Number of units to add or update.

variantsstringoptional

Selected product variant IDs or option values.

addonsstringoptional

Selected addon IDs or addon option values.

scheduled_attimestampoptional

ISO8601 timestamp for scheduled fulfillment.

store_locationstringoptional

Store location ID used for 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/{id}/empty

Empty cart

Removes all line items from a cart. The response returns the emptied cart resource.

PUT/v1/carts/{id}/empty

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

DELETE/v1/carts

Delete Cart

DELETE/v1/carts

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