docs: document marketplace API contracts

collections/apis/storefront-api/README.md

@@ -16,3 +16,16 @@ Requests inherit bearer token authentication from the collection. Set `api_key`
 ## Coverage
 
 The editable Postman Local Mode collection lives at `postman/collections/Fleetbase Storefront API`. It uses `api_prefix=storefront`, so versioned request URLs resolve as `{{base_url}}/{{api_prefix}}/{{namespace}}/...`.
+
+## Marketplace network keys
+
+Use a `network_...` Storefront API key to browse a marketplace. The same public routes are used for both editions, but the key determines the owner and access scope:
+
+- `GET /about` returns the network owner for a network key and the store owner for a store key.
+- `GET /stores`, `GET /store-locations`, and `GET /tags` are marketplace network resources.
+- Categories can represent the network's member-store taxonomy or, with `store`, a member store's product taxonomy.
+- Products, reviews, stores, and locations are limited to active network membership; unavailable or foreign resources return the endpoint's normal not-found or validation response.
+- Each cart line records its `store_id` and `store_location_id`. Multi-store checkout is accepted only when the network enables `multi_cart_enabled`; mixed currencies are rejected.
+- A `Customer-Token` is authoritative at checkout. A conflicting `customer` parameter returns `403` instead of checking out as another customer.
+
+The collection deliberately uses placeholders and local environment variables. Do not save real network keys or customer tokens in collection files.

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

@@ -14,4 +14,4 @@ fields:
     description: "Scheduled fulfillment time for the line item."
   - name: store_location
     type: string
-    description: "Public ID of the store location to associate with the line item."
+    description: "Public ID of a location belonging to the product's store. Marketplace carts reject cross-store location substitution."

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

@@ -0,0 +1,17 @@
+$kind: params
+fields:
+  - name: store
+    type: string
+    description: "Marketplace member store public ID whose product categories should be returned."
+  - name: parent
+    type: string
+    description: "Parent category public ID used to return its direct children."
+  - name: parents_only
+    type: boolean
+    description: "Return only top-level categories."
+  - name: with_products
+    type: boolean
+    description: "Include published, available products for each returned store product category."
+  - name: with_stores
+    type: boolean
+    description: "For marketplace categories, include member stores assigned to each category."

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

@@ -1,6 +1,12 @@
 $kind: http-request
 description: |-
-  Returns product categories available to the current storefront. Use this list to organize product browsing and filtering.
+  Returns product categories for a store key, marketplace categories for a network key, or product categories for a selected marketplace member store. Category and product expansion remains scoped to the authenticated storefront owner.
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/categories"
 method: GET
+queryParams:
+  store: ""
+  parent: ""
+  parents_only: ""
+  with_products: ""
+  with_stores: ""
 order: 1000

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

@@ -5,10 +5,10 @@ fields:
     description: "Payment gateway ID or code."
   - name: customer
     type: string
-    description: "Customer ID associated with the request."
+    description: "Customer public ID for guest checkout. When Customer-Token is present this value must identify the authenticated customer or checkout returns 403."
   - name: cart
     type: string
-    description: "Cart value for this checkout request."
+    description: "Cart public ID or unique identifier. Marketplace 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."

postman/collections/Fleetbase Storefront API/Delivery Service Quote/Retrieve a Delivery Service Quote ❗.queryParams.yaml

@@ -2,10 +2,10 @@ $kind: params
 fields:
   - name: origin
     type: string
-    description: "Origin value for this delivery service quote request."
+    description: "Fallback store-location public ID, or comma-separated IDs for a multi-store cart. Cart line-item locations take precedence."
   - name: destination
     type: string
     description: "Destination value for this delivery service quote request."
   - name: cart
     type: string
-    description: "Cart value for this delivery service quote request."
+    description: "Cart public ID or unique identifier. Marketplace origins must belong to the corresponding member stores."

postman/collections/Fleetbase Storefront API/Products/Query Products.queryParams.yaml

@@ -1,5 +1,20 @@
 $kind: params
 fields:
-  - name: offset
+  - name: query
+    type: string
+    description: "Search published products available through the current store or network."
+  - name: store
     type: string
-    description: "Offset value for this products request."
+    description: "Marketplace member store public ID. Ignored for store-scoped keys."
+  - name: category
+    type: string
+    description: "Product category public ID belonging to the selected store scope."
+  - name: with_store
+    type: boolean
+    description: "Include the product's hydrated member store and media."
+  - name: limit
+    type: integer
+    description: "Maximum number of products to return."
+  - name: offset
+    type: integer
+    description: "Number of matching products to skip."

postman/collections/Fleetbase Storefront API/Products/Query Products.request.yaml

@@ -1,8 +1,13 @@
 $kind: http-request
 description: |-
-  Returns products available in the current storefront. Use pagination and filters to browse the catalog.
+  Returns published, available products for the authenticated store or marketplace network. In marketplace mode, products are restricted to active network members and can be scoped to a member store or one of that store's categories.
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/products"
 method: GET
 queryParams:
+  query: ""
+  store: ""
+  category: ""
+  with_store: "true"
+  limit: ""
   offset: ""
 order: 1000

postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.queryParams.yaml

@@ -0,0 +1,29 @@
+$kind: params
+fields:
+  - name: query
+    type: string
+    description: "Search member stores and return their matching locations."
+  - name: tagged
+    type: string
+    description: "Comma-separated member-store tags to match."
+  - name: ids
+    type: string
+    description: "Comma-separated store-location public IDs to include."
+  - name: exclude
+    type: string
+    description: "Comma-separated store-location public IDs to exclude."
+  - name: with_store
+    type: boolean
+    description: "Include the location's hydrated member store, logo, and backdrop."
+  - name: "location[latitude]"
+    type: number
+    description: "Customer latitude used to calculate and order location distance."
+  - name: "location[longitude]"
+    type: number
+    description: "Customer longitude used to calculate and order location distance."
+  - name: limit
+    type: integer
+    description: "Maximum number of locations to return; defaults to 30."
+  - name: offset
+    type: integer
+    description: "Number of matching locations to skip."

postman/collections/Fleetbase Storefront API/Store Locations/Query Store Locations.request.yaml

@@ -1,6 +1,16 @@
 $kind: http-request
 description: |-
-  Returns store locations available through the current storefront or network. Use these locations for browsing, pickup, and fulfillment selection.
+  Returns locations for the authenticated storefront context. Network keys receive locations belonging to active member stores for marketplace 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:
+  query: ""
+  tagged: ""
+  ids: ""
+  exclude: ""
+  with_store: "true"
+  "location[latitude]": ""
+  "location[longitude]": ""
+  limit: ""
+  offset: ""
 order: 1000

postman/collections/Fleetbase Storefront API/Store/List Network Stores.queryParams.yaml

@@ -2,13 +2,40 @@ $kind: params
 fields:
   - name: query
     type: string
-    description: "Query value for this store request."
-  - name: limit
+    description: "Search member store names and other searchable store fields."
+  - name: tagged
     type: string
-    description: "Limit value for this store request."
-  - name: offset
+    description: "Comma-separated store tags; a store matching any supplied tag is returned."
+  - name: category
+    type: string
+    description: "Marketplace category public ID assigned to a network member store."
+  - name: without_category
+    type: boolean
+    description: "When true, return only member stores without a marketplace category assignment."
+  - name: ids
     type: string
-    description: "Offset value for this store request."
-  - name: store
+    description: "Comma-separated store public IDs to include."
+  - name: exclude
     type: string
-    description: "Store value for this store request."
+    description: "Comma-separated store public IDs to exclude."
+  - name: online
+    type: boolean
+    description: "Filter by the store online state."
+  - name: sort
+    type: string
+    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."
+  - 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."
+  - name: limit
+    type: integer
+    description: "Maximum number of stores to return."
+  - name: offset
+    type: integer
+    description: "Number of matching stores to skip."

postman/collections/Fleetbase Storefront API/Store/List Network Stores.request.yaml

@@ -1,10 +1,20 @@
 $kind: http-request
-description: List Network Stores
+description: |-
+  Lists active member stores for the authenticated marketplace network key. Results are network-scoped and can be searched, filtered, distance-ranked, and paginated. A store-scoped key receives an error from this endpoint.
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/stores"
 method: GET
 queryParams:
   query: ""
+  tagged: ""
+  category: ""
+  without_category: ""
+  ids: ""
+  exclude: ""
+  online: "true"
+  sort: ""
+  "location[latitude]": ""
+  "location[longitude]": ""
+  maximum_distance: ""
   limit: ""
   offset: ""
-  store: ""
 order: 2700

postman/collections/Fleetbase Storefront API/Store/List Tags.request.yaml

@@ -1,5 +1,6 @@
 $kind: http-request
-description: List Tags
+description: |-
+  Returns unique storefront tags for the authenticated context. Network keys aggregate tags across active member stores, while store keys return tags from the current store only.
 url: "{{base_url}}/{{api_prefix}}/{{namespace}}/tags"
 method: GET
 order: 2800

scripts/lint-collections.sh

@@ -4,12 +4,7 @@ set -eu
 node ./scripts/validate-collections.js
 
 if command -v postman >/dev/null 2>&1; then
-  yaml_files="$(find ./postman/collections -name '*.yaml' -print)"
-  if [ -n "$yaml_files" ]; then
-    for yaml_file in $yaml_files; do
-      postman collection lint "$yaml_file" --fail-severity error
-    done
-  fi
+  postman collection lint ./postman/collections --fail-severity error
 else
   echo "Postman CLI not found; skipped v3 YAML schema lint."
 fi