Document Storefront verified reviews, promotion availability, order chat and add-on limits

postman/collections/Fleetbase Storefront API/Cart/.resources/definition.yaml

@@ -1,4 +1,6 @@
 $kind: collection
 description: |-
   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.
 order: 1000

postman/collections/Fleetbase Storefront API/Cart/Add Item to Cart.params.yaml

@@ -14,4 +14,7 @@ fields:
     description: "Scheduled fulfillment time for the line item."
   - name: store_location
     type: string
-    description: "Public ID of a location belonging to the product's store. Network carts reject cross-store location substitution."
+    description: "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."
+  - name: catalog
+    type: string
+    description: "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`."

postman/collections/Fleetbase Storefront API/Cart/Delete Cart.request.yaml

@@ -1,5 +1,6 @@
 $kind: http-request
-description: Delete Cart
+description: |-
+  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.
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/carts/{{cart_id}}"
 method: DELETE
 order: 6000

postman/collections/Fleetbase Storefront API/Cart/Empty cart.request.yaml

@@ -1,8 +1,6 @@
 $kind: http-request
 description: |-
-  Removes all line items from a cart. The response returns the emptied cart resource.
-url: "{{base_url}}/{{api_prefix}}/{{namespace}}/carts/{id}/empty"
+  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.
+url: "{{base_url}}/{{api_prefix}}/{{namespace}}/carts/{{cart_id}}/empty"
 method: PUT
-pathVariables:
-  id: ""
 order: 5000

postman/collections/Fleetbase Storefront API/Cart/Retrieve a Cart.request.yaml

@@ -1,8 +1,6 @@
 $kind: http-request
 description: |-
-  Retrieves an existing cart by its unique identifier. If the cart is still active, the response includes its current line items and totals.
-url: "{{base_url}}/{{api_prefix}}/{{namespace}}/carts/{id}"
+  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.
+url: "{{base_url}}/{{api_prefix}}/{{namespace}}/carts/{{cart_id}}"
 method: GET
-pathVariables:
-  id: ""
 order: 2000

postman/collections/Fleetbase Storefront API/Cart/Retrieve or Create Cart.request.yaml

@@ -1,6 +1,6 @@
 $kind: http-request
 description: |-
-  Retrieves the current cart or creates a new cart when no cart identifier is supplied. Use the returned cart ID for subsequent cart operations.
+  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.
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/carts"
 method: GET
 scripts:

postman/collections/Fleetbase Storefront API/Cart/Update item in Cart.params.yaml

@@ -2,16 +2,13 @@ $kind: params
 fields:
   - name: quantity
     type: integer
-    description: "Number of units to add or update."
+    description: "New quantity for the line item."
   - name: variants
-    type: string
-    description: "Selected product variant IDs or option values."
+    type: array of objects
+    description: "Selected product variant data for the line item."
   - name: addons
-    type: string
-    description: "Selected addon IDs or addon option values."
+    type: array of objects
+    description: "Selected product add-on data for the line item."
   - name: scheduled_at
     type: timestamp
-    description: "ISO8601 timestamp for scheduled fulfillment."
-  - name: store_location
-    type: string
-    description: "Store location ID used for fulfillment."
+    description: "ISO 8601 timestamp for scheduled fulfillment."

postman/collections/Fleetbase Storefront API/Cart/Update item in Cart.request.yaml

@@ -3,6 +3,8 @@ description: |-
   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.
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/carts/{{cart_id}}/{{line_item_id}}"
 method: PUT
 headers:

postman/collections/Fleetbase Storefront API/Category/List categories.request.yaml

@@ -1,12 +1,10 @@
 $kind: http-request
 description: |-
   Returns product categories for a store key, network categories for a network key, or product categories for a selected network member store. Category and product expansion remains scoped to the authenticated storefront owner.
+
+  `parent`, `parents_only`, `with_products` and `with_stores` take effect whenever they're present, whatever their value; leave them out to turn them off.
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/categories"
 method: GET
 queryParams:
   store: ""
-  parent: ""
-  parents_only: ""
-  with_products: ""
-  with_stores: ""
 order: 1000

postman/collections/Fleetbase Storefront API/Checkout/.resources/object.yaml

@@ -1,19 +1,30 @@
 $kind: object
 name: Checkout
 description: |-
-  A checkout token represents a prepared storefront checkout session for a cart, customer, gateway, and delivery or pickup option.
+  A checkout represents a prepared storefront checkout session for a cart, customer, gateway, and delivery or pickup option. The fields returned depend on the gateway.
+
+  Realtime updates are published on the channel `checkout.{checkout}` as `{ checkout, status, order, payment, error }`, where `status` is `pending`, `paid`, `completed` or `failed`. With socket authentication enabled, subscribe using `socket_token` (guests) or a customer socket token from `POST customers/socket-token`.
 example: |
   {
+    "checkout": "chkt_8Ty2nQ4",
     "token": "checkout-token",
     "paymentIntent": "pi_123",
     "clientSecret": "pi_123_secret_456",
     "ephemeralKey": "ek_test_123",
-    "customerId": "cus_123"
+    "customerId": "cus_123",
+    "socket_token": {
+      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+      "expires_in": 900,
+      "expires_at": "2026-10-12T10:15:00+00:00"
+    }
   }
 fields:
+  - name: checkout
+    type: string
+    description: "Public checkout ID (`chkt_…`). Use it with `checkouts/status` and the realtime channel `checkout.{checkout}`."
   - name: token
     type: string
-    description: "Checkout token used to capture the order."
+    description: "Checkout token used to capture the order and check its status."
   - name: paymentIntent
     type: string
     description: "Stripe PaymentIntent ID when using Stripe checkout."
@@ -28,7 +39,7 @@ fields:
     description: "Gateway customer ID."
   - name: invoice
     type: object
-    description: "QPay invoice payload when using QPay checkout."
-  - name: checkout
-    type: string
-    description: "Public checkout ID returned by QPay checkout initialization."
+    description: "QPay invoice payload (bank app links, QR) when using QPay checkout."
+  - name: socket_token
+    type: object
+    description: "Present when realtime socket authentication is enabled: `{ token, expires_in, expires_at }`, a short-lived token allowed to subscribe to `checkout.{checkout}`. Logged-in customers can use their own socket token instead."

postman/collections/Fleetbase Storefront API/Checkout/Before Cash Pickup Checkout.queryParams.yaml

@@ -2,16 +2,19 @@ $kind: params
 fields:
   - name: gateway
     type: string
-    description: "Payment gateway code — `cash` for a cash-on-delivery checkout."
+    required: true
+    description: "Payment gateway code: `cash` for a cash-on-delivery checkout."
   - name: customer
     type: string
-    description: "Customer ID associated with the request."
+    required: true
+    description: "Customer public ID. Must match the authenticated customer when `Customer-Token` is sent."
   - name: cart
     type: string
-    description: "Cart value for this checkout request."
+    required: true
+    description: "Cart public ID (`cart_…`)."
   - name: pickup
     type: boolean
     description: "Set true for a pickup order; a cash pickup checkout needs no service quote."
   - name: promo_codes
     type: array of strings
-    description: "Promo codes to apply, as an array or a comma separated string. `promo_code` and `discount_code` are accepted for a single code. Codes already applied to the cart are always included. The checkout is refused with `400` and `promotions.rejected[]` (`{ code, reason }`) when a code cannot be applied; the discount of the storefront's automatic promotions is applied without a code."
+    description: "Promo codes to apply, as an array or a comma separated string. `promo_code`, `promoCode` and `discount_code` are accepted for a single code. Codes already applied to the cart are always included. The checkout is refused with `400` and `promotions.rejected[]` (`{ code, reason }`) when a code cannot be applied; the discount of the storefront's automatic promotions is applied without a code."

postman/collections/Fleetbase Storefront API/Checkout/Before ❗.queryParams.yaml

@@ -2,28 +2,36 @@ $kind: params
 fields:
   - name: gateway
     type: string
-    description: "Payment gateway ID or code."
+    required: true
+    description: "Code of a payment gateway configured for the store or network (for example `stripe` or `qpay`), or `cash` for cash on delivery. Gateway IDs are not accepted."
   - name: customer
     type: string
-    description: "Customer public ID for guest checkout. When Customer-Token is present this value must identify the authenticated customer or checkout returns 403."
+    required: true
+    description: "Customer public ID. When `Customer-Token` is sent, it must identify the authenticated customer, otherwise the checkout is refused with `403`."
   - name: cart
     type: string
-    description: "Cart public ID or unique identifier. Network checkout validates member stores, online state, products, locations, currency consistency, and the network multi-cart policy before payment initialization."
+    required: true
+    description: "Cart public ID (`cart_…`). Only open carts are used: an ID of a cart that was already checked out or cleared resolves to the device's open cart. Network checkout validates member stores, online state, products, locations, currency consistency and the network multi-cart policy before payment initialization."
   - name: service_quote
     type: string
-    description: "Service quote ID used by the request."
-  - name: cash
-    type: boolean
-    description: "Cash value for this checkout request."
+    description: "Delivery service quote public ID. Required unless `pickup` is true. `serviceQuote` is an accepted alias."
   - name: pickup
     type: boolean
-    description: "Pickup address, place ID, or pickup payload for the order."
+    default: false
+    description: "Set to true for a pickup order. A pickup checkout needs no service quote and ignores `delivery_tip`."
+  - name: cash
+    type: boolean
+    default: false
+    description: "Set to true to pay cash on delivery. Same as `gateway=cash`."
   - name: tip
-    type: number
-    description: "Tip amount applied to the checkout."
+    type: string
+    description: "Store tip, as an amount in the currency's smallest unit or a percentage string such as `10%`."
   - name: delivery_tip
-    type: number
-    description: "Tip amount allocated to delivery."
+    type: string
+    description: "Driver tip, as an amount or a percentage string such as `10%`. Ignored for pickup. `deliveryTip` is an accepted alias."
   - name: promo_codes
     type: array of strings
-    description: "Promo codes to apply, as an array or a comma separated string. `promo_code` and `discount_code` are accepted for a single code. Codes already applied to the cart are always included. The checkout is refused with `400` and `promotions.rejected[]` (`{ code, reason }`) when a code cannot be applied; the discount of the storefront's automatic promotions is applied without a code."
+    description: "Promo codes to apply, as an array or a comma separated string. `promo_code`, `promoCode` and `discount_code` are accepted for a single code. Codes already applied to the cart are always included. The checkout is refused with `400` and `promotions.rejected[]` (`{ code, reason }`) when a code cannot be applied; the discount of the storefront's automatic promotions is applied without a code."
+  - name: ebarimt_registration_no
+    type: string
+    description: "QPay only. Company registration number for the e-barimt receipt. It is saved on the customer and sent as the receipt's receiver."

postman/collections/Fleetbase Storefront API/Checkout/Before ❗.request.yaml

@@ -3,6 +3,10 @@ description: |-
   Initializes a checkout preview for a cart, customer, gateway, and delivery or pickup option. The response prepares gateway-specific client data or a checkout token before the order is captured.
 
   Promotions are priced when the checkout is created: automatic promotions and any promo codes (from `promo_codes` or applied to the cart) are subtracted from the amount charged, and each use is reserved for the checkout. A code that cannot be applied refuses the checkout with `400`.
+
+  The response depends on the gateway: cash returns `{ checkout, token }`, Stripe returns `{ paymentIntent, clientSecret, ephemeralKey, customerId, checkout, token }`, and QPay returns `{ invoice, checkout, token }`. When realtime socket authentication is enabled, every response also carries `socket_token`: a token scoped to the realtime channel `checkout.{checkout}`, which a guest uses to receive payment and order updates (see the Checkout object).
+
+  Errors: `403` when `customer` does not match the authenticated customer; `400` when no gateway is configured or a promo code cannot be applied; for Network carts, `422`/`403` when the cart is empty, has a store outside the network or offline, mixes stores without multi-store carts, has an unavailable product or location, or mixes currencies.
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/checkouts/before"
 method: GET
 queryParams:

postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback via GET.queryParams.yaml

@@ -2,10 +2,12 @@ $kind: params
 fields:
   - name: checkout
     type: string
-    description: "Checkout value for this checkout request."
+    required: true
+    description: "Public checkout ID (`chkt_…`) the invoice was created for."
   - name: respond
     type: boolean
-    description: "Respond value for this checkout request."
+    description: "Return `{ checkout, payment, error }` as JSON instead of QPay's plain-text `SUCCESS`."
   - name: test
-    type: string
-    description: "Test value for this checkout request."
+    type: enum
+    values: ["success", "error"]
+    description: "Sandbox only. Simulate a paid (`success`) or unpaid (`error`) callback."

postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback via GET.request.yaml

@@ -1,6 +1,10 @@
 $kind: http-request
 description: |-
-  Processes a QPay checkout callback from query parameters. Sandbox requests can pass `test` to simulate success or failure.
+  The same callback with its parameters in the query string, which is how QPay calls it; it is public and needs no storefront key. Fleetbase looks up the checkout, asks QPay for the invoice's payments, and creates the order only when a payment is `PAID` for at least the invoiced amount (`NEW`, `FAILED`, `PARTIAL` and `REFUNDED` create nothing). The payment is recorded on the checkout and published to the realtime channel `checkout.{checkout}`, first as `paid`, then as `completed` with the order.
+
+  Response: without `respond`, always HTTP `200` with the plain-text body `SUCCESS`, as QPay requires, even when something failed. With `respond=1`: JSON `{ checkout, payment, error }`, where `error` is `CHECKOUT_ID_MISSING`, `CHECKOUT_SESSION_NOT_FOUND`, `GATEWAY_NOT_CONFIGURED`, `MISSING_INVOICE_ID` or `PAYMENT_NOT_PAID`.
+
+  In sandbox, `test=success` only publishes test data (no payment is recorded and no order is created) and `test=error` returns `PAYMENT_NOT_PAID`.
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/checkouts/capture-qpay"
 method: GET
 queryParams:

postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback.params.yaml

@@ -6,7 +6,7 @@ fields:
     description: "Public checkout ID being confirmed by QPay."
   - name: respond
     type: boolean
-    description: "Whether Fleetbase should return the payment check payload in the HTTP response."
+    description: "Return `{ checkout, payment, error }` as JSON instead of QPay's plain-text `SUCCESS`."
   - name: test
     type: enum
     values: ["success", "error"]

postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback.request.yaml

@@ -1,6 +1,10 @@
 $kind: http-request
 description: |-
-  Processes a QPay checkout callback. Fleetbase verifies the checkout and gateway, checks the QPay invoice payment state, and creates the order when payment is confirmed.
+  The callback QPay calls when an invoice is paid; it is public and needs no storefront key. Fleetbase looks up the checkout, asks QPay for the invoice's payments, and creates the order only when a payment is `PAID` for at least the invoiced amount (`NEW`, `FAILED`, `PARTIAL` and `REFUNDED` create nothing). The payment is recorded on the checkout and published to the realtime channel `checkout.{checkout}`, first as `paid`, then as `completed` with the order.
+
+  Response: without `respond`, always HTTP `200` with the plain-text body `SUCCESS`, as QPay requires, even when something failed. With `respond=1`: JSON `{ checkout, payment, error }`, where `error` is `CHECKOUT_ID_MISSING`, `CHECKOUT_SESSION_NOT_FOUND`, `GATEWAY_NOT_CONFIGURED`, `MISSING_INVOICE_ID` or `PAYMENT_NOT_PAID`.
+
+  In sandbox, `test=success` only publishes test data (no payment is recorded and no order is created) and `test=error` returns `PAYMENT_NOT_PAID`.
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/checkouts/capture-qpay"
 method: POST
 headers:

postman/collections/Fleetbase Storefront API/Checkout/Capture checkout as order.request.yaml

@@ -4,6 +4,8 @@ description: |-
 
   Stripe checkouts are captured only after Fleetbase retrieves the server-linked PaymentIntent and verifies that it succeeded and matches the checkout amount, currency, customer, and live/test mode. An incomplete payment returns `402`, a missing or mismatched PaymentIntent returns `422`, and a temporary Stripe verification failure returns `502`. Clients must confirm the PaymentIntent before calling this endpoint and must not send or trust a client-selected PaymentIntent ID during capture.
 
+  The order is built from the cart as it was when the checkout was created, so changing or clearing the cart afterwards doesn't change the order, and the cart is marked checked out. A cart with a bookable product or a scheduled line becomes a booking order (`meta.is_booking`, `meta.booking_at`). A Network checkout across several stores creates one order per store under a master order (`meta.is_master_order`, `meta.related_orders`); see `GET orders/{id}/stores`. The response is the order; its `meta` includes `discount`, `promotions`, `payment_status` and the booking fields.
+
   Because a contract run cannot complete a card payment, this example captures the cash pickup checkout created by `Before Cash Pickup Checkout`, which needs no provider payment; the unpaid Stripe checkout's `402` refusal is asserted by `Capture Stripe checkout without payment`.
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/checkouts/capture"
 method: POST

postman/collections/Fleetbase Storefront API/Checkout/Create Stripe Setup Intent.params.yaml

@@ -1,16 +1,6 @@
 $kind: params
 fields:
-  - name: name
+  - name: customer
     type: string
     required: true
-    description: "Display name for the resource."
-  - name: description
-    type: string
-    description: "Human-readable description of the resource."
-  - name: status
-    type: enum
-    values: ["active", "inactive"]
-    description: "Lifecycle status to apply to the resource."
-  - name: meta
-    type: string
-    description: "Arbitrary metadata stored with the resource."
+    description: "Customer public ID. Must match the authenticated customer when `Customer-Token` is sent, otherwise `403`."