diff --git a/postman/collections/Fleetbase Storefront API/Cart/.resources/definition.yaml b/postman/collections/Fleetbase Storefront API/Cart/.resources/definition.yaml index 3de170c..f818760 100644 --- a/postman/collections/Fleetbase Storefront API/Cart/.resources/definition.yaml +++ b/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 diff --git a/postman/collections/Fleetbase Storefront API/Cart/Add Item to Cart.params.yaml b/postman/collections/Fleetbase Storefront API/Cart/Add Item to Cart.params.yaml index 3c5301f..ff46ed8 100644 --- a/postman/collections/Fleetbase Storefront API/Cart/Add Item to Cart.params.yaml +++ b/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`." diff --git a/postman/collections/Fleetbase Storefront API/Cart/Delete Cart.request.yaml b/postman/collections/Fleetbase Storefront API/Cart/Delete Cart.request.yaml index 8c7404e..534d03c 100644 --- a/postman/collections/Fleetbase Storefront API/Cart/Delete Cart.request.yaml +++ b/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 diff --git a/postman/collections/Fleetbase Storefront API/Cart/Empty cart.request.yaml b/postman/collections/Fleetbase Storefront API/Cart/Empty cart.request.yaml index c5569e3..3668d26 100644 --- a/postman/collections/Fleetbase Storefront API/Cart/Empty cart.request.yaml +++ b/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 diff --git a/postman/collections/Fleetbase Storefront API/Cart/Retrieve a Cart.request.yaml b/postman/collections/Fleetbase Storefront API/Cart/Retrieve a Cart.request.yaml index 410b7a8..c28c150 100644 --- a/postman/collections/Fleetbase Storefront API/Cart/Retrieve a Cart.request.yaml +++ b/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 diff --git a/postman/collections/Fleetbase Storefront API/Cart/Retrieve or Create Cart.request.yaml b/postman/collections/Fleetbase Storefront API/Cart/Retrieve or Create Cart.request.yaml index f7ad79f..27590ee 100644 --- a/postman/collections/Fleetbase Storefront API/Cart/Retrieve or Create Cart.request.yaml +++ b/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: diff --git a/postman/collections/Fleetbase Storefront API/Cart/Update item in Cart.params.yaml b/postman/collections/Fleetbase Storefront API/Cart/Update item in Cart.params.yaml index af04d1b..cb1c10b 100644 --- a/postman/collections/Fleetbase Storefront API/Cart/Update item in Cart.params.yaml +++ b/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." diff --git a/postman/collections/Fleetbase Storefront API/Cart/Update item in Cart.request.yaml b/postman/collections/Fleetbase Storefront API/Cart/Update item in Cart.request.yaml index 2e50339..9462dfc 100644 --- a/postman/collections/Fleetbase Storefront API/Cart/Update item in Cart.request.yaml +++ b/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: diff --git a/postman/collections/Fleetbase Storefront API/Category/List categories.request.yaml b/postman/collections/Fleetbase Storefront API/Category/List categories.request.yaml index 0668e3b..cf7cae8 100644 --- a/postman/collections/Fleetbase Storefront API/Category/List categories.request.yaml +++ b/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 diff --git a/postman/collections/Fleetbase Storefront API/Checkout/.resources/object.yaml b/postman/collections/Fleetbase Storefront API/Checkout/.resources/object.yaml index 19dc178..fb24430 100644 --- a/postman/collections/Fleetbase Storefront API/Checkout/.resources/object.yaml +++ b/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." diff --git a/postman/collections/Fleetbase Storefront API/Checkout/Before Cash Pickup Checkout.queryParams.yaml b/postman/collections/Fleetbase Storefront API/Checkout/Before Cash Pickup Checkout.queryParams.yaml index 7c19fd4..4254dce 100644 --- a/postman/collections/Fleetbase Storefront API/Checkout/Before Cash Pickup Checkout.queryParams.yaml +++ b/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." diff --git "a/postman/collections/Fleetbase Storefront API/Checkout/Before \342\235\227.queryParams.yaml" "b/postman/collections/Fleetbase Storefront API/Checkout/Before \342\235\227.queryParams.yaml" index c316ca9..2cc059e 100644 --- "a/postman/collections/Fleetbase Storefront API/Checkout/Before \342\235\227.queryParams.yaml" +++ "b/postman/collections/Fleetbase Storefront API/Checkout/Before \342\235\227.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." diff --git "a/postman/collections/Fleetbase Storefront API/Checkout/Before \342\235\227.request.yaml" "b/postman/collections/Fleetbase Storefront API/Checkout/Before \342\235\227.request.yaml" index 35474e4..3d6bacf 100644 --- "a/postman/collections/Fleetbase Storefront API/Checkout/Before \342\235\227.request.yaml" +++ "b/postman/collections/Fleetbase Storefront API/Checkout/Before \342\235\227.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: diff --git a/postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback via GET.queryParams.yaml b/postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback via GET.queryParams.yaml index 3289772..593c221 100644 --- a/postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback via GET.queryParams.yaml +++ b/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." diff --git a/postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback via GET.request.yaml b/postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback via GET.request.yaml index db2ce43..415ced2 100644 --- a/postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback via GET.request.yaml +++ b/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: diff --git a/postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback.params.yaml b/postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback.params.yaml index 0de0f8f..e9a54d8 100644 --- a/postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback.params.yaml +++ b/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"] diff --git a/postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback.request.yaml b/postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback.request.yaml index 92448f5..f7866ed 100644 --- a/postman/collections/Fleetbase Storefront API/Checkout/Capture QPay Callback.request.yaml +++ b/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: diff --git a/postman/collections/Fleetbase Storefront API/Checkout/Capture checkout as order.request.yaml b/postman/collections/Fleetbase Storefront API/Checkout/Capture checkout as order.request.yaml index b3595ce..8297536 100644 --- a/postman/collections/Fleetbase Storefront API/Checkout/Capture checkout as order.request.yaml +++ b/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 diff --git a/postman/collections/Fleetbase Storefront API/Checkout/Create Stripe Setup Intent.params.yaml b/postman/collections/Fleetbase Storefront API/Checkout/Create Stripe Setup Intent.params.yaml index 5159ab3..e7a022a 100644 --- a/postman/collections/Fleetbase Storefront API/Checkout/Create Stripe Setup Intent.params.yaml +++ b/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`." diff --git a/postman/collections/Fleetbase Storefront API/Checkout/Create Stripe Setup Intent.request.yaml b/postman/collections/Fleetbase Storefront API/Checkout/Create Stripe Setup Intent.request.yaml index 5d91ad4..e0384bd 100644 --- a/postman/collections/Fleetbase Storefront API/Checkout/Create Stripe Setup Intent.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Checkout/Create Stripe Setup Intent.request.yaml @@ -1,6 +1,8 @@ $kind: http-request description: |- - Creates a Stripe SetupIntent for a storefront customer. The response includes Stripe client data for saving a payment method. + Creates a Stripe SetupIntent for a storefront customer, for saving a payment method. + + Response: `{ setupIntent, clientSecret, defaultPaymentMethod, customerId }`. `defaultPaymentMethod` is null or `{ paymentMethodId, id, brand, last4, label, exp_month, exp_year, country, funding }`. Errors: `400` when Stripe is not set up or not configured correctly. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/checkouts/stripe-setup-intent" method: POST headers: diff --git a/postman/collections/Fleetbase Storefront API/Checkout/Get Checkout Status.queryParams.yaml b/postman/collections/Fleetbase Storefront API/Checkout/Get Checkout Status.queryParams.yaml index bb10818..2ead5f2 100644 --- a/postman/collections/Fleetbase Storefront API/Checkout/Get Checkout Status.queryParams.yaml +++ b/postman/collections/Fleetbase Storefront API/Checkout/Get Checkout Status.queryParams.yaml @@ -2,7 +2,13 @@ $kind: params fields: - name: checkout type: string - description: "Checkout value for this checkout request." + required: true + description: "Public checkout ID (`chkt_…`)." - name: token type: string - description: "Token used to authenticate or capture the checkout." + required: true + description: "The checkout's token. Both values must belong to the same checkout." + - name: verify + type: boolean + default: false + description: "QPay only. Ask QPay for the payment state when no payment is recorded yet. Limited to once every 5 seconds per checkout; calls within that window answer from the database." diff --git a/postman/collections/Fleetbase Storefront API/Checkout/Get Checkout Status.request.yaml b/postman/collections/Fleetbase Storefront API/Checkout/Get Checkout Status.request.yaml index 68ffed5..142fb28 100644 --- a/postman/collections/Fleetbase Storefront API/Checkout/Get Checkout Status.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Checkout/Get Checkout Status.request.yaml @@ -1,9 +1,14 @@ $kind: http-request description: |- - Returns the status of a checkout by checkout ID or token. + Returns the status of a checkout. The answer comes from the database: the payment is recorded the moment QPay's callback (or a `verify` check) confirms it. + + Response: `{ status, checkout, payment, order }`. `status` is `completed` once an order exists, `paid` for a QPay payment that is recorded but has no order yet, and `pending` otherwise. `order` is the order, or null. `payment` is null, or for QPay the recorded payment `{ payment_id, payment_status, payment_amount, payment_currency, payment_date, payment_wallet, recorded_at }`. A payment counts only when QPay reports it `PAID` for at least the invoiced amount. If a recorded payment still has no order after 15 seconds, this call creates the order. + + Errors: `400` without `checkout` and `token`, `404` when they don't match a checkout. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/checkouts/status" method: GET queryParams: checkout: "{{checkout_id}}" token: "{{checkout_token}}" + verify: "false" order: 5000 diff --git a/postman/collections/Fleetbase Storefront API/Checkout/Update Stripe Payment Intent.params.yaml b/postman/collections/Fleetbase Storefront API/Checkout/Update Stripe Payment Intent.params.yaml index d5868d7..77e5eb4 100644 --- a/postman/collections/Fleetbase Storefront API/Checkout/Update Stripe Payment Intent.params.yaml +++ b/postman/collections/Fleetbase Storefront API/Checkout/Update Stripe Payment Intent.params.yaml @@ -7,23 +7,23 @@ fields: - name: cart type: string required: true - description: "Cart public ID or unique identifier." + description: "Cart public ID or unique identifier. Only open carts are used." - name: payment_intent_id type: string required: true description: "Stripe PaymentIntent to update. `paymentIntent` and `paymentIntentId` are accepted aliases." - name: service_quote type: string - description: "Delivery service quote public ID. `serviceQuote` is an accepted alias." + description: "Delivery service quote public ID. Required unless `pickup` is true. `serviceQuote` is an accepted alias." - name: pickup type: boolean description: "Whether the order is a pickup order." - name: tip - type: number + type: string description: "Tip, as an amount or a percentage string such as `10%`." - name: delivery_tip - type: number + type: string description: "Delivery tip, as an amount or a percentage string. `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." diff --git a/postman/collections/Fleetbase Storefront API/Checkout/Update Stripe Payment Intent.request.yaml b/postman/collections/Fleetbase Storefront API/Checkout/Update Stripe Payment Intent.request.yaml index 3b72509..1255c80 100644 --- a/postman/collections/Fleetbase Storefront API/Checkout/Update Stripe Payment Intent.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Checkout/Update Stripe Payment Intent.request.yaml @@ -1,6 +1,10 @@ $kind: http-request description: |- - Recalculates and updates an existing Stripe PaymentIntent for the current cart and checkout options. The response includes refreshed Stripe client data and a new checkout token. + Recalculates and updates an existing Stripe PaymentIntent for the current cart and checkout options, and returns refreshed Stripe client data (plus `socket_token` when socket authentication is enabled). + + If a checkout is already linked to the PaymentIntent, it is updated in place: the response keeps the same `checkout` and `token`, and its promotion reservations are released and reserved again. A new checkout is created only when none is linked. Cash on delivery is not supported here. + + Errors: `422` when the PaymentIntent belongs to another customer's checkout, `400` when the PaymentIntent can no longer be updated (its status is not `requires_payment_method`, `requires_confirmation`, `requires_action` or `processing`) or a promo code cannot be applied. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/checkouts/stripe-update-payment-intent" method: PUT headers: diff --git a/postman/collections/Fleetbase Storefront API/Customer/Authenticate a Customer via SMS.request.yaml b/postman/collections/Fleetbase Storefront API/Customer/Authenticate a Customer via SMS.request.yaml index d063187..d36ae68 100644 --- a/postman/collections/Fleetbase Storefront API/Customer/Authenticate a Customer via SMS.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Customer/Authenticate a Customer via SMS.request.yaml @@ -1,6 +1,8 @@ $kind: http-request description: |- - Starts SMS authentication for an existing storefront customer. The customer receives a verification code that can be exchanged for an auth token. + Starts phone authentication for an existing storefront customer. A verification code is sent by SMS; if the SMS can't be sent and the customer has an email address, it's emailed instead. Exchange the code at `customers/verify-code`. + + `phone` is in E.164 format, with or without the leading `+` (no spaces or dashes). Response: `{ "status": "OK", "method": "sms" }`, or `"method": "email"` when the code was emailed. Errors (`400`): no customer with this phone, or the code could not be sent. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/customers/login-with-sms" method: POST headers: diff --git a/postman/collections/Fleetbase Storefront API/Customer/Create Customer Socket Token.params.yaml b/postman/collections/Fleetbase Storefront API/Customer/Create Customer Socket Token.params.yaml new file mode 100644 index 0000000..5162c44 --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Customer/Create Customer Socket Token.params.yaml @@ -0,0 +1,2 @@ +$kind: params +fields: [] diff --git a/postman/collections/Fleetbase Storefront API/Customer/Create Customer Socket Token.request.yaml b/postman/collections/Fleetbase Storefront API/Customer/Create Customer Socket Token.request.yaml new file mode 100644 index 0000000..4377496 --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Customer/Create Customer Socket Token.request.yaml @@ -0,0 +1,19 @@ +$kind: http-request +description: |- + Creates a short-lived token for the authenticated customer to authenticate the realtime (SocketCluster) connection. With it the customer may subscribe to their storefront's channel, their own checkouts (`checkout.{id}`) and the chats they take part in (`chat.{id}`, see Order Chat). Fetch a new one before `expires_at`. + + Response: `{ "token": "", "expires_in": 900, "expires_at": "2026-10-12T10:15:00+00:00" }`. `expires_in` is in seconds (900 by default, at most 3600). + + Errors: `404` when the server doesn't have socket authentication enabled (clients then connect anonymously), `401` without a valid `Customer-Token` or for a customer of another company. +url: "{{base_url}}/{{api_prefix}}/{{namespace}}/customers/socket-token" +method: POST +headers: + - key: Customer-Token + value: "{{customer_token}}" + - key: Content-Type + value: application/json +body: + type: json + content: |- + {} +order: 5150 diff --git a/postman/collections/Fleetbase Storefront API/Customer/Create a Customer.params.yaml b/postman/collections/Fleetbase Storefront API/Customer/Create a Customer.params.yaml index a04b25e..405c6b2 100644 --- a/postman/collections/Fleetbase Storefront API/Customer/Create a Customer.params.yaml +++ b/postman/collections/Fleetbase Storefront API/Customer/Create a Customer.params.yaml @@ -1,23 +1,22 @@ $kind: params fields: + - name: code + type: string + required: true + description: "Verification code from `customers/request-creation-code`." - name: name type: string required: true - description: "Display name for the resource." + description: "Customer's name." + - name: identity + type: string + description: "Email address or phone number the code was sent to. Defaults to `email`, then `phone`; at least one of the three is required." - name: email type: string - description: "Email address for the person or customer." + description: "Customer email address. Must be unique among the company's customers." - name: phone type: string - description: "Phone number for the person or customer." - - name: identity + description: "Customer phone number. Must be unique among the company's customers." + - name: photo type: string - required: true - description: "Email address or phone number used for authentication." - - name: password - type: string - description: "Password used to authenticate the customer." - - name: code - type: string - required: true - description: "Verification or status code." + description: "Profile photo, as a file public ID or a base64 image." diff --git a/postman/collections/Fleetbase Storefront API/Customer/List a customer orders.request.yaml b/postman/collections/Fleetbase Storefront API/Customer/List a customer orders.request.yaml index 4827fe7..7149694 100644 --- a/postman/collections/Fleetbase Storefront API/Customer/List a customer orders.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Customer/List a customer orders.request.yaml @@ -1,6 +1,8 @@ $kind: http-request description: |- Returns orders that belong to the authenticated storefront customer. Use pagination and filters to browse the customer order history. + + For a network key, a checkout across several stores appears once, as its master order (`meta.is_master_order`, `meta.related_orders`); the stores' own orders are left out. Use `GET orders/{id}/stores` for the per-store breakdown. Order `meta` can include `checkout_id`, `discount`, `promotions`, `payment_status`, `is_booking`, `booking_at` and `booking_has_items`. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/customers/orders" method: GET headers: diff --git a/postman/collections/Fleetbase Storefront API/Customer/Request Phone Verification.request.yaml b/postman/collections/Fleetbase Storefront API/Customer/Request Phone Verification.request.yaml index ef673f4..85c32b5 100644 --- a/postman/collections/Fleetbase Storefront API/Customer/Request Phone Verification.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Customer/Request Phone Verification.request.yaml @@ -1,6 +1,6 @@ $kind: http-request description: |- - Sends a verification code to a new phone number for the authenticated storefront customer. Fleetbase rejects numbers already assigned to another user. + Sends a verification code to a new phone number for the authenticated storefront customer. Fleetbase rejects numbers already assigned to another user. Response: `{ "status": "ok" }`. For an app store review account (listed in `STOREFRONT_REVIEW_ACCOUNTS`, with `STOREFRONT_BYPASS_VERIFICATION_CODE` set), no SMS is sent and the response is `{ "status": "ok", "method": "bypass" }`. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/customers/request-phone-verification" method: POST headers: diff --git a/postman/collections/Fleetbase Storefront API/Customer/Update Contact Customer Alias.params.yaml b/postman/collections/Fleetbase Storefront API/Customer/Update Contact Customer Alias.params.yaml index f89be5e..2a6b634 100644 --- a/postman/collections/Fleetbase Storefront API/Customer/Update Contact Customer Alias.params.yaml +++ b/postman/collections/Fleetbase Storefront API/Customer/Update Contact Customer Alias.params.yaml @@ -2,19 +2,22 @@ $kind: params fields: - name: name type: string - description: "Display name for the resource." + description: "Customer's name." + - name: title + type: string + description: "Customer's title." - name: email type: string - description: "Email address for the person or customer." + description: "Customer email address." - name: phone type: string - description: "Phone number for the person or customer." - - name: identity - type: string - description: "Email address or phone number used for authentication." - - name: password + description: "Customer phone number. To change a verified number, use `request-phone-verification` and `verify-phone-number`." + - name: place type: string - description: "Password used to authenticate the customer." - - name: code + description: "Public ID of one of the customer's places to make it their default address." + - name: photo type: string - description: "Verification or status code." + description: "Profile photo, as a file public ID or a base64 image; `REMOVE` deletes it." + - name: meta + type: object + description: "Custom metadata stored on the customer." diff --git a/postman/collections/Fleetbase Storefront API/Customer/Update a Customer.params.yaml b/postman/collections/Fleetbase Storefront API/Customer/Update a Customer.params.yaml index f89be5e..2a6b634 100644 --- a/postman/collections/Fleetbase Storefront API/Customer/Update a Customer.params.yaml +++ b/postman/collections/Fleetbase Storefront API/Customer/Update a Customer.params.yaml @@ -2,19 +2,22 @@ $kind: params fields: - name: name type: string - description: "Display name for the resource." + description: "Customer's name." + - name: title + type: string + description: "Customer's title." - name: email type: string - description: "Email address for the person or customer." + description: "Customer email address." - name: phone type: string - description: "Phone number for the person or customer." - - name: identity - type: string - description: "Email address or phone number used for authentication." - - name: password + description: "Customer phone number. To change a verified number, use `request-phone-verification` and `verify-phone-number`." + - name: place type: string - description: "Password used to authenticate the customer." - - name: code + description: "Public ID of one of the customer's places to make it their default address." + - name: photo type: string - description: "Verification or status code." + description: "Profile photo, as a file public ID or a base64 image; `REMOVE` deletes it." + - name: meta + type: object + description: "Custom metadata stored on the customer." diff --git a/postman/collections/Fleetbase Storefront API/Customer/Update a Customer.request.yaml b/postman/collections/Fleetbase Storefront API/Customer/Update a Customer.request.yaml index 9af910f..ae2f1c8 100644 --- a/postman/collections/Fleetbase Storefront API/Customer/Update a Customer.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Customer/Update a Customer.request.yaml @@ -10,5 +10,8 @@ headers: value: application/json body: type: json - content: "" + content: |- + { + "name": "Jane Doe" + } order: 8000 diff --git a/postman/collections/Fleetbase Storefront API/Customer/Verify Phone Number.params.yaml b/postman/collections/Fleetbase Storefront API/Customer/Verify Phone Number.params.yaml index b95d49d..1a1678b 100644 --- a/postman/collections/Fleetbase Storefront API/Customer/Verify Phone Number.params.yaml +++ b/postman/collections/Fleetbase Storefront API/Customer/Verify Phone Number.params.yaml @@ -4,3 +4,6 @@ fields: type: string required: true description: "Verification code sent to the pending phone number." + - name: phone + type: string + description: "The phone number being verified. Needed for app store review accounts, whose fixed code sets this number directly." diff --git a/postman/collections/Fleetbase Storefront API/Customer/Verify a SMS code.params.yaml b/postman/collections/Fleetbase Storefront API/Customer/Verify a SMS code.params.yaml index ded3c35..205a0d8 100644 --- a/postman/collections/Fleetbase Storefront API/Customer/Verify a SMS code.params.yaml +++ b/postman/collections/Fleetbase Storefront API/Customer/Verify a SMS code.params.yaml @@ -3,7 +3,7 @@ fields: - name: identity type: string required: true - description: "Customer email address or phone number being verified." + description: "Customer email address or phone number being verified. A phone number gets a leading `+` when it's missing." - name: code type: string required: true diff --git a/postman/collections/Fleetbase Storefront API/Customer/Verify a SMS code.request.yaml b/postman/collections/Fleetbase Storefront API/Customer/Verify a SMS code.request.yaml index 66ffa9c..29b70a6 100644 --- a/postman/collections/Fleetbase Storefront API/Customer/Verify a SMS code.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Customer/Verify a SMS code.request.yaml @@ -1,6 +1,10 @@ $kind: http-request description: |- - Verifies a storefront SMS or creation code. The response includes the customer profile and auth token when verification succeeds. + Verifies a code sent by SMS or email (sign-in or account creation). The response includes the customer profile and auth token when verification succeeds. + + App store review accounts: when the server sets `STOREFRONT_BYPASS_VERIFICATION_CODE` and lists the identity in `STOREFRONT_REVIEW_ACCOUNTS`, that fixed code is accepted for those identities only, without sending a message. + + Errors (`400`): no customer for the identity, or an invalid code. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/customers/verify-code" method: POST headers: diff --git a/postman/collections/Fleetbase Storefront API/Delivery Service Quote/.resources/object.yaml b/postman/collections/Fleetbase Storefront API/Delivery Service Quote/.resources/object.yaml index 98b2550..02744cd 100644 --- a/postman/collections/Fleetbase Storefront API/Delivery Service Quote/.resources/object.yaml +++ b/postman/collections/Fleetbase Storefront API/Delivery Service Quote/.resources/object.yaml @@ -1,27 +1,55 @@ $kind: object name: Delivery Service Quote description: |- - A delivery service quote prices delivery for a storefront cart and is consumed during checkout capture. + A delivery service quote prices delivery for a storefront cart and is used at checkout. example: | { "id": "service_quote_4fK2mQ8", + "service_rate": "service_rate_7Hq2xL9", + "service_rate_name": "Standard delivery", + "service_name": "Standard delivery", + "facilitator": null, + "request_id": "c2f1a7d4-2b8e-4c51-9d0a-6f3e1b2c4d5e", "amount": 950, "currency": "USD", + "items": [ + { "amount": 950, "currency": "USD", "details": "Base fee and distance" } + ], "meta": { "origin": "place_123", "destination": "place_456" - } + }, + "created_at": "2026-10-07T13:30:00Z", + "updated_at": "2026-10-07T13:30:00Z" } fields: - name: id type: string description: "Public identifier of the service quote." + - name: service_rate + type: string + description: "Service rate the quote was priced with." + - name: service_rate_name + type: string + description: "Name of the service rate." + - name: service_name + type: string + description: "Name of the delivery service." + - name: facilitator + type: string + description: "Integrated vendor that produced the quote, or null for the store's own rates." + - name: request_id + type: string + description: "Identifier of the quote request." - name: amount type: integer - description: "Quoted delivery amount." + description: "Quoted delivery amount in the currency's smallest unit." - name: currency type: currency description: "Quote currency code." + - name: items + type: array + description: "Line items that make up the quoted amount." - name: meta type: object - description: "Quote metadata, including origin and destination used by checkout." + description: "Origin and destination used for the quote. For a multi-store Network cart, `origin` is an array of place IDs." diff --git "a/postman/collections/Fleetbase Storefront API/Delivery Service Quote/Retrieve a Delivery Service Quote \342\235\227.queryParams.yaml" "b/postman/collections/Fleetbase Storefront API/Delivery Service Quote/Retrieve a Delivery Service Quote \342\235\227.queryParams.yaml" index 563e4e3..9c9e7c1 100644 --- "a/postman/collections/Fleetbase Storefront API/Delivery Service Quote/Retrieve a Delivery Service Quote \342\235\227.queryParams.yaml" +++ "b/postman/collections/Fleetbase Storefront API/Delivery Service Quote/Retrieve a Delivery Service Quote \342\235\227.queryParams.yaml" @@ -1,11 +1,30 @@ $kind: params fields: - - name: origin + - name: cart type: string - description: "Fallback store-location public ID, or comma-separated IDs for a multi-store cart. Cart line-item locations take precedence." + required: true + description: "Cart public ID or unique identifier. Network cart origins must belong to the corresponding member stores." - name: destination type: string - description: "Destination value for this delivery service quote request." - - name: cart + required: true + description: "Where to deliver: a place ID, store location ID, vehicle ID, food truck ID, or a `lat,lng` pair." + - name: origin type: string - description: "Cart public ID or unique identifier. Network cart origins must belong to the corresponding member stores." + description: "Where the delivery starts, in the same formats as `destination`. Required for a store key (a store location must belong to that store). For a network key it's optional: each cart line's store location is used, and `origin` (or comma-separated IDs) is only a fallback." + - name: facilitator + type: string + description: "Integrated vendor ID or provider to quote with instead of the store's own service rates." + - name: scheduled_at + type: timestamp + description: "Requested delivery time, forwarded to integrated vendors." + - name: service_type + type: string + description: "Service type, forwarded to integrated vendors." + - name: all + type: boolean + default: false + description: "Return every available quote as an array instead of the single best quote." + - name: is_route_optimized + type: boolean + default: true + description: "Whether the route through several stores is optimized when pricing a multi-store cart." diff --git "a/postman/collections/Fleetbase Storefront API/Delivery Service Quote/Retrieve a Delivery Service Quote \342\235\227.request.yaml" "b/postman/collections/Fleetbase Storefront API/Delivery Service Quote/Retrieve a Delivery Service Quote \342\235\227.request.yaml" index c3fdf56..c988539 100644 --- "a/postman/collections/Fleetbase Storefront API/Delivery Service Quote/Retrieve a Delivery Service Quote \342\235\227.request.yaml" +++ "b/postman/collections/Fleetbase Storefront API/Delivery Service Quote/Retrieve a Delivery Service Quote \342\235\227.request.yaml" @@ -1,6 +1,10 @@ $kind: http-request description: |- - Returns a delivery service quote for the supplied cart, origin, and destination. Use the quote during checkout to include delivery pricing. + Returns a delivery service quote for the supplied cart, origin, and destination. Use the quote's `id` as `service_quote` at checkout to include delivery pricing. Returns a single quote, or an array with `all=1`. + + For a multi-store Network cart the distance is summed leg by leg: from the farthest store, to the nearest next store, then to the customer. + + Errors: `422` with `code: "cart_items_unavailable"` and `items: [{ id, product_id, name }]` when a product in the cart was deleted, made unavailable or unpublished, or a line's food truck or store location no longer exists (show it to the customer and send them back to the cart). `400` for a missing origin or destination, no service rates, or an unknown integrated vendor. `422` when a Network store location is not available in the network. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/service-quotes/from-cart" method: GET queryParams: diff --git a/postman/collections/Fleetbase Storefront API/Food Trucks/.resources/definition.yaml b/postman/collections/Fleetbase Storefront API/Food Trucks/.resources/definition.yaml index 332aa75..e311f5e 100644 --- a/postman/collections/Fleetbase Storefront API/Food Trucks/.resources/definition.yaml +++ b/postman/collections/Fleetbase Storefront API/Food Trucks/.resources/definition.yaml @@ -1,4 +1,6 @@ $kind: collection description: |- - Food trucks expose mobile storefront availability backed by FleetOps vehicles, zones, and service areas. Use food truck endpoints to discover mobile vendors and their current operating state. + Food trucks expose mobile storefront availability backed by FleetOps vehicles, zones, and service areas. Use food truck endpoints to discover mobile vendors, where they are, whether they're online, and the catalogs (menus) they sell from. + + A store key returns that store's trucks. A network key returns the trucks of the network's active member stores and the trucks the network runs itself. order: 5500 diff --git a/postman/collections/Fleetbase Storefront API/Food Trucks/.resources/object.yaml b/postman/collections/Fleetbase Storefront API/Food Trucks/.resources/object.yaml index 2afcff9..5d255ed 100644 --- a/postman/collections/Fleetbase Storefront API/Food Trucks/.resources/object.yaml +++ b/postman/collections/Fleetbase Storefront API/Food Trucks/.resources/object.yaml @@ -5,12 +5,47 @@ description: |- example: | { "id": "food_truck_8Fq2mL1", - "vehicle": null, - "service_area": null, - "zone": null, - "catalogs": [], - "location": null, - "online": false, + "store": { + "id": "store_3Xb9kL2", + "name": "Acme Market", + "logo_url": "https://files.example.com/logo.png", + "currency": "USD", + "options": { "map_marker": "store", "reviews_enabled": true } + }, + "vehicle": { "id": "vehicle_6Tq1nP8", "plate_number": "GBB-1006", "online": true }, + "service_area": { "id": "service_area_2Kd8mQ4", "name": "Singapore Central" }, + "zone": { "id": "zone_9Lx3vR7", "name": "CBD" }, + "catalogs": [ + { + "id": "catalog_4Hn8zB2", + "name": "Truck menu", + "description": null, + "status": "published", + "categories": [ + { + "id": "category_7Pq2wE5", + "name": "Drinks", + "products": [ + { + "id": "product_1Ab2Cd3", + "name": "Cold Brew", + "price": 450, + "sale_price": null, + "is_on_sale": false, + "is_available": true, + "store_price": 500, + "catalog_price": 450, + "catalog_available": null + } + ] + } + ], + "created_at": "2026-05-07T09:30:00Z", + "updated_at": "2026-05-07T09:30:00Z" + } + ], + "location": { "type": "Point", "coordinates": [103.8515, 1.2835] }, + "online": true, "status": "active", "created_at": "2026-05-07T09:30:00Z", "updated_at": "2026-05-07T09:30:00Z" @@ -19,6 +54,12 @@ fields: - name: id type: string description: "Public identifier of the food truck." + - name: store + type: object + description: "The store the truck sells for: `id`, `name`, `logo_url`, `currency` and `options` (including `map_marker` and `reviews_enabled`)." + - name: network + type: object + description: "For a truck the network runs itself, the network: `id`, `name`, `logo_url`. Returned by Query Food Trucks only." - name: vehicle type: object description: "FleetOps vehicle assigned to the food truck." @@ -30,10 +71,10 @@ fields: description: "Zone assigned to the food truck." - name: catalogs type: array of objects - description: "Catalogs available for the food truck." + description: "Catalogs (menus) the truck sells from, each with `categories[].products[]`. A product's `price`, `is_on_sale` and `is_available` are the values for this catalog: a catalog price replaces the store price (and removes a sale price), and a catalog can mark a product unavailable. `store_price`, `catalog_price` and `catalog_available` show both sides. Pass the catalog's `id` as `catalog` when adding the product to a cart." - name: location type: object - description: "Current vehicle location." + description: "Current vehicle location, as a GeoJSON point." - name: online type: boolean description: "Whether the assigned vehicle is online." diff --git a/postman/collections/Fleetbase Storefront API/Food Trucks/Query Food Trucks.queryParams.yaml b/postman/collections/Fleetbase Storefront API/Food Trucks/Query Food Trucks.queryParams.yaml index 4112244..ad799ea 100644 --- a/postman/collections/Fleetbase Storefront API/Food Trucks/Query Food Trucks.queryParams.yaml +++ b/postman/collections/Fleetbase Storefront API/Food Trucks/Query Food Trucks.queryParams.yaml @@ -1,11 +1,11 @@ $kind: params fields: - name: limit - type: string - description: "Limit value for this food trucks request." + type: integer + description: "Maximum number of trucks to return; `-1` returns all." - name: offset - type: string - description: "Offset value for this food trucks request." + type: integer + description: "Number of trucks to skip." - name: sort type: string - description: "Sort value for this food trucks request." + description: "Field to sort by; prefix with `-` for descending." diff --git a/postman/collections/Fleetbase Storefront API/Food Trucks/Query Food Trucks.request.yaml b/postman/collections/Fleetbase Storefront API/Food Trucks/Query Food Trucks.request.yaml index 7fcb5d0..3f6d036 100644 --- a/postman/collections/Fleetbase Storefront API/Food Trucks/Query Food Trucks.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Food Trucks/Query Food Trucks.request.yaml @@ -1,5 +1,6 @@ $kind: http-request -description: Query Food Trucks +description: |- + Lists the food trucks of the storefront: a store key returns that store's trucks; a network key returns the active member stores' trucks and the network's own. Each truck includes its store, vehicle, zone, service area and catalogs. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/food-trucks" method: GET queryParams: diff --git a/postman/collections/Fleetbase Storefront API/Food Trucks/Retrieve Food Truck.request.yaml b/postman/collections/Fleetbase Storefront API/Food Trucks/Retrieve Food Truck.request.yaml index 06d109e..111a754 100644 --- a/postman/collections/Fleetbase Storefront API/Food Trucks/Retrieve Food Truck.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Food Trucks/Retrieve Food Truck.request.yaml @@ -1,5 +1,6 @@ $kind: http-request -description: Retrieve Food Truck +description: |- + Retrieves one food truck. Only a truck of this storefront is found: the store's own, or for a network key an active member store's or the network's. Any other truck returns `404`. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/food-trucks/{{food_truck_id}}" method: GET order: 2000 diff --git a/postman/collections/Fleetbase Storefront API/Notifications/.resources/object.yaml b/postman/collections/Fleetbase Storefront API/Notifications/.resources/object.yaml index 498e670..5d183c1 100644 --- a/postman/collections/Fleetbase Storefront API/Notifications/.resources/object.yaml +++ b/postman/collections/Fleetbase Storefront API/Notifications/.resources/object.yaml @@ -24,7 +24,7 @@ fields: description: "Notification id (uuid)." - name: type type: string - description: "What the notification is about, e.g. `order_accepted`, `order_enroute`, `order_nearby`, `order_completed`, `order_canceled`, `order_ready`, `order_driver_assigned`, `promotional` or `campaign`." + description: "What the notification is about, e.g. `order_accepted`, `order_enroute`, `order_nearby`, `order_completed`, `order_canceled`, `order_ready`, `order_driver_assigned`, `order_activity`, `order_chat_message`, `promotional` or `campaign`. `order_activity` covers order steps that have no notification of their own (and every step of a booking after it's requested); its title is the step's label. `order_chat_message` is a message from the driver (`data` has `order`, `order_id`, `chat_id`, `message_id`, `store_id`, `network_id`); it's always delivered, whatever the `order_updates` preference." - name: title type: string description: "Notification title." diff --git a/postman/collections/Fleetbase Storefront API/Order Chat/.resources/definition.yaml b/postman/collections/Fleetbase Storefront API/Order Chat/.resources/definition.yaml new file mode 100644 index 0000000..96270b7 --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Order Chat/.resources/definition.yaml @@ -0,0 +1,8 @@ +$kind: collection +description: |- + Chat between a customer and the driver delivering their order. The chat opens when a driver is assigned and closes, read-only, once the order is completed, canceled or expired. Every request needs the `Customer-Token` header of the customer who placed the order. + + New messages and read receipts are broadcast in realtime on the SocketCluster channel given by the chat's `channel` (`chat.{chat id}`) as `chat_message.*` and `chat_receipt.*` events. The driver's messages also reach the customer as `order_chat_message` notifications. When the server requires socket authentication, subscribe with a token from `POST customers/socket-token`. + + Sending a message or marking the chat read returns `403` when the customer isn't part of the chat. Responses: `Send Order Chat Message` returns `{ "message": {…} }`, `List Order Chat Messages` returns `{ "messages": [...] }` and `Mark Order Chat as Read` returns `{ "read": n }`. +order: 7500 diff --git a/postman/collections/Fleetbase Storefront API/Order Chat/.resources/object.yaml b/postman/collections/Fleetbase Storefront API/Order Chat/.resources/object.yaml new file mode 100644 index 0000000..82e8b4d --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Order Chat/.resources/object.yaml @@ -0,0 +1,54 @@ +$kind: object +name: Order Chat +description: |- + The chat for an order, with its participants and latest messages (oldest first). Messages are `{ id, content, sender: { id, role, name }, is_mine, attachments: [{ id, url, type }], read, created_at }`. +example: | + { + "id": "chat_5Nq8vR2", + "channel": "chat.chat_5Nq8vR2", + "order": "order_9Ks2mP1", + "status": "open", + "me": "chat_participant_2Lm4kQ7", + "participants": [ + { "id": "chat_participant_2Lm4kQ7", "role": "customer", "name": "Ada Buyer", "avatar_url": null, "is_online": true }, + { "id": "chat_participant_7Rt3pW9", "role": "driver", "name": "Ravi Kumar", "avatar_url": "https://files.example.com/ravi.png", "is_online": true } + ], + "messages": [ + { + "id": "chat_message_3Hk9mL2", + "content": "Picked up your order, about 8 minutes away.", + "sender": { "id": "chat_participant_7Rt3pW9", "role": "driver", "name": "Ravi Kumar" }, + "is_mine": false, + "attachments": [], + "read": true, + "created_at": "2026-10-07T13:52:00Z" + } + ], + "unread_count": 0 + } +fields: + - name: id + type: string + description: "Public identifier of the chat." + - name: channel + type: string + description: "SocketCluster channel to subscribe to for live messages." + - name: order + type: string + description: "Public identifier of the order." + - name: status + type: enum + values: ["open", "closed"] + description: "`closed` once the order is completed, canceled or expired; messages can still be read." + - name: me + type: string + description: "The requesting customer's participant ID." + - name: participants + type: array of objects + description: "`id`, `role` (`customer` or `driver`), `name`, `avatar_url` and `is_online`." + - name: messages + type: array of objects + description: "The latest messages, oldest first." + - name: unread_count + type: integer + description: "Messages from the driver the customer has not read." diff --git a/postman/collections/Fleetbase Storefront API/Order Chat/Get Order Chat.request.yaml b/postman/collections/Fleetbase Storefront API/Order Chat/Get Order Chat.request.yaml new file mode 100644 index 0000000..5bee352 --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Order Chat/Get Order Chat.request.yaml @@ -0,0 +1,21 @@ +$kind: http-request +description: |- + Returns the order's chat (see the Order Chat object) with its latest 50 messages, oldest first, opening it when a driver is assigned. `unread_count` counts messages from others the customer hasn't read. Subscribe to `channel` for live messages. + + Refusals: `401` without a customer token, `404` for an order not placed through this storefront, `403` for another customer's order, and `409` with `"reason": "driver_not_assigned"` when no driver is assigned yet (or the order finished without ever having a chat). +url: "{{base_url}}/{{api_prefix}}/{{namespace}}/orders/{{chat_order_id}}/chat" +method: GET +headers: + - key: Customer-Token + value: "{{customer_token}}" +scripts: + - type: beforeRequest + code: |- + // Uses {{chat_order_id}} when the environment has an order with a driver assigned. + // Otherwise it addresses {{order_id}} (no driver yet) and documents the 409 refusal. + if (!pm.environment.get('chat_order_id')) { + pm.variables.set('chat_order_id', pm.environment.get('order_id') || 'order_missing'); + pm.variables.set('expected_status', pm.environment.get('order_id') ? 409 : 404); + } + language: text/javascript +order: 1000 diff --git a/postman/collections/Fleetbase Storefront API/Order Chat/List Order Chat Messages.queryParams.yaml b/postman/collections/Fleetbase Storefront API/Order Chat/List Order Chat Messages.queryParams.yaml new file mode 100644 index 0000000..6bcaebd --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Order Chat/List Order Chat Messages.queryParams.yaml @@ -0,0 +1,8 @@ +$kind: params +fields: + - name: before + type: string + description: "Message ID; only messages sent before it are returned." + - name: limit + type: integer + description: "Maximum number of messages. Defaults to 50; values above 100 are treated as 100." diff --git a/postman/collections/Fleetbase Storefront API/Order Chat/List Order Chat Messages.request.yaml b/postman/collections/Fleetbase Storefront API/Order Chat/List Order Chat Messages.request.yaml new file mode 100644 index 0000000..cc09a82 --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Order Chat/List Order Chat Messages.request.yaml @@ -0,0 +1,24 @@ +$kind: http-request +description: |- + Older messages of the order's chat, oldest first, as `{ "messages": [...] }`. Pass the oldest message you have as `before` to page back. A `before` that isn't in this chat returns `404`. + + Refusals: `401` without a customer token, `404` for an order not placed through this storefront, `403` for another customer's order, and `409` with `"reason": "driver_not_assigned"` when no driver is assigned yet (or the order finished without ever having a chat). +url: "{{base_url}}/{{api_prefix}}/{{namespace}}/orders/{{chat_order_id}}/chat/messages" +method: GET +headers: + - key: Customer-Token + value: "{{customer_token}}" +queryParams: + before: "" + limit: "50" +scripts: + - type: beforeRequest + code: |- + // Uses {{chat_order_id}} when the environment has an order with a driver assigned. + // Otherwise it addresses {{order_id}} (no driver yet) and documents the 409 refusal. + if (!pm.environment.get('chat_order_id')) { + pm.variables.set('chat_order_id', pm.environment.get('order_id') || 'order_missing'); + pm.variables.set('expected_status', pm.environment.get('order_id') ? 409 : 404); + } + language: text/javascript +order: 2000 diff --git a/postman/collections/Fleetbase Storefront API/Order Chat/Mark Order Chat as Read.request.yaml b/postman/collections/Fleetbase Storefront API/Order Chat/Mark Order Chat as Read.request.yaml new file mode 100644 index 0000000..799887a --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Order Chat/Mark Order Chat as Read.request.yaml @@ -0,0 +1,21 @@ +$kind: http-request +description: |- + Marks the driver's messages as read for the customer and returns `{ "read": n }`, the number of messages marked. The driver sees the read receipts on the chat channel. + + Refusals: `401` without a customer token, `404` for an order not placed through this storefront, `403` for another customer's order, and `409` with `"reason": "driver_not_assigned"` before a driver is assigned. +url: "{{base_url}}/{{api_prefix}}/{{namespace}}/orders/{{chat_order_id}}/chat/read" +method: POST +headers: + - key: Customer-Token + value: "{{customer_token}}" +scripts: + - type: beforeRequest + code: |- + // Uses {{chat_order_id}} when the environment has an order with a driver assigned. + // Otherwise it addresses {{order_id}} (no driver yet) and documents the 409 refusal. + if (!pm.environment.get('chat_order_id')) { + pm.variables.set('chat_order_id', pm.environment.get('order_id') || 'order_missing'); + pm.variables.set('expected_status', pm.environment.get('order_id') ? 409 : 404); + } + language: text/javascript +order: 4000 diff --git a/postman/collections/Fleetbase Storefront API/Order Chat/Send Order Chat Message.params.yaml b/postman/collections/Fleetbase Storefront API/Order Chat/Send Order Chat Message.params.yaml new file mode 100644 index 0000000..dcf97f2 --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Order Chat/Send Order Chat Message.params.yaml @@ -0,0 +1,8 @@ +$kind: params +fields: + - name: content + type: string + description: "Message text, up to 2000 characters. Required without `files`." + - name: files + type: array of objects + description: "Up to 4 photos, each `{ \"data\": base64, \"type\": \"image/jpeg\" }`. `data` and `type` are required for each file, and `type` must be an image type (`image/…`). Required without `content`. Invalid input returns `422`." diff --git a/postman/collections/Fleetbase Storefront API/Order Chat/Send Order Chat Message.request.yaml b/postman/collections/Fleetbase Storefront API/Order Chat/Send Order Chat Message.request.yaml new file mode 100644 index 0000000..39db1ad --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Order Chat/Send Order Chat Message.request.yaml @@ -0,0 +1,29 @@ +$kind: http-request +description: |- + Sends a message to the driver and returns `{ "message": Message }`. Send `content`, `files` (photos), or both. The driver is notified and the message is broadcast on the chat channel. Once the order is finished the chat is read-only and sending returns `423` with `"reason": "chat_closed"`. + + Refusals: `401` without a customer token, `404` for an order not placed through this storefront, `403` for another customer's order, and `409` with `"reason": "driver_not_assigned"` before a driver is assigned. +url: "{{base_url}}/{{api_prefix}}/{{namespace}}/orders/{{chat_order_id}}/chat/messages" +method: POST +headers: + - key: Customer-Token + value: "{{customer_token}}" + - key: Content-Type + value: application/json +body: + type: json + content: |- + { + "content": "I'm in tower B, unit 08-112." + } +scripts: + - type: beforeRequest + code: |- + // Uses {{chat_order_id}} when the environment has an order with a driver assigned. + // Otherwise it addresses {{order_id}} (no driver yet) and documents the 409 refusal. + if (!pm.environment.get('chat_order_id')) { + pm.variables.set('chat_order_id', pm.environment.get('order_id') || 'order_missing'); + pm.variables.set('expected_status', pm.environment.get('order_id') ? 409 : 404); + } + language: text/javascript +order: 3000 diff --git a/postman/collections/Fleetbase Storefront API/Orders/.resources/definition.yaml b/postman/collections/Fleetbase Storefront API/Orders/.resources/definition.yaml index 1cc872c..35b0d02 100644 --- a/postman/collections/Fleetbase Storefront API/Orders/.resources/definition.yaml +++ b/postman/collections/Fleetbase Storefront API/Orders/.resources/definition.yaml @@ -1,4 +1,4 @@ $kind: collection description: |- - Storefront order endpoints expose customer-facing actions after checkout. Use them to mark pickup orders complete and retrieve receipts for supported payment methods. + Storefront order endpoints expose customer-facing actions after checkout: follow an order's progress through its activity flow, see each store's part of a multi-store Network order, mark pickup orders complete, and retrieve receipts for supported payment methods. order: 7000 diff --git a/postman/collections/Fleetbase Storefront API/Orders/.resources/object.yaml b/postman/collections/Fleetbase Storefront API/Orders/.resources/object.yaml index be3f4ab..93b280f 100644 --- a/postman/collections/Fleetbase Storefront API/Orders/.resources/object.yaml +++ b/postman/collections/Fleetbase Storefront API/Orders/.resources/object.yaml @@ -45,7 +45,7 @@ fields: description: "Customer associated with the order." - name: meta type: object - description: "Storefront checkout, payment, totals, and fulfillment metadata. `discount` is the total promotion discount (minor units) and `promotions` lists the applied promotions with their amounts; multi-store child orders carry their store's share of the item discount." + description: "Storefront checkout, payment, totals, and fulfillment metadata. `discount` is the total promotion discount (minor units) and `promotions` lists the applied promotions with their amounts; multi-store child orders carry their store's share of the item discount. Also: `payment_status`, `subtotal`, `tip`; booking orders carry `is_booking`, `booking_at` (ISO 8601) and `booking_has_items`; a multi-store Network checkout creates a master order (`is_master_order`, `related_orders`) whose store orders carry `master_order_id`." - name: notes type: string description: "Order notes supplied during checkout capture." diff --git a/postman/collections/Fleetbase Storefront API/Orders/Get Order Activity Flow.request.yaml b/postman/collections/Fleetbase Storefront API/Orders/Get Order Activity Flow.request.yaml new file mode 100644 index 0000000..d0de9b4 --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Orders/Get Order Activity Flow.request.yaml @@ -0,0 +1,13 @@ +$kind: http-request +description: |- + 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. +url: "{{base_url}}/{{api_prefix}}/{{namespace}}/orders/{{order_id}}/activity-flow" +method: GET +headers: + - key: Customer-Token + value: "{{customer_token}}" +order: 3000 diff --git a/postman/collections/Fleetbase Storefront API/Orders/Get Order Stores.request.yaml b/postman/collections/Fleetbase Storefront API/Orders/Get Order Stores.request.yaml new file mode 100644 index 0000000..e5b0423 --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Orders/Get Order Stores.request.yaml @@ -0,0 +1,13 @@ +$kind: http-request +description: |- + 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. +url: "{{base_url}}/{{api_prefix}}/{{namespace}}/orders/{{order_id}}/stores" +method: GET +headers: + - key: Customer-Token + value: "{{customer_token}}" +order: 4000 diff --git a/postman/collections/Fleetbase Storefront API/Products/.resources/object.yaml b/postman/collections/Fleetbase Storefront API/Products/.resources/object.yaml index 8f97d54..0db622c 100644 --- a/postman/collections/Fleetbase Storefront API/Products/.resources/object.yaml +++ b/postman/collections/Fleetbase Storefront API/Products/.resources/object.yaml @@ -18,11 +18,23 @@ example: | "is_bookable": false, "is_available": true, "tags": ["coffee"], - "status": "active", + "status": "published", "meta": {}, "slug": "cold-brew", "translations": [], - "addon_categories": [], + "addon_categories": [ + { + "id": "category_2Fd8kL1", + "name": "Extras", + "description": null, + "is_required": false, + "max_selectable": 2, + "excluded_addons": [], + "addons": [ + { "id": "product_addon_5Gh7jK2", "name": "Oat milk", "description": null, "price": 80, "sale_price": null, "is_on_sale": false } + ] + } + ], "variants": [], "images": [], "videos": [], @@ -70,7 +82,7 @@ fields: description: "Arbitrary metadata stored with the product." - name: addon_categories type: array of objects - description: "Addon categories available for the product." + description: "Addon categories available for the product: `id`, `name`, `description`, `is_required` (the customer must choose at least one), `max_selectable` (most add-ons that can be chosen, or null for no limit), `excluded_addons` and `addons`." - name: variants type: array of objects description: "Product variants and options." diff --git a/postman/collections/Fleetbase Storefront API/Products/Retrieve a Product.request.yaml b/postman/collections/Fleetbase Storefront API/Products/Retrieve a Product.request.yaml index ba1525a..60a6c8d 100644 --- a/postman/collections/Fleetbase Storefront API/Products/Retrieve a Product.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Products/Retrieve a Product.request.yaml @@ -1,6 +1,6 @@ $kind: http-request description: |- - Retrieves a single storefront product by ID. The response includes product details, pricing, variants, and related catalog data when available. + Retrieves a single storefront product by ID, with its details, pricing, variants and add-on categories (`is_required`, `max_selectable`). With a network key, only published, available products of active member stores are found. A product outside the storefront returns `404`. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/products/{{product_id}}" method: GET order: 3000 \ No newline at end of file diff --git a/postman/collections/Fleetbase Storefront API/Promotions/.resources/object.yaml b/postman/collections/Fleetbase Storefront API/Promotions/.resources/object.yaml index 9e090fe..fe86675 100644 --- a/postman/collections/Fleetbase Storefront API/Promotions/.resources/object.yaml +++ b/postman/collections/Fleetbase Storefront API/Promotions/.resources/object.yaml @@ -1,20 +1,24 @@ $kind: object name: Promotion description: |- - A live, public promotion of the store (or, with a network key, of the network or one of its member stores). Money values are integers in the currency's minor unit, like cart subtotals. Promo codes are never included. + A live, public promotion of the store (or, with a network key, of the network or one of its member stores). Money values are integers in the currency's minor unit, like cart subtotals. `code` is a code customers can share (never a single-use or customer-specific one); `availability` and `next_starts_at` say whether it applies right now. example: | { "id": "promotion_7Hq2xL9", "name": "Weekday lunch 20% off", "description": "20% off mains, weekdays 11:00-14:00.", "trigger": "automatic", + "code": null, + "availability": "scheduled", + "next_starts_at": "2026-10-08T15:00:00Z", + "owner": { "type": "store", "id": "store_3Xb9kL2", "name": "Corner Bistro", "logo_url": "https://files.example.com/bistro.png" }, "type": "percentage", "value": 20, "max_discount_amount": 1000, "currency": "USD", "min_subtotal": 1500, "min_items": null, - "applies_to": { "categories": ["category_uuid"] }, + "applies_to": { "categories": ["category_8Lq2nT4"] }, "bogo_config": null, "first_order_only": false, "usage_limit_per_customer": 1, @@ -42,6 +46,19 @@ fields: type: enum values: ["automatic", "code"] description: "`automatic` promotions apply to every eligible cart; `code` promotions need a promo code." + - name: code + type: string + description: "For `code` promotions, an active promo code customers can share and enter in the cart. Null for automatic promotions and when only single-use or customer-specific codes exist." + - name: availability + type: enum + values: ["live", "scheduled", "ended", "inactive"] + description: "`live` applies now; `scheduled` is active but outside its dates or weekly schedule; `ended` is past `ends_at` or ended. Paused promotions are not returned by the public API, so `inactive` doesn't appear here." + - name: next_starts_at + type: timestamp + description: "For `scheduled` promotions, when it next starts applying (looking up to a week ahead). Null otherwise." + - name: owner + type: object + description: "Who runs it: `type` (`store` or `network`), `id`, `name` and `logo_url`." - name: type type: enum values: ["percentage", "fixed_amount", "free_delivery", "bogo"] @@ -63,7 +80,7 @@ fields: description: "Minimum number of targeted items." - name: applies_to type: object - description: "Targeting: `products`, `categories`, `stores`, `exclude_products` and `exclude_categories` identifier lists. Empty means the whole cart (of the owning store, for store promotions)." + description: "Targeting: `products`, `categories`, `stores`, `exclude_products` and `exclude_categories` lists of public IDs. Empty means the whole cart (of the owning store, for store promotions)." - name: bogo_config type: object description: "For `bogo`: `buy_quantity`, `get_quantity` and `discount_percent` (100 means free). The cheapest units of each group are discounted." diff --git a/postman/collections/Fleetbase Storefront API/Promotions/Query Promotions.queryParams.yaml b/postman/collections/Fleetbase Storefront API/Promotions/Query Promotions.queryParams.yaml index b5b6240..2b1b32c 100644 --- a/postman/collections/Fleetbase Storefront API/Promotions/Query Promotions.queryParams.yaml +++ b/postman/collections/Fleetbase Storefront API/Promotions/Query Promotions.queryParams.yaml @@ -3,3 +3,6 @@ fields: - name: store type: string description: "Network member store public ID, to only list that store's promotions. Ignored for store keys." + - name: include + type: string + description: "`scheduled` to also list active promotions that are outside their dates or weekly schedule right now (`availability: scheduled`), e.g. for an \"upcoming offers\" list." diff --git a/postman/collections/Fleetbase Storefront API/Promotions/Query Promotions.request.yaml b/postman/collections/Fleetbase Storefront API/Promotions/Query Promotions.request.yaml index 5d95207..55158c3 100644 --- a/postman/collections/Fleetbase Storefront API/Promotions/Query Promotions.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Promotions/Query Promotions.request.yaml @@ -1,10 +1,11 @@ $kind: http-request description: |- - Lists the storefront's live, public promotions: active, inside their date range and weekly schedule. With a network key the network's promotions and those of its member stores are returned; pass `store` to only list one member store's. + Lists the storefront's live, public promotions: active, inside their date range and weekly schedule. Pass `include=scheduled` to also list active promotions that start later or are outside their weekly hours. With a network key the network's promotions and those of its member stores are returned; pass `store` to only list one member store's. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/promotions" method: GET queryParams: store: "" + include: "" scripts: - type: afterResponse code: |- diff --git a/postman/collections/Fleetbase Storefront API/Promotions/Retrieve a Promotion.request.yaml b/postman/collections/Fleetbase Storefront API/Promotions/Retrieve a Promotion.request.yaml index c950312..6364f1c 100644 --- a/postman/collections/Fleetbase Storefront API/Promotions/Retrieve a Promotion.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Promotions/Retrieve a Promotion.request.yaml @@ -1,6 +1,6 @@ $kind: http-request description: |- - Retrieves one live, public promotion of the storefront. Returns `404` for promotions that are not active, not public, outside their schedule, or owned by another storefront. + Retrieves one public promotion of the storefront, including ones that are scheduled or have ended, so a shared link still explains the offer; check `availability`. Returns `404` for promotions that are paused, not public, or owned by another storefront. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/promotions/{{promotion_id}}" method: GET scripts: diff --git a/postman/collections/Fleetbase Storefront API/Reviews/.resources/definition.yaml b/postman/collections/Fleetbase Storefront API/Reviews/.resources/definition.yaml index eaae823..1e69f84 100644 --- a/postman/collections/Fleetbase Storefront API/Reviews/.resources/definition.yaml +++ b/postman/collections/Fleetbase Storefront API/Reviews/.resources/definition.yaml @@ -1,4 +1,8 @@ $kind: collection description: |- - Reviews capture customer ratings and feedback for storefront resources. Use review endpoints to create, retrieve, count, query, and remove customer feedback. + Reviews follow the store's or network's `reviews_enabled` option (on by default for a store, off by default for a network). When reviews are off, lists are empty, counts are 0, eligibility answers `reviews_disabled` and creating a review returns `403`. + + Reviews capture customer ratings and feedback for stores and products. Anyone can read a store's reviews and rating counts. Writing one is limited to verified purchases: the customer needs a completed order with the store (or containing the product) that they have not reviewed yet. Call Check Review Eligibility before offering "Write a review" so the app can explain why when it can't. Customers can delete their own reviews. + + Reviews are public, so the reviewer is shown by first name and last initial only, without contact details. order: 9000 diff --git a/postman/collections/Fleetbase Storefront API/Reviews/.resources/object.yaml b/postman/collections/Fleetbase Storefront API/Reviews/.resources/object.yaml index f2864d0..9060f26 100644 --- a/postman/collections/Fleetbase Storefront API/Reviews/.resources/object.yaml +++ b/postman/collections/Fleetbase Storefront API/Reviews/.resources/object.yaml @@ -1,16 +1,27 @@ $kind: object name: Review description: |- - A review stores a customer rating, written content, photos, and the reviewed subject. + A customer's rating and written review of a store or product, with optional photos. `verified` is true for reviews written from a completed order. example: | { "id": "review_2xK9mQ1", "subject_id": "store_3Xb9kL2", + "subject_type": "store", + "verified": true, + "is_mine": false, "rating": 5, "content": "Great pickup experience.", - "customer": null, + "customer": { + "id": "customer_8Jk2mP1", + "name": "Ada B.", + "photo_url": "https://files.example.com/ada.png", + "reviews_count": 3, + "uploads_count": 1 + }, "slug": "great-pickup-experience", - "photos": [], + "photos": [ + { "id": "file_4Lm2nQ8", "filename": "pickup.jpg", "type": "image/jpeg", "caption": null, "url": "https://files.example.com/pickup.jpg" } + ], "created_at": "2026-05-07T09:30:00Z", "updated_at": "2026-05-07T09:30:00Z" } @@ -20,22 +31,32 @@ fields: description: "Public identifier of the review." - name: subject_id type: string - description: "Identifier of the reviewed subject." + description: "Public identifier of the reviewed store or product." + - name: subject_type + type: enum + values: ["store", "product"] + description: "What was reviewed." + - name: verified + type: boolean + description: "Whether the review was written from a completed order (a verified purchase)." + - name: is_mine + type: boolean + description: "Whether the customer making the request wrote it. Only true when the request carries that customer's `Customer-Token`." - name: rating type: integer - description: "Numeric review rating." + description: "Rating from 1 to 5." - name: content type: string description: "Review text." - name: customer type: object - description: "Customer that created the review." + description: "The reviewer: `id`, `name` as first name and last initial (e.g. `Ada B.`), `photo_url`, `reviews_count` and `uploads_count`. Email and phone are never included." - name: slug type: string description: "URL-friendly review slug." - name: photos type: array of objects - description: "Photos attached to the review." + description: "Photos attached to the review: `id`, `filename`, `type`, `caption` and `url`." - name: created_at type: timestamp description: "Time the review was created." diff --git a/postman/collections/Fleetbase Storefront API/Reviews/Check Review Eligibility.queryParams.yaml b/postman/collections/Fleetbase Storefront API/Reviews/Check Review Eligibility.queryParams.yaml new file mode 100644 index 0000000..63bae23 --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Reviews/Check Review Eligibility.queryParams.yaml @@ -0,0 +1,9 @@ +$kind: params +fields: + - name: subject + type: string + required: true + description: "Public identifier of the store or product to review." + - name: order + type: string + description: "A specific completed order to review, e.g. from the order screen. Without it the most recent unreviewed completed order is used." diff --git a/postman/collections/Fleetbase Storefront API/Reviews/Check Review Eligibility.request.yaml b/postman/collections/Fleetbase Storefront API/Reviews/Check Review Eligibility.request.yaml new file mode 100644 index 0000000..3132cb2 --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Reviews/Check Review Eligibility.request.yaml @@ -0,0 +1,25 @@ +$kind: http-request +description: |- + Whether the authenticated customer can review a store or product, and why not. Returns: + + ```json + { "can_review": true, "reason": null, "message": null, "order": "order_9Ks2mP1", "review": null } + ``` + + `order` is the completed order the review will be attached to. When `can_review` is false, `reason` is one of `sign_in_required` (no customer token), `unsupported_subject`, `no_completed_order` (no completed order with the store, or containing the product) `already_reviewed` (every completed order has been reviewed; `review` is the latest one) or `reviews_disabled` (reviews are turned off for the store or network), with a customer-facing `message`. +url: "{{base_url}}/{{api_prefix}}/{{namespace}}/reviews/eligibility" +method: GET +headers: + - key: Customer-Token + value: "{{customer_token}}" +queryParams: + subject: "{{store_id}}" + order: "" +scripts: + - type: afterResponse + code: |- + pm.test('Eligibility says whether the customer can review', function () { + pm.expect(pm.response.json().can_review).to.be.a('boolean'); + }); + language: text/javascript +order: 1500 diff --git a/postman/collections/Fleetbase Storefront API/Reviews/Counts the number of ratings for a store.queryParams.yaml b/postman/collections/Fleetbase Storefront API/Reviews/Counts the number of ratings for a store.queryParams.yaml new file mode 100644 index 0000000..592d3a7 --- /dev/null +++ b/postman/collections/Fleetbase Storefront API/Reviews/Counts the number of ratings for a store.queryParams.yaml @@ -0,0 +1,5 @@ +$kind: params +fields: + - name: store + type: string + description: "Network keys only: public ID of the member store to count reviews for. An unknown store returns `400`." diff --git a/postman/collections/Fleetbase Storefront API/Reviews/Counts the number of ratings for a store.request.yaml b/postman/collections/Fleetbase Storefront API/Reviews/Counts the number of ratings for a store.request.yaml index 7a73973..8b452f7 100644 --- a/postman/collections/Fleetbase Storefront API/Reviews/Counts the number of ratings for a store.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Reviews/Counts the number of ratings for a store.request.yaml @@ -1,5 +1,8 @@ $kind: http-request -description: Counts the number of ratings for a store +description: |- + Counts the store's reviews by rating, as `{ "1": n, "2": n, "3": n, "4": n, "5": n }`. Only reviews of the store itself are counted. With a network key, pass `store`; without it the response is `[]`. When reviews are turned off, every count is 0. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/reviews/count" method: GET +queryParams: + store: "" order: 3000 diff --git a/postman/collections/Fleetbase Storefront API/Reviews/Create a review.params.yaml b/postman/collections/Fleetbase Storefront API/Reviews/Create a review.params.yaml index b25869f..1d7a5c5 100644 --- a/postman/collections/Fleetbase Storefront API/Reviews/Create a review.params.yaml +++ b/postman/collections/Fleetbase Storefront API/Reviews/Create a review.params.yaml @@ -1,8 +1,20 @@ $kind: params fields: - - name: content + - name: subject + type: string + required: true + description: "Public identifier of the store or product being reviewed." + - name: order type: string - description: "Text content for the comment or message." + description: "The completed order being reviewed. Optional; the most recent unreviewed completed order is used without it." - name: rating type: integer - description: "Rating value for this reviews request." + required: true + description: "Rating from 1 to 5." + - name: content + type: string + required: true + description: "Review text, up to 2000 characters." + - name: files + type: array of objects + description: "Up to 4 photos or videos, each `{ \"data\": base64, \"type\": \"image/jpeg\" }`." diff --git a/postman/collections/Fleetbase Storefront API/Reviews/Create a review.request.yaml b/postman/collections/Fleetbase Storefront API/Reviews/Create a review.request.yaml index da3d057..6774719 100644 --- a/postman/collections/Fleetbase Storefront API/Reviews/Create a review.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Reviews/Create a review.request.yaml @@ -1,5 +1,6 @@ $kind: http-request -description: Create a review +description: |- + Creates a verified-purchase review for the authenticated customer. The customer must be allowed to review the subject (see Check Review Eligibility); otherwise the request is refused with `403` and `{ "error": message, "reason": reason }`, using the same reasons. The review is linked to the order it reviews, so it is returned with `"verified": true`. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/reviews" method: POST headers: @@ -11,16 +12,29 @@ body: type: json content: |- { - "subject": "{{product_id}}", + "subject": "{{store_id}}", "content": "Arrived on time and exactly as described.", "rating": 5 } scripts: + - type: beforeRequest + code: |- + // A customer can only review after a completed order. Unless the environment says + // the customer has one to review, the request documents the refusal contract. + if (!pm.environment.get('review_eligible')) { + pm.variables.set('expected_status', 403); + } + language: text/javascript - type: afterResponse code: |- - // Retrieve a Store review and Delete a Review both address {{review_id}}; - // nothing set it. + // Retrieve a Store review and Delete a Review both address {{review_id}}. var json_response = pm.response.json(); - pm.environment.set("review_id", json_response.id); + if (pm.response.code === 403) { + pm.test('An ineligible customer is told why', function () { + pm.expect(json_response.reason).to.be.oneOf(['sign_in_required', 'unsupported_subject', 'no_completed_order', 'already_reviewed', 'reviews_disabled']); + }); + } else { + pm.environment.set("review_id", json_response.id); + } language: text/javascript order: 2000 diff --git a/postman/collections/Fleetbase Storefront API/Reviews/Delete a Review.request.yaml b/postman/collections/Fleetbase Storefront API/Reviews/Delete a Review.request.yaml index 3828e88..ad8251e 100644 --- a/postman/collections/Fleetbase Storefront API/Reviews/Delete a Review.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Reviews/Delete a Review.request.yaml @@ -1,5 +1,9 @@ $kind: http-request -description: Delete a Review +description: |- + Deletes one of the authenticated customer's own reviews. Deleting another customer's review is refused with `403`. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/reviews/{{review_id}}" method: DELETE +headers: + - key: Customer-Token + value: "{{customer_token}}" order: 5000 diff --git "a/postman/collections/Fleetbase Storefront API/Reviews/Query Reviews \342\235\227.queryParams.yaml" "b/postman/collections/Fleetbase Storefront API/Reviews/Query Reviews \342\235\227.queryParams.yaml" index cf7f877..9f9340a 100644 --- "a/postman/collections/Fleetbase Storefront API/Reviews/Query Reviews \342\235\227.queryParams.yaml" +++ "b/postman/collections/Fleetbase Storefront API/Reviews/Query Reviews \342\235\227.queryParams.yaml" @@ -1,11 +1,14 @@ $kind: params fields: + - name: store + type: string + description: "Store public ID. Required with a network key (the store must be a member); ignored with a store key." - name: limit type: string - description: "Limit value for this reviews request." + description: "Maximum number of reviews to return." - name: offset type: string - description: "Offset value for this reviews request." + description: "Number of reviews to skip." - name: sort type: string - description: "Sort value for this reviews request." + description: "`newest`, `oldest`, `highest` or `lowest`." diff --git "a/postman/collections/Fleetbase Storefront API/Reviews/Query Reviews \342\235\227.request.yaml" "b/postman/collections/Fleetbase Storefront API/Reviews/Query Reviews \342\235\227.request.yaml" index 9673bf2..0ce0b87 100644 --- "a/postman/collections/Fleetbase Storefront API/Reviews/Query Reviews \342\235\227.request.yaml" +++ "b/postman/collections/Fleetbase Storefront API/Reviews/Query Reviews \342\235\227.request.yaml" @@ -1,11 +1,13 @@ $kind: http-request -description: Query Reviews ❗ +description: |- + Lists a store's reviews (reviews of the store itself, not its products). Send the customer token to have the customer's own review marked with `"is_mine": true`. With a network key, pass `store`; without it the list is empty, and an unknown or non-member store returns `400`. When reviews are turned off, the list is empty. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/reviews" method: GET headers: - key: Customer-Token value: "{{customer_token}}" queryParams: + store: "{{store_id}}" limit: "" offset: "" sort: "" diff --git a/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.request.yaml b/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.request.yaml index 2146c42..063e577 100644 --- a/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.request.yaml +++ b/postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.request.yaml @@ -1,6 +1,6 @@ $kind: http-request description: |- - Returns locations for the authenticated storefront context. Network keys receive locations belonging to active member stores for network storefront maps, pickup selection, and multi-store delivery origins; store keys receive only their own locations. Requests without a storefront context receive an error. + Returns locations for the authenticated storefront context. Network keys receive locations belonging to active member stores (suspended and pending members are hidden) for network storefront maps, pickup selection, and multi-store delivery origins; store keys receive only their own locations. Requests without a storefront context receive an error. url: "{{base_url}}/{{api_prefix}}/{{namespace}}/store-locations" method: GET queryParams: diff --git a/postman/collections/Fleetbase Storefront API/Store/.resources/definition.yaml b/postman/collections/Fleetbase Storefront API/Store/.resources/definition.yaml index 178b988..a00b5f7 100644 --- a/postman/collections/Fleetbase Storefront API/Store/.resources/definition.yaml +++ b/postman/collections/Fleetbase Storefront API/Store/.resources/definition.yaml @@ -1,4 +1,6 @@ $kind: collection description: |- + With a network key, only active member stores are visible: suspended and pending (not yet approved) members are hidden from every storefront endpoint, and their products can't be quoted or checked out. + Store endpoints describe the active storefront or network being browsed. Use them to retrieve store profile data, locations, payment gateways, tags, search results, and network store listings. order: 5000 diff --git a/postman/collections/Fleetbase Storefront API/Store/.resources/object.yaml b/postman/collections/Fleetbase Storefront API/Store/.resources/object.yaml index f589a42..780be7d 100644 --- a/postman/collections/Fleetbase Storefront API/Store/.resources/object.yaml +++ b/postman/collections/Fleetbase Storefront API/Store/.resources/object.yaml @@ -55,7 +55,7 @@ fields: description: "Country code derived from the store currency." - name: options type: object - description: "Public store option values." + description: "Public store options, such as `pickup_enabled`, `cod_enabled`, `tips_enabled`, `multi_cart_enabled`, `reviews_enabled` and `map_marker` (how the store is shown on maps: `store`, `warehouse` or `factory` icon, or `logo`)." - name: logo_url type: string description: "Store logo URL." diff --git a/postman/collections/Fleetbase Storefront API/Store/List Network Stores.queryParams.yaml b/postman/collections/Fleetbase Storefront API/Store/List Network Stores.queryParams.yaml index 4638687..bea130c 100644 --- a/postman/collections/Fleetbase Storefront API/Store/List Network Stores.queryParams.yaml +++ b/postman/collections/Fleetbase Storefront API/Store/List Network Stores.queryParams.yaml @@ -26,13 +26,13 @@ fields: description: "Sort mode: highest_rated, lowest_rated, newest, oldest, popular, trending, or nearest." - name: "location[latitude]" type: number - description: "Customer latitude used by nearest sorting and distance filtering." + description: "Customer latitude used by nearest sorting and distance filtering. A missing or invalid location (or 0,0) is ignored, and then `nearest` and `maximum_distance` have no effect." - name: "location[longitude]" type: number description: "Customer longitude used by nearest sorting and distance filtering." - name: maximum_distance type: number - description: "Maximum distance from location in meters. Stores without a valid location are omitted." + description: "Maximum distance from location in meters. Applies only with a valid `location`; each store then also has `distance` (meters)." - name: limit type: integer description: "Maximum number of stores to return."