Orders

Complete Order Pickup

Marks an authenticated customer's pickup order as completed. Fleetbase verifies that the order belongs to the customer before updating the order status.

curl -X PUT https://api.fleetbase.io/v1/orders/picked-up \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{
  "order": "{{order_id}}"
}'

Get Order Receipt

Returns a receipt for an authenticated customer's order when the payment method supports receipts. QPay orders can generate an Ebarimt receipt.

curl -X POST https://api.fleetbase.io/v1/orders/receipt \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{
  "order": "{{order_id}}",
  "ebarimt_receiver_type": "CITIZEN",
  "ebarimt_receiver": ""
}'

Request Address Change

Tells the store that the order's drop-off address is wrong. The store sees an alert on the order, and the message is posted in the customer's chat with the store (a message with kind address_change_requested). The store then updates the address or dismisses the request. Requires the Customer-Token of the customer who placed the order.

Send a message, a place (one of the customer's saved places, see customers/places), or both. The request is recorded on the order as meta.address_change_request.

Response: { "status": "ok", "address_change_request": { "status": "open", "message", "place", "address", "at" } }. place and address are the suggested saved place's id and address, or null.

Errors: 401 without a customer token; 404 for an order not placed through this storefront (Order not found.) or an unknown place (Place not found.); 403 for another customer's order; 409 with "reason": "chat_unavailable" when the chat with the store can't be opened (the customer has no user account, or the order finished without one); 422 when the order is completed, canceled or expired, or is a pickup order (The address of this order can no longer change.), and when message is longer than 1000 characters.

In a contract run this addresses {{address_change_order_id}} when the environment sets one (an open delivery order of the run's customer). Otherwise it addresses an unknown order and asserts the 404.

curl -X POST https://api.fleetbase.io/v1/orders/address-change-request \
  -H "Authorization: Bearer flb_live_…" \
  -H "Content-Type: application/json" \
  -H "Customer-Token: {{customer_token}}" \
  -d '{
  "message": "The building number is wrong, it'\''s 18 not 81.",
  "place": "{{place_id}}"
}'

Balance Paid Callback

QPay's callback for a balance invoice: when the store edits a paid order and the total goes up, the customer is sent a payment link for the balance (a QPay invoice, or a Stripe Payment Link), and QPay calls this URL when the invoice is paid. It needs no storefront key; Storefront builds the URL with the order's public id when it creates the invoice.

Storefront never trusts the callback itself: it asks the gateway what was paid against the order's open balance link. When the balance is paid it records the charge on the order's payment (meta.payment), closes the link and sends the customer the order_balance_paid notification. Stripe Payment Links have no callback; Storefront checks them every five minutes (storefront:check-balance-payments).

Response: { "status": "paid" } when the balance was settled now, { "status": "pending" } when nothing (more) is paid or the gateway can't be asked, and 404 with { "status": "unknown" } for an unknown order. Calling it again after the balance is settled answers pending.

In a contract run this addresses {{balance_order_id}} when the environment sets one. Otherwise it addresses an unknown order and asserts the 404.

curl https://api.fleetbase.io/v1/orders/balance-paid?order={{balance_order_id}} \
  -H "Authorization: Bearer flb_live_…"

Get Order Activity Flow

Returns the steps of an order's activity flow for a progress view: the steps already reached (with when), the current step, and the steps still to come. Requires the Customer-Token of the customer who placed the order.

Response: { order, order_config, status, canceled, completed, steps: [{ code, label, details, state, reached_at, complete }] }. state is done, current or upcoming; once the order is completed, the current step is done. order_config ({ id, key, name }) and status can be null.

Errors: 400 when the customer isn't authenticated, 404 for an unknown order, 403 for another customer's order.

curl https://api.fleetbase.io/v1/orders/activity-flow \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"

Get Order Stores

For a Network order placed across several stores (a master order), returns each store's part of the order: its status, items and amounts. Returns { "stores": [] } for an order from a single store. Requires the Customer-Token of the customer who placed the order.

Response: { stores: [{ order, status, label, store: { id, name, logo_url, phone, address }, items: [{ id, name, quantity, subtotal, variants, addons, image_url }], subtotal, discount, tip, currency }] }. label is the store order's current activity step. Amounts are in the currency's smallest unit.

Errors: 400 when the customer isn't authenticated, 404 for an unknown order, 403 for another customer's order.

curl https://api.fleetbase.io/v1/orders/stores \
  -H "Authorization: Bearer flb_live_…" \
  -H "Customer-Token: {{customer_token}}"