{"openapi":"3.1.0","info":{"title":"Bridge to Brands API","summary":"One normalised API to every brand's dealer portal.","description":"Bridge to Brands reaches every brand's dealer portal through one normalised API: catalog search, availability grids, prices, ship-tos, and orders, with the brand as a path parameter.\n\n**How ordering works.** Bridge to Brands places your orders within your caps and confirmation settings where the brand is verified; it stages them with a link otherwise (`submission.mode_effective` and `submission.reason` say which and why). A staged order is an unsubmitted draft in the brand's portal: always show the user `portal.url` and `portal.instructions`; nothing ships until a human submits it there.\n\n**Authentication.** Send `Authorization: Bearer b2b_live_<prefix>_<secret>`. Keys are created by the account owner at app.brdg2b.ai/keys with scope `read` (catalog, ship-tos, usage) or `read orders` (also stage and read orders). Keys starting `b2b_test_` reach deterministic fake portals: same schemas, same errors, no portal traffic.\n\n**Happy path.** `GET /brands` → `POST /brands/{brand}/lookup` (resolve SKUs or UPCs, see stock and price) → `GET /brands/{brand}/ship-tos` → `POST /orders` with an `Idempotency-Key` → show `portal.url`.\n\n**Conventions.** Errors are RFC 9457 `application/problem+json`; branch on `type` (`https://brdg2b.ai/problems/<code>`) and follow the recovery action documented on each operation. Money is a string with two decimals plus `currency`, never a float. Times are RFC 3339 UTC; `as_of` says when the portal was asked — cache on it and do not poll availability more often than every 15 minutes. Lists are `{data, next_cursor, meta}` with `limit` (≤ 100) and `cursor`. Unknown request fields are rejected with `400`. Every response carries `X-Request-Id`; quote it to support. Respect `Retry-After` on `429` and `503`.\n\nThe agent guide with full request/response pairs is at [`/v1/agents.md`](https://api.brdg2b.ai/v1/agents.md).\n\nBridge to Brands is a product of RunOps Inc.\n","termsOfService":"https://brdg2b.ai/legal/terms","contact":{"name":"RunOps Inc.","url":"https://runops.ai","email":"support@brdg2b.ai"},"version":"1.0.0","x-provider":"RunOps Inc."},"servers":[{"url":"https://api.brdg2b.ai/v1","description":"Production"}],"paths":{"/brands":{"get":{"tags":["Brands"],"summary":"List brands, their capabilities and your connections","description":"**What it does.** Returns every brand Bridge to Brands supports, what each brand's connector can do, and whether this account has connected the brand's dealer portal.\n\n**When to call it.** Call it first, once per session, and cache it: it tells you which brand codes exist, which are connected (`connection.status = connected`), and which capabilities (search, drop-ship, ordering modes, PO length) to respect before any other call.\n\n**Inputs.** None. A key with a brand allowlist sees only its allowed brands.\n\n**Output.** `{data: Brand[], next_cursor: null, meta}`. Each `Brand` carries `code`, `name`, `platform`, `support`, `capabilities`, `connection` (the default account's: `status` is connected, pending, invalid, error, disabled or not_connected) and `accounts[]` — every login the retailer holds for the brand (e.g. one for the stores, one for Amazon), each with `id`, `name`, `description`, `default`, `status`.\n\n**Metering.** Not metered: no portal is contacted.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 60/minute and 10/10second (class `catalog`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`.\n\n**Brand variation.** This is the source of truth for brand variation: every capability flag is per brand and can change over time.","operationId":"list_brands","responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandList"},"examples":{"example_1":{"summary":"BrandList","value":{"data":[{"code":"brooks","name":"Brooks","platform":null,"support":"supported","description":"Brooks Running FastTrack dealer portal.","capabilities":{"catalog_search":true,"prices":true,"width_axis":true,"ordering_modes":["at_once","future"],"ordering":true,"drop_ship":true,"drop_ship_requires_phone":false,"drop_ship_requires_email":false,"drop_ship_max_per_send":1,"po_max_length":20,"submit":false,"submit_contract_complete":true,"order_feed":true,"order_feed_tracking":true,"portal_url":"https://fasttrack.brooksrunning.com","unmatched_hint":"Brooks SKUs look like 1204431B189 (style 120443, width 1B, colour 189).","portal_window":true,"portal_window_reason":null,"future_window_at_stage":false},"connection":{"status":"connected","connected_at":"2026-10-01T12:00:00Z","last_check_at":"2026-10-16T14:55:00Z"},"accounts":[{"id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PA","brand":"brooks","name":"Retail stores","description":"The stores' account; ships to the three stores","default":true,"status":"connected","warehouses":[],"ship_tos":{"count":3,"labels":["Columbia","Lexington","Irmo"]}}]}],"next_cursor":null,"meta":{"count":1}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/brands","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/brands","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/brands","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/brands","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/brands","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"503":{"description":"Problem: `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/brands","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"List brands, their capabilities and your connections — reference page","url":"https://brdg2b.ai/docs/api/list-brands"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","unavailable","internal"],"x-metering":{"metered":false,"operation":null,"counts":"Not metered: no portal is contacted.","recorded_by":"gateway"},"x-rate-limit":{"class":"catalog","per_key":["60/minute","10/10second"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/accounts":{"get":{"tags":["Brands"],"summary":"List your logins (accounts) per brand","description":"**What it does.** Returns every login the retailer holds for each brand — a brand can have several, e.g. one for the stores and one for Amazon, each seeing different warehouses, prices and availability — with the name and description the retailer wrote for it.\n\n**When to call it.** Call it when a brand has more than one account (see `accounts[]` in GET /v1/brands), before acting on that brand: match the user's words (\"the Amazon account\", \"retail vs Amazon\") against `name` and `description`. When nothing matches clearly, list the accounts to the user and ask; never guess.\n\n**Inputs.** `brand` (query, optional, e.g. `brooks`): only that brand's accounts.\n\n**Output.** `{data: Account[], next_cursor: null, meta}`. An `Account` has `id` (send it, or the exact `name`, as `account`), `brand`, `name`, `description`, `default` (used when a call names no account), `status`, `warehouses[]` (when the portal lists them) and `ship_tos {count, labels}`.\n\n**Metering.** Not metered: no portal is contacted.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `brand_not_supported` (404): The brand code in the path or body is not a brand Bridge to Brands supports. → Call GET /v1/brands for the valid codes. Do not retry.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 60/minute and 10/10second (class `catalog`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`.\n\n**Brand variation.** A platform login (NuORDER, Wolverine) is one account for every brand it carries, with the same id. Read GET /v1/brands/{brand} capabilities rather than hard-coding a brand list; capabilities change as connectors gain features.","operationId":"list_accounts","parameters":[{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,39}$"},{"type":"null"}],"description":"Only this brand.","examples":["brooks"],"title":"Brand"},"description":"Only this brand.","example":"brooks"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountList"},"examples":{"example_1":{"summary":"AccountList","value":{"data":[{"id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PA","brand":"brooks","name":"Retail stores","description":"The stores' account; ships to the three stores","default":true,"status":"connected","warehouses":[],"ship_tos":{"count":3,"labels":["Columbia","Lexington","Irmo"]}}],"next_cursor":null,"meta":{"count":1}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/accounts","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/accounts","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/accounts","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/accounts","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `brand_not_supported`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_supported":{"summary":"Brand not supported","value":{"type":"https://brdg2b.ai/problems/brand_not_supported","title":"Brand not supported","status":404,"detail":"no such brand","instance":"/v1/accounts","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/accounts","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/accounts","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"503":{"description":"Problem: `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/accounts","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"List your logins (accounts) per brand — reference page","url":"https://brdg2b.ai/docs/api/list-accounts"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","brand_not_supported","unavailable","internal"],"x-metering":{"metered":false,"operation":null,"counts":"Not metered: no portal is contacted.","recorded_by":"gateway"},"x-rate-limit":{"class":"catalog","per_key":["60/minute","10/10second"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/brands/{brand}":{"get":{"tags":["Brands"],"summary":"Get one brand","description":"**What it does.** Returns one brand's capabilities and this account's connection to its portal.\n\n**When to call it.** Call it before ordering or searching a brand you have not cached, to check `connection.status` and the capabilities that constrain the request.\n\n**Inputs.** `brand` (path): a brand code from GET /v1/brands, lowercase, e.g. `brooks`.\n\n**Output.** One `Brand` object (see GET /v1/brands).\n\n**Metering.** Not metered: no portal is contacted.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `brand_not_supported` (404): The brand code in the path or body is not a brand Bridge to Brands supports. → Call GET /v1/brands for the valid codes. Do not retry.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 60/minute and 10/10second (class `catalog`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`.\n\n**Brand variation.** Read GET /v1/brands/{brand} capabilities rather than hard-coding a brand list; capabilities change as connectors gain features.","operationId":"get_brand","parameters":[{"name":"brand","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,39}$","description":"Brand code from GET /v1/brands (lowercase).","examples":["brooks"],"title":"Brand"},"description":"Brand code from GET /v1/brands (lowercase).","example":"brooks"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Brand"},"examples":{"example_1":{"summary":"Brand","value":{"code":"brooks","name":"Brooks","platform":null,"support":"supported","description":"Brooks Running FastTrack dealer portal.","capabilities":{"catalog_search":true,"prices":true,"width_axis":true,"ordering_modes":["at_once","future"],"ordering":true,"drop_ship":true,"drop_ship_requires_phone":false,"drop_ship_requires_email":false,"drop_ship_max_per_send":1,"po_max_length":20,"submit":false,"submit_contract_complete":true,"order_feed":true,"order_feed_tracking":true,"portal_url":"https://fasttrack.brooksrunning.com","unmatched_hint":"Brooks SKUs look like 1204431B189 (style 120443, width 1B, colour 189).","portal_window":true,"portal_window_reason":null,"future_window_at_stage":false},"connection":{"status":"connected","connected_at":"2026-10-01T12:00:00Z","last_check_at":"2026-10-16T14:55:00Z"},"accounts":[{"id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PA","brand":"brooks","name":"Retail stores","description":"The stores' account; ships to the three stores","default":true,"status":"connected","warehouses":[],"ship_tos":{"count":3,"labels":["Columbia","Lexington","Irmo"]}}]}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/brands/{brand}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/brands/{brand}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/brands/{brand}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/brands/{brand}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `brand_not_supported`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_supported":{"summary":"Brand not supported","value":{"type":"https://brdg2b.ai/problems/brand_not_supported","title":"Brand not supported","status":404,"detail":"no such brand","instance":"/v1/brands/{brand}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/brands/{brand}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/brands/{brand}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"503":{"description":"Problem: `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/brands/{brand}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"Get one brand — reference page","url":"https://brdg2b.ai/docs/api/get-brand"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","brand_not_supported","unavailable","internal"],"x-metering":{"metered":false,"operation":null,"counts":"Not metered: no portal is contacted.","recorded_by":"gateway"},"x-rate-limit":{"class":"catalog","per_key":["60/minute","10/10second"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/brands/{brand}/products":{"get":{"tags":["Catalog"],"summary":"Search a brand's catalog","description":"**What it does.** Searches the brand's dealer-portal catalog by free text and returns matching styles with their colourways and this dealer's prices.\n\n**When to call it.** Call it when the user names a product in words (\"Ghost 17\"). If you already hold a SKU or UPC, call POST /v1/brands/{brand}/lookup instead: it is cheaper and exact.\n\n**Inputs.** `brand` (path, e.g. `brooks`); `q` (query, required, 1–200 characters, e.g. `ghost 17`); `limit` (1–100, default 25) and `cursor` (the previous page's `next_cursor`). `account` (query, optional): which of the brand's logins to use — the account id or its exact name from GET /v1/accounts, e.g. `Amazon FBA`; omitted = the brand's default account. An unknown name is `404 account_not_found` listing the valid names.\n\n**Output.** `{data: Product[], next_cursor, meta}`. A `Product` is a style (`style_id`, `name`, `gender`, `category`) with `colorways[]` (`color_id`, `name`, `image_url`, `price`). Prices are strings with two decimals plus `currency`. `meta.as_of` says when the portal was asked and `meta.account` which login answered.\n\n**Metering.** One `search` usage event per call; `result_count` = colourways returned.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `brand_not_supported` (404): The brand code in the path or body is not a brand Bridge to Brands supports. → Call GET /v1/brands for the valid codes. Do not retry.\n- `account_not_found` (404): The account (one of the retailer's logins to this brand) named in the request is not one of the brand's accounts. The detail lists the valid account names. → Pick one of the listed names (or ids from GET /v1/accounts), or omit account to use the brand's default account. Never guess: when the user's words do not clearly match one account, ask them.\n- `brand_not_connected` (409): The account has no enabled connection to this brand's dealer portal. → Tell the account owner to connect the brand at app.brdg2b.ai/brands. Do not retry until they have.\n- `credentials_invalid` (409): The brand's portal rejected the saved login (password changed or account locked). → Tell the account owner to re-enter the portal password at app.brdg2b.ai/brands. API keys can never do this. Do not retry.\n- `portal_down` (503): The brand's portal is down, slow, or refused the session; other brands are unaffected. → Retry after Retry-After seconds; keep serving other brands.\n- `portal_changed` (502): The brand's portal answered in a shape we no longer understand; our team is alerted. → Do not retry now; try again later, or finish in the portal window from the order in Bridge to Brands.\n- `portal_rejected` (422): The brand's portal refused the request (the dealer account is not entitled, or the portal refused a line or ship-to). → Show the user the problem; check the ship-to and lines. Do not retry unchanged.\n- `capability_unavailable` (422): The brand's connector does not offer this (for example catalog search, drop-ship, or future ordering). → Check capabilities in GET /v1/brands/{brand} and use another route (for example lookup by UPC instead of search). Do not retry.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 60/minute and 10/10second (class `catalog`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`. Portal-inclusive p95 under 4 s; one portal call per page.\n\n**Brand variation.** Only brands with `capabilities.catalog_search = true` support search; the others return `capability_unavailable` — use lookup by UPC/SKU for them. Gender and category are the vendor's own words. Read GET /v1/brands/{brand} capabilities rather than hard-coding a brand list; capabilities change as connectors gain features.","operationId":"search_products","parameters":[{"name":"brand","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,39}$","description":"Brand code from GET /v1/brands (lowercase).","examples":["brooks"],"title":"Brand"},"description":"Brand code from GET /v1/brands (lowercase).","example":"hoka"},{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":200,"description":"Free-text search, e.g. a model name.","examples":["ghost 17"],"title":"Q"},"description":"Free-text search, e.g. a model name.","example":"clifton"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Opaque cursor: the previous page's next_cursor.","examples":["b3JkOjI1"],"title":"Cursor"},"description":"Opaque cursor: the previous page's next_cursor."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size, 1–100.","examples":[25],"default":25,"title":"Limit"},"description":"Page size, 1–100.","example":"25"},{"name":"mode","in":"query","required":false,"schema":{"anyOf":[{"enum":["at_once","future"],"type":"string"},{"type":"null"}],"description":"Only items in this order book: `at_once` (stock now) or `future` (pre-book / season).","examples":["future"],"title":"Mode"},"description":"Only items in this order book: `at_once` (stock now) or `future` (pre-book / season)."},{"name":"account","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":60},{"type":"null"}],"description":"Which of the brand's logins to use: the account id or its exact name (GET /v1/accounts). Omitted = the brand's default account.","examples":["Amazon FBA"],"title":"Account"},"description":"Which of the brand's logins to use: the account id or its exact name (GET /v1/accounts). Omitted = the brand's default account."}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductPage"},"examples":{"example_1":{"summary":"ProductPage","value":{"data":[{"brand":"brooks","style_id":"120443","name":"Ghost 17","gender":"women","category":"road","colorways":[{"color_id":"120443189","name":"Black/Ebony/Pink","image_url":"https://images.brooksrunning.com/120443189.jpg","price":{"wholesale":"70.00","retail":"140.00","currency":"USD"}}],"as_of":"2026-10-16T15:04:05Z"}],"next_cursor":"c2VhcmNoOjI1","meta":{"count":1,"limit":25,"as_of":"2026-10-16T15:04:05Z","brand":"brooks"}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `brand_not_supported`, `account_not_found`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_supported":{"summary":"Brand not supported","value":{"type":"https://brdg2b.ai/problems/brand_not_supported","title":"Brand not supported","status":404,"detail":"no such brand","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"account_not_found":{"summary":"Account not found","value":{"type":"https://brdg2b.ai/problems/account_not_found","title":"Account not found","status":404,"detail":"Brooks has no account 'amazon'; its accounts are \"Retail stores\", \"Amazon FBA\"","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"409":{"description":"Problem: `brand_not_connected`, `credentials_invalid`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_connected":{"summary":"Brand not connected","value":{"type":"https://brdg2b.ai/problems/brand_not_connected","title":"Brand not connected","status":409,"detail":"This account has not connected this brand's dealer portal.","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"credentials_invalid":{"summary":"Portal credentials invalid","value":{"type":"https://brdg2b.ai/problems/credentials_invalid","title":"Portal credentials invalid","status":409,"detail":"The brand's portal rejected the saved login.","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"422":{"description":"Problem: `portal_rejected`, `capability_unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_rejected":{"summary":"Portal rejected the request","value":{"type":"https://brdg2b.ai/problems/portal_rejected","title":"Portal rejected the request","status":422,"detail":"The brand's portal refused this request.","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"capability_unavailable":{"summary":"Capability unavailable","value":{"type":"https://brdg2b.ai/problems/capability_unavailable","title":"Capability unavailable","status":422,"detail":"this brand has no catalog search","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"502":{"description":"Problem: `portal_changed`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_changed":{"summary":"Portal changed","value":{"type":"https://brdg2b.ai/problems/portal_changed","title":"Portal changed","status":502,"detail":"The brand's portal answered in an unexpected shape.","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"503":{"description":"Problem: `portal_down`, `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_down":{"summary":"Portal unavailable","value":{"type":"https://brdg2b.ai/problems/portal_down","title":"Portal unavailable","status":503,"detail":"The brand's portal is not answering right now.","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks","retry_after":60}},"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/brands/{brand}/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"Search a brand's catalog — reference page","url":"https://brdg2b.ai/docs/api/search-products"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","brand_not_supported","account_not_found","brand_not_connected","credentials_invalid","portal_down","portal_changed","portal_rejected","capability_unavailable","unavailable","internal"],"x-metering":{"metered":true,"operation":"search","counts":"One `search` usage event per call; `result_count` = colourways returned.","recorded_by":"gateway"},"x-rate-limit":{"class":"catalog","per_key":["60/minute","10/10second"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/brands/{brand}/products/{style_id}":{"get":{"tags":["Catalog"],"summary":"Get one style with its size run","description":"**What it does.** Returns one style: its colourways and prices, every size column it is made in, and its images.\n\n**When to call it.** Call it after a search to show a style's full size run, or before ordering by `style_id` + `color_id` + `size` to learn the valid sizes.\n\n**Inputs.** `brand` (path, e.g. `brooks`); `style_id` (path, the vendor's style id from search, e.g. `120443`). `account` (query, optional): which of the brand's logins to use — the account id or its exact name from GET /v1/accounts, e.g. `Amazon FBA`; omitted = the brand's default account. An unknown name is `404 account_not_found` listing the valid names.\n\n**Output.** `ProductDetail` = `Product` + `size_columns[]` (`key`, `size`, `width`) + `images[]`. The answer says which login it came from: `account: {id, name}`.\n\n**Metering.** One `product` usage event per call.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `brand_not_supported` (404): The brand code in the path or body is not a brand Bridge to Brands supports. → Call GET /v1/brands for the valid codes. Do not retry.\n- `account_not_found` (404): The account (one of the retailer's logins to this brand) named in the request is not one of the brand's accounts. The detail lists the valid account names. → Pick one of the listed names (or ids from GET /v1/accounts), or omit account to use the brand's default account. Never guess: when the user's words do not clearly match one account, ask them.\n- `brand_not_connected` (409): The account has no enabled connection to this brand's dealer portal. → Tell the account owner to connect the brand at app.brdg2b.ai/brands. Do not retry until they have.\n- `credentials_invalid` (409): The brand's portal rejected the saved login (password changed or account locked). → Tell the account owner to re-enter the portal password at app.brdg2b.ai/brands. API keys can never do this. Do not retry.\n- `portal_down` (503): The brand's portal is down, slow, or refused the session; other brands are unaffected. → Retry after Retry-After seconds; keep serving other brands.\n- `portal_changed` (502): The brand's portal answered in a shape we no longer understand; our team is alerted. → Do not retry now; try again later, or finish in the portal window from the order in Bridge to Brands.\n- `portal_rejected` (422): The brand's portal refused the request (the dealer account is not entitled, or the portal refused a line or ship-to). → Show the user the problem; check the ship-to and lines. Do not retry unchanged.\n- `not_found` (404): The order, product or shipment does not exist for this account. → Check the id; list the collection to find the right one. Do not retry.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 60/minute and 10/10second (class `catalog`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`.\n\n**Brand variation.** `width` is present only for brands with `capabilities.width_axis = true`; size keys look different per brand (`7.0/B` vs `04B`) — treat them as opaque. Read GET /v1/brands/{brand} capabilities rather than hard-coding a brand list; capabilities change as connectors gain features.","operationId":"get_product","parameters":[{"name":"brand","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,39}$","description":"Brand code from GET /v1/brands (lowercase).","examples":["brooks"],"title":"Brand"},"description":"Brand code from GET /v1/brands (lowercase).","example":"brooks"},{"name":"style_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":80,"description":"The vendor's style id, from search or lookup.","examples":["120443"],"title":"Style Id"},"description":"The vendor's style id, from search or lookup.","example":"120443"},{"name":"account","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":60},{"type":"null"}],"description":"Which of the brand's logins to use: the account id or its exact name (GET /v1/accounts). Omitted = the brand's default account.","examples":["Amazon FBA"],"title":"Account"},"description":"Which of the brand's logins to use: the account id or its exact name (GET /v1/accounts). Omitted = the brand's default account."}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductDetail"},"examples":{"example_1":{"summary":"ProductDetail","value":{"brand":"brooks","style_id":"120443","name":"Ghost 17","gender":"women","category":"road","colorways":[{"color_id":"120443189","name":"Black/Ebony/Pink","image_url":"https://images.brooksrunning.com/120443189.jpg","price":{"wholesale":"70.00","retail":"140.00","currency":"USD"}}],"as_of":"2026-10-16T15:04:05Z","size_columns":[{"key":"7.0/B","size":"7","width":"B"},{"key":"7.5/B","size":"7.5","width":"B"}],"images":["https://images.brooksrunning.com/120443189.jpg"]}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `brand_not_supported`, `account_not_found`, `not_found`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_supported":{"summary":"Brand not supported","value":{"type":"https://brdg2b.ai/problems/brand_not_supported","title":"Brand not supported","status":404,"detail":"no such brand","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"account_not_found":{"summary":"Account not found","value":{"type":"https://brdg2b.ai/problems/account_not_found","title":"Account not found","status":404,"detail":"Brooks has no account 'amazon'; its accounts are \"Retail stores\", \"Amazon FBA\"","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"not_found":{"summary":"Not found","value":{"type":"https://brdg2b.ai/problems/not_found","title":"Not found","status":404,"detail":"no such order","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"409":{"description":"Problem: `brand_not_connected`, `credentials_invalid`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_connected":{"summary":"Brand not connected","value":{"type":"https://brdg2b.ai/problems/brand_not_connected","title":"Brand not connected","status":409,"detail":"This account has not connected this brand's dealer portal.","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"credentials_invalid":{"summary":"Portal credentials invalid","value":{"type":"https://brdg2b.ai/problems/credentials_invalid","title":"Portal credentials invalid","status":409,"detail":"The brand's portal rejected the saved login.","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"422":{"description":"Problem: `portal_rejected`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_rejected":{"summary":"Portal rejected the request","value":{"type":"https://brdg2b.ai/problems/portal_rejected","title":"Portal rejected the request","status":422,"detail":"The brand's portal refused this request.","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"502":{"description":"Problem: `portal_changed`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_changed":{"summary":"Portal changed","value":{"type":"https://brdg2b.ai/problems/portal_changed","title":"Portal changed","status":502,"detail":"The brand's portal answered in an unexpected shape.","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"503":{"description":"Problem: `portal_down`, `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_down":{"summary":"Portal unavailable","value":{"type":"https://brdg2b.ai/problems/portal_down","title":"Portal unavailable","status":503,"detail":"The brand's portal is not answering right now.","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks","retry_after":60}},"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/brands/{brand}/products/{style_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"Get one style with its size run — reference page","url":"https://brdg2b.ai/docs/api/get-product"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","brand_not_supported","account_not_found","brand_not_connected","credentials_invalid","portal_down","portal_changed","portal_rejected","not_found","unavailable","internal"],"x-metering":{"metered":true,"operation":"product","counts":"One `product` usage event per call.","recorded_by":"gateway"},"x-rate-limit":{"class":"catalog","per_key":["60/minute","10/10second"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/brands/{brand}/products/{style_id}/availability":{"get":{"tags":["Catalog"],"summary":"Get a style's availability grid","description":"**What it does.** Returns the vendor's date × size availability for one colourway, or for every colourway of the style, with this dealer's price.\n\n**When to call it.** Call it to decide what to order and when it ships. Do not poll: cache by `as_of` and ask again no sooner than every 15 minutes. For many SKUs at once use POST /v1/brands/{brand}/lookup, which returns availability per item.\n\n**Inputs.** `brand` (path, e.g. `brooks`); `style_id` (path, e.g. `120443`); `color_id` (query, optional, e.g. `120443189`). `account` (query, optional): which of the brand's logins to use — the account id or its exact name from GET /v1/accounts, e.g. `Amazon FBA`; omitted = the brand's default account. An unknown name is `404 account_not_found` listing the valid names. To compare logins (\"Brooks Amazon vs Brooks retail\"), send `accounts` instead: repeat it once per account (ids or exact names), or send `accounts=all` for every account of the brand (at most 10).\n\n**Output.** With `color_id`: one `AvailabilityGrid`. Without it: `{data: AvailabilityGrid[], next_cursor: null, meta}`, one per colourway. A grid has `columns[]` (sizes), `rows[]` (the date-null `at_once` row is stock now; dated rows are future windows) with `cells[column_key] = {qty, display, order_limit}`, `cap_threshold`/`cap_applied_by` (quantities at or above the cap show as `200+`), `price`, `as_of`, and `stale` (true when the portal is down and you get the last snapshot). `status`: ok, partial (some sizes unknown), unsupported, size_missing, error (that colourway failed; others may still be ok). Every grid carries `account: {id, name}`. With `accounts`: an `AvailabilityComparison` `{brand, style_id, color_id, data[], meta}` with one entry per account — `account {id, name, description, default}`, its `grids[]`, `as_of`, `stale` and `error` (a problem object when that account could not answer; the others still do).\n\n**Metering.** One `availability` usage event per call; `result_count` = grids returned. With `accounts`: one event per account read (the accounts are read in parallel, each through its own login).\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `brand_not_supported` (404): The brand code in the path or body is not a brand Bridge to Brands supports. → Call GET /v1/brands for the valid codes. Do not retry.\n- `account_not_found` (404): The account (one of the retailer's logins to this brand) named in the request is not one of the brand's accounts. The detail lists the valid account names. → Pick one of the listed names (or ids from GET /v1/accounts), or omit account to use the brand's default account. Never guess: when the user's words do not clearly match one account, ask them.\n- `brand_not_connected` (409): The account has no enabled connection to this brand's dealer portal. → Tell the account owner to connect the brand at app.brdg2b.ai/brands. Do not retry until they have.\n- `credentials_invalid` (409): The brand's portal rejected the saved login (password changed or account locked). → Tell the account owner to re-enter the portal password at app.brdg2b.ai/brands. API keys can never do this. Do not retry.\n- `portal_down` (503): The brand's portal is down, slow, or refused the session; other brands are unaffected. → Retry after Retry-After seconds; keep serving other brands.\n- `portal_changed` (502): The brand's portal answered in a shape we no longer understand; our team is alerted. → Do not retry now; try again later, or finish in the portal window from the order in Bridge to Brands.\n- `portal_rejected` (422): The brand's portal refused the request (the dealer account is not entitled, or the portal refused a line or ship-to). → Show the user the problem; check the ship-to and lines. Do not retry unchanged.\n- `not_found` (404): The order, product or shipment does not exist for this account. → Check the id; list the collection to find the right one. Do not retry.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 60/minute and 10/10second (class `catalog`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`. p95 under 2 s when served from the recent snapshot.\n\n**Brand variation.** Some brands cap displayed quantities (`cap_applied_by = server` means the true number is unknown above the cap); some have no future windows (`capabilities.ordering_modes`). Read GET /v1/brands/{brand} capabilities rather than hard-coding a brand list; capabilities change as connectors gain features.","operationId":"get_availability","parameters":[{"name":"brand","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,39}$","description":"Brand code from GET /v1/brands (lowercase).","examples":["brooks"],"title":"Brand"},"description":"Brand code from GET /v1/brands (lowercase).","example":"brooks"},{"name":"style_id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":80,"description":"The vendor's style id, from search or lookup.","examples":["120443"],"title":"Style Id"},"description":"The vendor's style id, from search or lookup.","example":"120443"},{"name":"color_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":80},{"type":"null"}],"description":"One colourway; omit for every colourway of the style.","examples":["120443189"],"title":"Color Id"},"description":"One colourway; omit for every colourway of the style.","example":"120443189"},{"name":"account","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":60},{"type":"null"}],"description":"Which of the brand's logins to use: the account id or its exact name (GET /v1/accounts). Omitted = the brand's default account.","examples":["Amazon FBA"],"title":"Account"},"description":"Which of the brand's logins to use: the account id or its exact name (GET /v1/accounts). Omitted = the brand's default account."},{"name":"accounts","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"},"maxItems":10},{"type":"null"}],"description":"Compare logins: repeat once per account (id or exact name), or send `all` for every account of the brand. Returns an AvailabilityComparison with one entry per account.","examples":[["Retail stores","Amazon FBA"]],"title":"Accounts"},"description":"Compare logins: repeat once per account (id or exact name), or send `all` for every account of the brand. Returns an AvailabilityComparison with one entry per account."}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AvailabilityGrid"},{"$ref":"#/components/schemas/AvailabilityGridList"},{"$ref":"#/components/schemas/AvailabilityComparison"}],"title":"Response Get Availability"},"examples":{"one_colourway":{"summary":"With color_id: one grid","value":{"brand":"brooks","style_id":"120443","color_id":"120443189","color_name":"Black/Ebony/Pink","status":"ok","columns":[{"key":"7.0/B","size":"7","width":"B"}],"rows":[{"date":null,"ordering_mode":"at_once","cells":{"7.0/B":{"qty":200,"display":"200+","order_limit":null}}},{"date":"2026-11-15","ordering_mode":"future","cells":{"7.0/B":{"qty":48,"display":"48","order_limit":null}}}],"cap_threshold":200,"cap_applied_by":"server","price":{"wholesale":"70.00","retail":"140.00","currency":"USD"},"as_of":"2026-10-16T15:04:05Z","stale":false}},"every_colourway":{"summary":"Without color_id: one grid per colourway","value":{"data":[{"brand":"brooks","style_id":"120443","color_id":"120443189","color_name":"Black/Ebony/Pink","status":"ok","columns":[{"key":"7.0/B","size":"7","width":"B"}],"rows":[{"date":null,"ordering_mode":"at_once","cells":{"7.0/B":{"qty":200,"display":"200+","order_limit":null}}},{"date":"2026-11-15","ordering_mode":"future","cells":{"7.0/B":{"qty":48,"display":"48","order_limit":null}}}],"cap_threshold":200,"cap_applied_by":"server","price":{"wholesale":"70.00","retail":"140.00","currency":"USD"},"as_of":"2026-10-16T15:04:05Z","stale":false}],"next_cursor":null,"meta":{"count":1,"as_of":"2026-10-16T15:04:05Z","brand":"brooks"}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `brand_not_supported`, `account_not_found`, `not_found`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_supported":{"summary":"Brand not supported","value":{"type":"https://brdg2b.ai/problems/brand_not_supported","title":"Brand not supported","status":404,"detail":"no such brand","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"account_not_found":{"summary":"Account not found","value":{"type":"https://brdg2b.ai/problems/account_not_found","title":"Account not found","status":404,"detail":"Brooks has no account 'amazon'; its accounts are \"Retail stores\", \"Amazon FBA\"","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"not_found":{"summary":"Not found","value":{"type":"https://brdg2b.ai/problems/not_found","title":"Not found","status":404,"detail":"no such order","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"409":{"description":"Problem: `brand_not_connected`, `credentials_invalid`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_connected":{"summary":"Brand not connected","value":{"type":"https://brdg2b.ai/problems/brand_not_connected","title":"Brand not connected","status":409,"detail":"This account has not connected this brand's dealer portal.","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"credentials_invalid":{"summary":"Portal credentials invalid","value":{"type":"https://brdg2b.ai/problems/credentials_invalid","title":"Portal credentials invalid","status":409,"detail":"The brand's portal rejected the saved login.","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"422":{"description":"Problem: `portal_rejected`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_rejected":{"summary":"Portal rejected the request","value":{"type":"https://brdg2b.ai/problems/portal_rejected","title":"Portal rejected the request","status":422,"detail":"The brand's portal refused this request.","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"502":{"description":"Problem: `portal_changed`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_changed":{"summary":"Portal changed","value":{"type":"https://brdg2b.ai/problems/portal_changed","title":"Portal changed","status":502,"detail":"The brand's portal answered in an unexpected shape.","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"503":{"description":"Problem: `portal_down`, `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_down":{"summary":"Portal unavailable","value":{"type":"https://brdg2b.ai/problems/portal_down","title":"Portal unavailable","status":503,"detail":"The brand's portal is not answering right now.","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks","retry_after":60}},"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/brands/{brand}/products/{style_id}/availability","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"Get a style's availability grid — reference page","url":"https://brdg2b.ai/docs/api/get-availability"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","brand_not_supported","account_not_found","brand_not_connected","credentials_invalid","portal_down","portal_changed","portal_rejected","not_found","unavailable","internal"],"x-metering":{"metered":true,"operation":"availability","counts":"One `availability` usage event per call; `result_count` = grids returned. With `accounts`: one event per account read (the accounts are read in parallel, each through its own login).","recorded_by":"gateway"},"x-rate-limit":{"class":"catalog","per_key":["60/minute","10/10second"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/brands/{brand}/lookup":{"post":{"tags":["Catalog"],"summary":"Resolve SKUs/UPCs to vendor variants with availability and price","description":"**What it does.** Resolves up to 200 products, each given by barcode, SKU, style code or catalog coordinates, to the vendor's exact variant and returns stock now, future windows and this dealer's price for each.\n\n**When to call it.** Call it before POST /v1/orders whenever you hold retailer SKUs or UPCs: it shows what will resolve and what is in stock, and returns `variant_id`s to order by. Batch: one call with 200 items beats 200 calls.\n\n**Inputs.** `brand` (path, e.g. `brooks`). Body `{items: LookupItem[]}`, 1–200 items. Identify each item by exactly one form: `variant_id`; `upc` (8–14 digits, e.g. `195394123456`); `sku` plus optional `size`, `width`, `color` (e.g. `1204431B189` + `8` + `B`); `style_code`; or `style_id` + `color_id` + `size`. `client_ref` is echoed back. `account` (query, optional): which of the brand's logins to use — the account id or its exact name from GET /v1/accounts, e.g. `Amazon FBA`; omitted = the brand's default account. An unknown name is `404 account_not_found` listing the valid names.\n\n**Output.** `{brand, items: LookupResult[], unmatched_hint, meta}` in request order. Each result: `resolved`, `variant_id`, `style_id`, `color_id`, `size_key`, `match_method` (barcode_api, sku_decode, search, manual), `confidence` (string 0.00–1.00), `immediate {qty, display}`, `future[]`, `order_limit`, `price`, and `reason` when unresolved. Show `unmatched_hint` next to unresolved items.\n\n**Metering.** One `lookup` usage event per call; `result_count` = items resolved.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `brand_not_supported` (404): The brand code in the path or body is not a brand Bridge to Brands supports. → Call GET /v1/brands for the valid codes. Do not retry.\n- `account_not_found` (404): The account (one of the retailer's logins to this brand) named in the request is not one of the brand's accounts. The detail lists the valid account names. → Pick one of the listed names (or ids from GET /v1/accounts), or omit account to use the brand's default account. Never guess: when the user's words do not clearly match one account, ask them.\n- `brand_not_connected` (409): The account has no enabled connection to this brand's dealer portal. → Tell the account owner to connect the brand at app.brdg2b.ai/brands. Do not retry until they have.\n- `credentials_invalid` (409): The brand's portal rejected the saved login (password changed or account locked). → Tell the account owner to re-enter the portal password at app.brdg2b.ai/brands. API keys can never do this. Do not retry.\n- `portal_down` (503): The brand's portal is down, slow, or refused the session; other brands are unaffected. → Retry after Retry-After seconds; keep serving other brands.\n- `portal_changed` (502): The brand's portal answered in a shape we no longer understand; our team is alerted. → Do not retry now; try again later, or finish in the portal window from the order in Bridge to Brands.\n- `portal_rejected` (422): The brand's portal refused the request (the dealer account is not entitled, or the portal refused a line or ship-to). → Show the user the problem; check the ship-to and lines. Do not retry unchanged.\n- `capability_unavailable` (422): The brand's connector does not offer this (for example catalog search, drop-ship, or future ordering). → Check capabilities in GET /v1/brands/{brand} and use another route (for example lookup by UPC instead of search). Do not retry.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 10/minute (class `lookup`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`. At most 200 items per call.\n\n**Brand variation.** Barcode lookup is the most reliable form for most brands; SKU decoding exists for brands whose SKUs encode style, width and colour (Brooks, ASICS, HOKA…); other brands fall back to catalog search, which needs `capabilities.catalog_search`. Read GET /v1/brands/{brand} capabilities rather than hard-coding a brand list; capabilities change as connectors gain features.","operationId":"lookup_items","parameters":[{"name":"brand","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,39}$","description":"Brand code from GET /v1/brands (lowercase).","examples":["brooks"],"title":"Brand"},"description":"Brand code from GET /v1/brands (lowercase).","example":"brooks"},{"name":"account","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":60},{"type":"null"}],"description":"Which of the brand's logins to use: the account id or its exact name (GET /v1/accounts). Omitted = the brand's default account.","examples":["Amazon FBA"],"title":"Account"},"description":"Which of the brand's logins to use: the account id or its exact name (GET /v1/accounts). Omitted = the brand's default account."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupRequest"},"examples":{"example_1":{"summary":"example-1","value":{"items":[{"sku":"1204431B189","size":"8","width":"B","client_ref":"pos-line-17"},{"upc":"195394123456"},{"style_id":"120443","color_id":"120443189","size":"9.5"}]}}}}}},"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResponse"},"examples":{"example_1":{"summary":"LookupResponse","value":{"brand":"brooks","items":[{"input":{"sku":"1204431B189","size":"8","width":"B","client_ref":"pos-line-17"},"resolved":true,"variant_id":"1204431B189.080","style_id":"120443","color_id":"120443189","size_key":"8.0/B","match_method":"sku_decode","confidence":"0.90","immediate":{"qty":12,"display":"12"},"future":[{"date":"2026-11-15","qty":48,"display":"48","ordering_mode":"future"}],"order_limit":null,"price":{"wholesale":"70.00","retail":"140.00","currency":"USD"},"reason":null},{"input":{"upc":"195394123456"},"resolved":false,"variant_id":null,"style_id":null,"color_id":null,"size_key":null,"match_method":null,"confidence":null,"immediate":null,"future":[],"order_limit":null,"price":null,"reason":"unresolved"}],"unmatched_hint":"Brooks SKUs look like 1204431B189 (style 120443, width 1B, colour 189).","meta":{"count":2,"as_of":"2026-10-16T15:04:05Z","brand":"brooks"}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `brand_not_supported`, `account_not_found`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_supported":{"summary":"Brand not supported","value":{"type":"https://brdg2b.ai/problems/brand_not_supported","title":"Brand not supported","status":404,"detail":"no such brand","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"account_not_found":{"summary":"Account not found","value":{"type":"https://brdg2b.ai/problems/account_not_found","title":"Account not found","status":404,"detail":"Brooks has no account 'amazon'; its accounts are \"Retail stores\", \"Amazon FBA\"","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"409":{"description":"Problem: `brand_not_connected`, `credentials_invalid`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_connected":{"summary":"Brand not connected","value":{"type":"https://brdg2b.ai/problems/brand_not_connected","title":"Brand not connected","status":409,"detail":"This account has not connected this brand's dealer portal.","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"credentials_invalid":{"summary":"Portal credentials invalid","value":{"type":"https://brdg2b.ai/problems/credentials_invalid","title":"Portal credentials invalid","status":409,"detail":"The brand's portal rejected the saved login.","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"422":{"description":"Problem: `portal_rejected`, `capability_unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_rejected":{"summary":"Portal rejected the request","value":{"type":"https://brdg2b.ai/problems/portal_rejected","title":"Portal rejected the request","status":422,"detail":"The brand's portal refused this request.","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"capability_unavailable":{"summary":"Capability unavailable","value":{"type":"https://brdg2b.ai/problems/capability_unavailable","title":"Capability unavailable","status":422,"detail":"this brand has no catalog search","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"502":{"description":"Problem: `portal_changed`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_changed":{"summary":"Portal changed","value":{"type":"https://brdg2b.ai/problems/portal_changed","title":"Portal changed","status":502,"detail":"The brand's portal answered in an unexpected shape.","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"503":{"description":"Problem: `portal_down`, `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_down":{"summary":"Portal unavailable","value":{"type":"https://brdg2b.ai/problems/portal_down","title":"Portal unavailable","status":503,"detail":"The brand's portal is not answering right now.","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks","retry_after":60}},"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/brands/{brand}/lookup","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"Resolve SKUs/UPCs to vendor variants with availability and price — reference page","url":"https://brdg2b.ai/docs/api/lookup-items"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","brand_not_supported","account_not_found","brand_not_connected","credentials_invalid","portal_down","portal_changed","portal_rejected","capability_unavailable","unavailable","internal"],"x-metering":{"metered":true,"operation":"lookup","counts":"One `lookup` usage event per call; `result_count` = items resolved.","recorded_by":"gateway"},"x-rate-limit":{"class":"lookup","per_key":["10/minute"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/brands/{brand}/ship-tos":{"get":{"tags":["Ship-tos"],"summary":"List your stores as the brand knows them","description":"**What it does.** Returns the account's stores (ship-to destinations) as the brand's portal knows them.\n\n**When to call it.** Call it once per brand before the first order and cache it: `ref` is the `ship_to_ref` every order needs.\n\n**Inputs.** `brand` (path, e.g. `brooks`). `account` (query, optional): which of the brand's logins to use — the account id or its exact name from GET /v1/accounts, e.g. `Amazon FBA`; omitted = the brand's default account. An unknown name is `404 account_not_found` listing the valid names.\n\n**Output.** `{data: ShipTo[], next_cursor: null, meta}`. A `ShipTo` has `ref` (send as `ship_to_ref`), `account_ref` (the vendor's own customer number), `name`, `city`, `state`, `postal` and `label` (the retailer's own name for the store). Each login has its own ship-tos; `meta.account` says whose these are.\n\n**Metering.** One `ship_tos` usage event per call.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `brand_not_supported` (404): The brand code in the path or body is not a brand Bridge to Brands supports. → Call GET /v1/brands for the valid codes. Do not retry.\n- `account_not_found` (404): The account (one of the retailer's logins to this brand) named in the request is not one of the brand's accounts. The detail lists the valid account names. → Pick one of the listed names (or ids from GET /v1/accounts), or omit account to use the brand's default account. Never guess: when the user's words do not clearly match one account, ask them.\n- `brand_not_connected` (409): The account has no enabled connection to this brand's dealer portal. → Tell the account owner to connect the brand at app.brdg2b.ai/brands. Do not retry until they have.\n- `credentials_invalid` (409): The brand's portal rejected the saved login (password changed or account locked). → Tell the account owner to re-enter the portal password at app.brdg2b.ai/brands. API keys can never do this. Do not retry.\n- `portal_down` (503): The brand's portal is down, slow, or refused the session; other brands are unaffected. → Retry after Retry-After seconds; keep serving other brands.\n- `portal_changed` (502): The brand's portal answered in a shape we no longer understand; our team is alerted. → Do not retry now; try again later, or finish in the portal window from the order in Bridge to Brands.\n- `portal_rejected` (422): The brand's portal refused the request (the dealer account is not entitled, or the portal refused a line or ship-to). → Show the user the problem; check the ship-to and lines. Do not retry unchanged.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 60/minute and 10/10second (class `catalog`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`.\n\n**Brand variation.** Store numbering is the vendor's; the same store has a different `ref` at each brand. Read GET /v1/brands/{brand} capabilities rather than hard-coding a brand list; capabilities change as connectors gain features.","operationId":"list_ship_tos","parameters":[{"name":"brand","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,39}$","description":"Brand code from GET /v1/brands (lowercase).","examples":["brooks"],"title":"Brand"},"description":"Brand code from GET /v1/brands (lowercase).","example":"brooks"},{"name":"account","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":60},{"type":"null"}],"description":"Which of the brand's logins to use: the account id or its exact name (GET /v1/accounts). Omitted = the brand's default account.","examples":["Amazon FBA"],"title":"Account"},"description":"Which of the brand's logins to use: the account id or its exact name (GET /v1/accounts). Omitted = the brand's default account."}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipToList"},"examples":{"example_1":{"summary":"ShipToList","value":{"data":[{"ref":"1002","account_ref":"0001234567","name":"Fleet Feet Columbia","city":"Columbia","state":"SC","postal":"29201","label":"Columbia"}],"next_cursor":null,"meta":{"count":1,"brand":"brooks"}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/brands/{brand}/ship-tos","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/brands/{brand}/ship-tos","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/brands/{brand}/ship-tos","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/brands/{brand}/ship-tos","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `brand_not_supported`, `account_not_found`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_supported":{"summary":"Brand not supported","value":{"type":"https://brdg2b.ai/problems/brand_not_supported","title":"Brand not supported","status":404,"detail":"no such brand","instance":"/v1/brands/{brand}/ship-tos","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"account_not_found":{"summary":"Account not found","value":{"type":"https://brdg2b.ai/problems/account_not_found","title":"Account not found","status":404,"detail":"Brooks has no account 'amazon'; its accounts are \"Retail stores\", \"Amazon FBA\"","instance":"/v1/brands/{brand}/ship-tos","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"409":{"description":"Problem: `brand_not_connected`, `credentials_invalid`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_connected":{"summary":"Brand not connected","value":{"type":"https://brdg2b.ai/problems/brand_not_connected","title":"Brand not connected","status":409,"detail":"This account has not connected this brand's dealer portal.","instance":"/v1/brands/{brand}/ship-tos","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"credentials_invalid":{"summary":"Portal credentials invalid","value":{"type":"https://brdg2b.ai/problems/credentials_invalid","title":"Portal credentials invalid","status":409,"detail":"The brand's portal rejected the saved login.","instance":"/v1/brands/{brand}/ship-tos","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"422":{"description":"Problem: `portal_rejected`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_rejected":{"summary":"Portal rejected the request","value":{"type":"https://brdg2b.ai/problems/portal_rejected","title":"Portal rejected the request","status":422,"detail":"The brand's portal refused this request.","instance":"/v1/brands/{brand}/ship-tos","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/brands/{brand}/ship-tos","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/brands/{brand}/ship-tos","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"502":{"description":"Problem: `portal_changed`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_changed":{"summary":"Portal changed","value":{"type":"https://brdg2b.ai/problems/portal_changed","title":"Portal changed","status":502,"detail":"The brand's portal answered in an unexpected shape.","instance":"/v1/brands/{brand}/ship-tos","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"503":{"description":"Problem: `portal_down`, `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_down":{"summary":"Portal unavailable","value":{"type":"https://brdg2b.ai/problems/portal_down","title":"Portal unavailable","status":503,"detail":"The brand's portal is not answering right now.","instance":"/v1/brands/{brand}/ship-tos","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks","retry_after":60}},"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/brands/{brand}/ship-tos","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"List your stores as the brand knows them — reference page","url":"https://brdg2b.ai/docs/api/list-ship-tos"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","brand_not_supported","account_not_found","brand_not_connected","credentials_invalid","portal_down","portal_changed","portal_rejected","unavailable","internal"],"x-metering":{"metered":true,"operation":"ship_tos","counts":"One `ship_tos` usage event per call.","recorded_by":"gateway"},"x-rate-limit":{"class":"catalog","per_key":["60/minute","10/10second"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/orders":{"post":{"tags":["Orders"],"summary":"Stage an order in a brand's portal (and submit it where allowed)","description":"**What it does.** Stages one fill-in (to your store) or drop-ship (to a consumer) order as an unsubmitted draft in the brand's portal and returns the link where a human reviews and submits it — or, with `mode: submit` where every gate allows it, verifies the staged basket and places the order with the brand (see `submission`).\n\n**When to call it.** Call it after GET /v1/brands (brand connected, `ordering` and, for drop-ship, `drop_ship` true), GET /v1/brands/{brand}/ship-tos (the `ship_to_ref`) and, ideally, POST /v1/brands/{brand}/lookup (so lines resolve). Always show the user `portal.url` and `portal.instructions` from the response: nothing ships until they submit it in the portal.\n\n**Inputs.** Header `Idempotency-Key` (required, 1–255 characters; reuse it to retry safely). Body: `brand` (e.g. `brooks`); `kind` (`fill_in` or `drop_ship`); `ship_to_ref` (from ship-tos, e.g. `1002`); `po` (sent exactly as typed, ≤ the brand's `po_max_length`); `lines[]` (1–500), each with `quantity` (1–999), optional `ordering_mode` (`at_once` default, or `future`) and the product in one form: `variant_id`, `upc`, `sku` + `size`/`width`/`color`, `style_code`, or `style_id` + `color_id` + `size`; `consumer` (required for drop_ship, forbidden for fill_in: `addressee`, `street`, `street2`, `city`, `state`, `postal`, `country`, `phone` only when the brand requires it, `email` = the STORE's email only when the brand requires it); `confirm` (true to confirm a large order when asked, and to submit); `mode` (`stage` or `submit`; omitted = the account's per-brand setting); `terms_ack` and `ship_dates {requested_ship, cancel_after}` (ISO dates) where the brand's capabilities require them to submit; `account` (optional): which of the brand's logins to order on, by id or exact name — omitted = the default account; `ship_to_ref` must be one of that account's ship-tos.\n\n**Output.** `202 Accepted` with an `Order`. `status`: `staged_in_portal` (all lines in the draft), `partial` (some lines in `lines.skipped` with a `reason`), `failed` (nothing reached the vendor; see `error`), `draft_left_behind` (the vendor holds a draft that may carry this order — `portal.draft_id` names it; acknowledge before re-sending). Staged vs submitted: a staged order is an unsubmitted draft — nothing ships until a human submits it in the portal, and `submitted` is false. `submission.mode_effective` says `stage` (with `reason`) or `submit`; a submitting order moves through `verified` → (`awaiting_confirmation`) → `submitting` → `submitted` (with `vendor.order_numbers`), or ends `staged_mismatch`, `submit_rejected`, `submit_unknown` or `submit_failed`. `submit_unknown` means the order MAY exist: never resend it; it is read back automatically, then a person resolves it in the app. `submitted` is true only with a vendor order number or a positive read-back. `portal` has `url` (the draft itself where possible), `login_url`, `draft_id` and one-sentence `instructions`; `baskets[]` has one entry per vendor container; `events[]` is the submission timeline.\n\n**Metering.** One `order_stage` usage event per call, success or failure; `line_count` = lines staged, `unit_count` = units staged; a call that goes on to submit adds one `order_submit` event. An idempotent replay is not metered again.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `brand_not_supported` (404): The brand code in the path or body is not a brand Bridge to Brands supports. → Call GET /v1/brands for the valid codes. Do not retry.\n- `account_not_found` (404): The account (one of the retailer's logins to this brand) named in the request is not one of the brand's accounts. The detail lists the valid account names. → Pick one of the listed names (or ids from GET /v1/accounts), or omit account to use the brand's default account. Never guess: when the user's words do not clearly match one account, ask them.\n- `brand_not_connected` (409): The account has no enabled connection to this brand's dealer portal. → Tell the account owner to connect the brand at app.brdg2b.ai/brands. Do not retry until they have.\n- `credentials_invalid` (409): The brand's portal rejected the saved login (password changed or account locked). → Tell the account owner to re-enter the portal password at app.brdg2b.ai/brands. API keys can never do this. Do not retry.\n- `portal_down` (503): The brand's portal is down, slow, or refused the session; other brands are unaffected. → Retry after Retry-After seconds; keep serving other brands.\n- `portal_changed` (502): The brand's portal answered in a shape we no longer understand; our team is alerted. → Do not retry now; try again later, or finish in the portal window from the order in Bridge to Brands.\n- `portal_rejected` (422): The brand's portal refused the request (the dealer account is not entitled, or the portal refused a line or ship-to). → Show the user the problem; check the ship-to and lines. Do not retry unchanged.\n- `capability_unavailable` (422): The brand's connector does not offer this (for example catalog search, drop-ship, or future ordering). → Check capabilities in GET /v1/brands/{brand} and use another route (for example lookup by UPC instead of search). Do not retry.\n- `push_busy` (409): Another order is being staged in this brand's portal for this account right now; nothing was sent. → Retry the same request with the same Idempotency-Key after Retry-After seconds.\n- `draft_left_behind` (409): An earlier attempt left an unsubmitted draft in the portal that may already hold this order; draft_id names it. → Show the user the draft_id; they check it in the portal window from the order in Bridge to Brands (no portal sign-in needed). After they delete or submit that draft, call POST /v1/orders/{order_id}/acknowledge-draft, then re-send. Never re-send before that.\n- `conflict` (409): The request conflicts with current state: an Idempotency-Key reused with a different body, or an order that is not in the state this action needs. → Read the resource again; use a new Idempotency-Key for a different order. Do not retry unchanged.\n- `unprocessable` (422): The request is well-formed but breaks a business rule. → Read detail, correct the request, and send again.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 10/minute (class `orders`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`. Idempotency: the same `Idempotency-Key` from the same account within 24 h returns the original order instead of staging again; the same key with a different body is `409 conflict`. Staging takes up to 60 s; body at most 256 KB.\n\n**Brand variation.** Submitting needs `capabilities.submit` (true only for brands whose submit is live-verified; none as of 2026-10-16 — every order is staged and `submission.reason` says why). Drop-ship needs `capabilities.drop_ship`; phone and store email are required only where `drop_ship_requires_phone` / `drop_ship_requires_email` say so; `po_max_length` and `drop_ship_max_per_send` differ per brand; `future` lines need `future` in `ordering_modes`. Unresolvable lines never block the rest. Read GET /v1/brands/{brand} capabilities rather than hard-coding a brand list; capabilities change as connectors gain features.","operationId":"place_order","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"pattern":"^[\\x21-\\x7e]+$","description":"Required. A unique value per order (a UUID); resend the same value to retry safely within 24 h.","examples":["7f9c2b1e-4d1a-4c5e-9b8a-2f6d3e1a0c55"],"title":"Idempotency-Key"},"description":"Required. A unique value per order (a UUID); resend the same value to retry safely within 24 h.","example":"7f9c2b1e-4d1a-4c5e-9b8a-2f6d3e1a0c55"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCreate"},"examples":{"fill_in":{"summary":"fill-in","value":{"brand":"brooks","kind":"fill_in","ship_to_ref":"1002","po":"FILL-1016-COLA","lines":[{"variant_id":"1204431B189.070","quantity":2},{"upc":"195394123456","quantity":1,"ordering_mode":"at_once"},{"sku":"1204431B189","size":"8","width":"B","quantity":1},{"style_id":"120443","color_id":"120443189","size":"9.5","quantity":1}]}},"drop_ship":{"summary":"drop-ship","value":{"brand":"on","kind":"drop_ship","ship_to_ref":"613907","po":"DS-1016-JANE","consumer":{"addressee":"Jane Doe","street":"12 Main St","street2":"","city":"Columbia","state":"SC","postal":"29201","country":"US","phone":"","email":""},"lines":[{"variant_id":"3MD10340123-7.5","quantity":1}]}}}}}},"responses":{"202":{"description":"Accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"examples":{"example_1":{"summary":"Order","value":{"order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"on","kind":"drop_ship","status":"staged_in_portal","submitted":false,"message":"Staged as an unsubmitted draft in the On portal. Review and place it in Bridge to Brands.","source":"brdg2b","portal":{"url":"https://backstage.on-running.com/reorder/drafts/RO-884213","draft_id":"RO-884213","order_reference":"DS-1016-JANE","login_url":"https://backstage.on-running.com/login","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft RO-884213 as the On portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing."},"baskets":[{"basket_id":"RO-884213","ship_to":"Fleet Feet Columbia (613907)","po":"DS-1016-JANE","total_pieces":1,"portal_url":"https://backstage.on-running.com/reorder/drafts/RO-884213"}],"po":"DS-1016-JANE","ship_to_ref":"613907","surface":"rest","api_key_name":"Storefront integration","lines":{"staged":[{"variant_id":"3MD10340123-7.5","upc":null,"sku":null,"quantity":1,"unit_price":"80.00","currency":"USD"}],"skipped":[{"variant_id":null,"upc":"195394123456","sku":null,"quantity":1,"reason":"no inventory at this ship-to"}],"confirmed":[]},"vendor":null,"shipments":[],"error":null,"draft_left_note":null,"draft_acknowledged_at":null,"created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}},"example_2":{"summary":"Order","value":{"order_id":"ord_01JA2ZB3C4D5E6F7G8H9J0K1M2","brand":"brooks","kind":"fill_in","status":"partial","submitted":false,"message":"Staged 4 of 5 pairs as an unsubmitted basket in the Brooks portal; 1 line was skipped. Review and place it in Bridge to Brands.","source":"brdg2b","portal":{"url":"https://fasttrack.brooksrunning.com/cart?basket=B-552901","draft_id":"B-552901","order_reference":"FILL-1016-COLA","login_url":"https://fasttrack.brooksrunning.com/login","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft B-552901 as the Brooks portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing."},"baskets":[{"basket_id":"B-552901","ship_to":"Fleet Feet Columbia (1002)","po":"FILL-1016-COLA","total_pieces":4,"portal_url":"https://fasttrack.brooksrunning.com/cart?basket=B-552901"}],"po":"FILL-1016-COLA","ship_to_ref":"1002","surface":"rest","api_key_name":"Storefront integration","lines":{"staged":[{"variant_id":"1204431B189.070","upc":null,"sku":null,"quantity":2,"unit_price":"70.00","currency":"USD"},{"variant_id":"1204431B189.080","upc":null,"sku":"1204431B189","quantity":1,"unit_price":"70.00","currency":"USD"},{"variant_id":"1204431B189.095","upc":null,"sku":null,"quantity":1,"unit_price":"70.00","currency":"USD"}],"skipped":[{"variant_id":null,"upc":"195394123456","sku":null,"quantity":1,"reason":"unresolved"}],"confirmed":[]},"vendor":null,"shipments":[],"error":null,"draft_left_note":null,"draft_acknowledged_at":null,"created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `brand_not_supported`, `account_not_found`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_supported":{"summary":"Brand not supported","value":{"type":"https://brdg2b.ai/problems/brand_not_supported","title":"Brand not supported","status":404,"detail":"no such brand","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"account_not_found":{"summary":"Account not found","value":{"type":"https://brdg2b.ai/problems/account_not_found","title":"Account not found","status":404,"detail":"Brooks has no account 'amazon'; its accounts are \"Retail stores\", \"Amazon FBA\"","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"409":{"description":"Problem: `brand_not_connected`, `credentials_invalid`, `push_busy`, `draft_left_behind`, `conflict`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_connected":{"summary":"Brand not connected","value":{"type":"https://brdg2b.ai/problems/brand_not_connected","title":"Brand not connected","status":409,"detail":"This account has not connected this brand's dealer portal.","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"credentials_invalid":{"summary":"Portal credentials invalid","value":{"type":"https://brdg2b.ai/problems/credentials_invalid","title":"Portal credentials invalid","status":409,"detail":"The brand's portal rejected the saved login.","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"push_busy":{"summary":"Portal basket busy","value":{"type":"https://brdg2b.ai/problems/push_busy","title":"Portal basket busy","status":409,"detail":"Another order is being staged for this brand; nothing was sent.","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks","retry_after":30}},"draft_left_behind":{"summary":"Draft left behind","value":{"type":"https://brdg2b.ai/problems/draft_left_behind","title":"Draft left behind","status":409,"detail":"An unsubmitted draft (RO-884213) may already hold this order: the ship-to address did not save.","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks","draft_id":"RO-884213"}},"conflict":{"summary":"Conflict","value":{"type":"https://brdg2b.ai/problems/conflict","title":"Conflict","status":409,"detail":"idempotency key was used with a different request","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"422":{"description":"Problem: `portal_rejected`, `capability_unavailable`, `unprocessable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_rejected":{"summary":"Portal rejected the request","value":{"type":"https://brdg2b.ai/problems/portal_rejected","title":"Portal rejected the request","status":422,"detail":"The brand's portal refused this request.","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"capability_unavailable":{"summary":"Capability unavailable","value":{"type":"https://brdg2b.ai/problems/capability_unavailable","title":"Capability unavailable","status":422,"detail":"this brand has no catalog search","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"unprocessable":{"summary":"Unprocessable","value":{"type":"https://brdg2b.ai/problems/unprocessable","title":"Unprocessable","status":422,"detail":"the order has no lines left to stage","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"502":{"description":"Problem: `portal_changed`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_changed":{"summary":"Portal changed","value":{"type":"https://brdg2b.ai/problems/portal_changed","title":"Portal changed","status":502,"detail":"The brand's portal answered in an unexpected shape.","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"503":{"description":"Problem: `portal_down`, `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_down":{"summary":"Portal unavailable","value":{"type":"https://brdg2b.ai/problems/portal_down","title":"Portal unavailable","status":503,"detail":"The brand's portal is not answering right now.","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks","retry_after":60}},"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"Stage an order in a brand's portal (and submit it where allowed) — reference page","url":"https://brdg2b.ai/docs/api/place-order"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","brand_not_supported","account_not_found","brand_not_connected","credentials_invalid","portal_down","portal_changed","portal_rejected","capability_unavailable","push_busy","draft_left_behind","conflict","unprocessable","unavailable","internal"],"x-metering":{"metered":true,"operation":"order_stage","counts":"One `order_stage` usage event per call, success or failure; `line_count` = lines staged, `unit_count` = units staged; a call that goes on to submit adds one `order_submit` event. An idempotent replay is not metered again.","recorded_by":"gateway"},"x-rate-limit":{"class":"orders","per_key":["10/minute"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}},"get":{"tags":["Orders"],"summary":"List orders: staged here and from the portal's order book","description":"**What it does.** Lists this account's orders — those staged through Bridge to Brands and those read from each vendor's own order book — newest first, with confirmations, status and tracking.\n\n**When to call it.** Call it to show order status or find an order by brand, status or date. Use GET /v1/orders/{order_id} for one order.\n\n**Inputs.** Query, all optional: `brand` (e.g. `brooks`); `account` (one login: its id, or its exact name together with `brand`); `status` (an order status, e.g. `staged_in_portal`); `source` (`brdg2b` or `portal`); `since` (RFC 3339, e.g. `2026-10-01T00:00:00Z`); `limit` (1–100, default 25) and `cursor` (the previous page's `next_cursor`).\n\n**Output.** `{data: Order[], next_cursor, meta}` (see POST /v1/orders for the `Order` shape; portal-sourced orders have `source = portal`).\n\n**Metering.** Not metered: served from Bridge to Brands' records.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `brand_not_supported` (404): The brand code in the path or body is not a brand Bridge to Brands supports. → Call GET /v1/brands for the valid codes. Do not retry.\n- `account_not_found` (404): The account (one of the retailer's logins to this brand) named in the request is not one of the brand's accounts. The detail lists the valid account names. → Pick one of the listed names (or ids from GET /v1/accounts), or omit account to use the brand's default account. Never guess: when the user's words do not clearly match one account, ask them.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 60/minute and 10/10second (class `order_reads`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`.\n\n**Brand variation.** Vendor order books are read only for brands with `capabilities.order_feed = true`. Read GET /v1/brands/{brand} capabilities rather than hard-coding a brand list; capabilities change as connectors gain features.","operationId":"list_orders","parameters":[{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,39}$"},{"type":"null"}],"description":"Only this brand.","examples":["brooks"],"title":"Brand"},"description":"Only this brand.","example":"brooks"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/OrderStatus"},{"type":"null"}],"description":"Only orders in this status.","examples":["staged_in_portal"],"title":"Status"},"description":"Only orders in this status."},{"name":"source","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/OrderSource"},{"type":"null"}],"description":"brdg2b or portal.","examples":["portal"],"title":"Source"},"description":"brdg2b or portal."},{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only items at or after this time (RFC 3339 with offset).","examples":["2026-10-01T00:00:00Z"],"title":"Since"},"description":"Only items at or after this time (RFC 3339 with offset).","example":"2026-10-01T00:00:00Z"},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Opaque cursor: the previous page's next_cursor.","examples":["b3JkOjI1"],"title":"Cursor"},"description":"Opaque cursor: the previous page's next_cursor."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size, 1–100.","examples":[25],"default":25,"title":"Limit"},"description":"Page size, 1–100."},{"name":"account","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":60},{"type":"null"}],"description":"Only orders on this login: its account id, or its exact name together with brand.","examples":["acct_01JB2C5V1C8ZK3V6Q4X9N7M2PB"],"title":"Account"},"description":"Only orders on this login: its account id, or its exact name together with brand."}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderPage"},"examples":{"example_1":{"summary":"OrderPage","value":{"data":[{"order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"on","kind":"drop_ship","status":"staged_in_portal","submitted":false,"message":"Staged as an unsubmitted draft in the On portal. Review and place it in Bridge to Brands.","source":"brdg2b","portal":{"url":"https://backstage.on-running.com/reorder/drafts/RO-884213","draft_id":"RO-884213","order_reference":"DS-1016-JANE","login_url":"https://backstage.on-running.com/login","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft RO-884213 as the On portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing."},"baskets":[{"basket_id":"RO-884213","ship_to":"Fleet Feet Columbia (613907)","po":"DS-1016-JANE","total_pieces":1,"portal_url":"https://backstage.on-running.com/reorder/drafts/RO-884213"}],"po":"DS-1016-JANE","ship_to_ref":"613907","surface":"rest","api_key_name":"Storefront integration","lines":{"staged":[{"variant_id":"3MD10340123-7.5","upc":null,"sku":null,"quantity":1,"unit_price":"80.00","currency":"USD"}],"skipped":[{"variant_id":null,"upc":"195394123456","sku":null,"quantity":1,"reason":"no inventory at this ship-to"}],"confirmed":[]},"vendor":null,"shipments":[],"error":null,"draft_left_note":null,"draft_acknowledged_at":null,"created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}],"next_cursor":"b3JkOjI1","meta":{"count":1,"limit":25}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `brand_not_supported`, `account_not_found`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_supported":{"summary":"Brand not supported","value":{"type":"https://brdg2b.ai/problems/brand_not_supported","title":"Brand not supported","status":404,"detail":"no such brand","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"account_not_found":{"summary":"Account not found","value":{"type":"https://brdg2b.ai/problems/account_not_found","title":"Account not found","status":404,"detail":"Brooks has no account 'amazon'; its accounts are \"Retail stores\", \"Amazon FBA\"","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"503":{"description":"Problem: `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/orders","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"List orders: staged here and from the portal's order book — reference page","url":"https://brdg2b.ai/docs/api/list-orders"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","brand_not_supported","account_not_found","unavailable","internal"],"x-metering":{"metered":false,"operation":null,"counts":"Not metered: served from Bridge to Brands' records.","recorded_by":"gateway"},"x-rate-limit":{"class":"order_reads","per_key":["60/minute","10/10second"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/orders/{order_id}":{"get":{"tags":["Orders"],"summary":"Get one order","description":"**What it does.** Returns one order with its lines, portal link, vendor record and shipments.\n\n**When to call it.** Call it to show an order's status or to recover the portal link.\n\n**Inputs.** `order_id` (path, e.g. `ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W`).\n\n**Output.** One `Order` (see POST /v1/orders).\n\n**Metering.** Not metered.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `not_found` (404): The order, product or shipment does not exist for this account. → Check the id; list the collection to find the right one. Do not retry.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 60/minute and 10/10second (class `order_reads`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`.\n\n**Brand variation.** `vendor` and `shipments` fill in only for brands with `capabilities.order_feed = true`.","operationId":"get_order","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,80}$","description":"Order id returned by POST /v1/orders or GET /v1/orders.","examples":["ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W"],"title":"Order Id"},"description":"Order id returned by POST /v1/orders or GET /v1/orders.","example":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"examples":{"example_1":{"summary":"Order","value":{"order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"on","kind":"drop_ship","status":"staged_in_portal","submitted":false,"message":"Staged as an unsubmitted draft in the On portal. Review and place it in Bridge to Brands.","source":"brdg2b","portal":{"url":"https://backstage.on-running.com/reorder/drafts/RO-884213","draft_id":"RO-884213","order_reference":"DS-1016-JANE","login_url":"https://backstage.on-running.com/login","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft RO-884213 as the On portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing."},"baskets":[{"basket_id":"RO-884213","ship_to":"Fleet Feet Columbia (613907)","po":"DS-1016-JANE","total_pieces":1,"portal_url":"https://backstage.on-running.com/reorder/drafts/RO-884213"}],"po":"DS-1016-JANE","ship_to_ref":"613907","surface":"rest","api_key_name":"Storefront integration","lines":{"staged":[{"variant_id":"3MD10340123-7.5","upc":null,"sku":null,"quantity":1,"unit_price":"80.00","currency":"USD"}],"skipped":[{"variant_id":null,"upc":"195394123456","sku":null,"quantity":1,"reason":"no inventory at this ship-to"}],"confirmed":[]},"vendor":null,"shipments":[],"error":null,"draft_left_note":null,"draft_acknowledged_at":null,"created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}},"example_2":{"summary":"Order","value":{"order_id":"ord_01JA2ZB3C4D5E6F7G8H9J0K1M2","brand":"brooks","kind":"fill_in","status":"partial","submitted":false,"message":"Staged 4 of 5 pairs as an unsubmitted basket in the Brooks portal; 1 line was skipped. Review and place it in Bridge to Brands.","source":"brdg2b","portal":{"url":"https://fasttrack.brooksrunning.com/cart?basket=B-552901","draft_id":"B-552901","order_reference":"FILL-1016-COLA","login_url":"https://fasttrack.brooksrunning.com/login","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft B-552901 as the Brooks portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing."},"baskets":[{"basket_id":"B-552901","ship_to":"Fleet Feet Columbia (1002)","po":"FILL-1016-COLA","total_pieces":4,"portal_url":"https://fasttrack.brooksrunning.com/cart?basket=B-552901"}],"po":"FILL-1016-COLA","ship_to_ref":"1002","surface":"rest","api_key_name":"Storefront integration","lines":{"staged":[{"variant_id":"1204431B189.070","upc":null,"sku":null,"quantity":2,"unit_price":"70.00","currency":"USD"},{"variant_id":"1204431B189.080","upc":null,"sku":"1204431B189","quantity":1,"unit_price":"70.00","currency":"USD"},{"variant_id":"1204431B189.095","upc":null,"sku":null,"quantity":1,"unit_price":"70.00","currency":"USD"}],"skipped":[{"variant_id":null,"upc":"195394123456","sku":null,"quantity":1,"reason":"unresolved"}],"confirmed":[]},"vendor":null,"shipments":[],"error":null,"draft_left_note":null,"draft_acknowledged_at":null,"created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/orders/{order_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/orders/{order_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/orders/{order_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/orders/{order_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `not_found`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"Not found","value":{"type":"https://brdg2b.ai/problems/not_found","title":"Not found","status":404,"detail":"no such order","instance":"/v1/orders/{order_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/orders/{order_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/orders/{order_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"503":{"description":"Problem: `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/orders/{order_id}","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"Get one order — reference page","url":"https://brdg2b.ai/docs/api/get-order"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","not_found","unavailable","internal"],"x-metering":{"metered":false,"operation":null,"counts":"Not metered.","recorded_by":"gateway"},"x-rate-limit":{"class":"order_reads","per_key":["60/minute","10/10second"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/orders/{order_id}/acknowledge-draft":{"post":{"tags":["Orders"],"summary":"Confirm a left-behind draft was dealt with","description":"**What it does.** Records that the buyer deleted or submitted the vendor draft named by a `draft_left_behind` order, which unblocks re-sending.\n\n**When to call it.** Call it only after the user confirms they handled `portal.draft_id` in the portal. Then re-send the order with a NEW Idempotency-Key.\n\n**Inputs.** `order_id` (path). No body.\n\n**Output.** The `Order`, with `draft_acknowledged_at` set.\n\n**Metering.** Not metered.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `not_found` (404): The order, product or shipment does not exist for this account. → Check the id; list the collection to find the right one. Do not retry.\n- `conflict` (409): The request conflicts with current state: an Idempotency-Key reused with a different body, or an order that is not in the state this action needs. → Read the resource again; use a new Idempotency-Key for a different order. Do not retry unchanged.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 10/minute (class `orders`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`.\n\n**Brand variation.** Applies to any brand; how to find the draft is in `portal.instructions`.","operationId":"acknowledge_draft","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,80}$","description":"Order id returned by POST /v1/orders or GET /v1/orders.","examples":["ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W"],"title":"Order Id"},"description":"Order id returned by POST /v1/orders or GET /v1/orders.","example":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"examples":{"example_1":{"summary":"Order","value":{"order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"on","kind":"drop_ship","status":"staged_in_portal","submitted":false,"message":"Staged as an unsubmitted draft in the On portal. Review and place it in Bridge to Brands.","source":"brdg2b","portal":{"url":"https://backstage.on-running.com/reorder/drafts/RO-884213","draft_id":"RO-884213","order_reference":"DS-1016-JANE","login_url":"https://backstage.on-running.com/login","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft RO-884213 as the On portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing."},"baskets":[{"basket_id":"RO-884213","ship_to":"Fleet Feet Columbia (613907)","po":"DS-1016-JANE","total_pieces":1,"portal_url":"https://backstage.on-running.com/reorder/drafts/RO-884213"}],"po":"DS-1016-JANE","ship_to_ref":"613907","surface":"rest","api_key_name":"Storefront integration","lines":{"staged":[{"variant_id":"3MD10340123-7.5","upc":null,"sku":null,"quantity":1,"unit_price":"80.00","currency":"USD"}],"skipped":[{"variant_id":null,"upc":"195394123456","sku":null,"quantity":1,"reason":"no inventory at this ship-to"}],"confirmed":[]},"vendor":null,"shipments":[],"error":null,"draft_left_note":null,"draft_acknowledged_at":null,"created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}},"example_2":{"summary":"Order","value":{"order_id":"ord_01JA2ZB3C4D5E6F7G8H9J0K1M2","brand":"brooks","kind":"fill_in","status":"partial","submitted":false,"message":"Staged 4 of 5 pairs as an unsubmitted basket in the Brooks portal; 1 line was skipped. Review and place it in Bridge to Brands.","source":"brdg2b","portal":{"url":"https://fasttrack.brooksrunning.com/cart?basket=B-552901","draft_id":"B-552901","order_reference":"FILL-1016-COLA","login_url":"https://fasttrack.brooksrunning.com/login","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft B-552901 as the Brooks portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing."},"baskets":[{"basket_id":"B-552901","ship_to":"Fleet Feet Columbia (1002)","po":"FILL-1016-COLA","total_pieces":4,"portal_url":"https://fasttrack.brooksrunning.com/cart?basket=B-552901"}],"po":"FILL-1016-COLA","ship_to_ref":"1002","surface":"rest","api_key_name":"Storefront integration","lines":{"staged":[{"variant_id":"1204431B189.070","upc":null,"sku":null,"quantity":2,"unit_price":"70.00","currency":"USD"},{"variant_id":"1204431B189.080","upc":null,"sku":"1204431B189","quantity":1,"unit_price":"70.00","currency":"USD"},{"variant_id":"1204431B189.095","upc":null,"sku":null,"quantity":1,"unit_price":"70.00","currency":"USD"}],"skipped":[{"variant_id":null,"upc":"195394123456","sku":null,"quantity":1,"reason":"unresolved"}],"confirmed":[]},"vendor":null,"shipments":[],"error":null,"draft_left_note":null,"draft_acknowledged_at":null,"created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/orders/{order_id}/acknowledge-draft","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/orders/{order_id}/acknowledge-draft","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/orders/{order_id}/acknowledge-draft","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/orders/{order_id}/acknowledge-draft","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `not_found`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"Not found","value":{"type":"https://brdg2b.ai/problems/not_found","title":"Not found","status":404,"detail":"no such order","instance":"/v1/orders/{order_id}/acknowledge-draft","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"409":{"description":"Problem: `conflict`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Conflict","value":{"type":"https://brdg2b.ai/problems/conflict","title":"Conflict","status":409,"detail":"idempotency key was used with a different request","instance":"/v1/orders/{order_id}/acknowledge-draft","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/orders/{order_id}/acknowledge-draft","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/orders/{order_id}/acknowledge-draft","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"503":{"description":"Problem: `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/orders/{order_id}/acknowledge-draft","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"Confirm a left-behind draft was dealt with — reference page","url":"https://brdg2b.ai/docs/api/acknowledge-draft"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","not_found","conflict","unavailable","internal"],"x-metering":{"metered":false,"operation":null,"counts":"Not metered.","recorded_by":"gateway"},"x-rate-limit":{"class":"orders","per_key":["10/minute"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/orders/{order_id}/submit":{"post":{"tags":["Orders"],"summary":"Submit a staged order to the brand (place it)","description":"**What it does.** Places a fully staged order with the brand: the staged basket is read back and compared with the order, then submitted exactly once; the order ends `submitted` with the vendor order number(s), or says why not.\n\n**When to call it.** Call it after POST /v1/orders returned `staged_in_portal` with `submission.mode_effective = stage` and a reason you can now satisfy (for example `confirm`), and ONLY after the user approved submitting this exact order. Check `capabilities.submit` first.\n\n**Inputs.** `order_id` (path). Body: `confirm` (must be true), `terms_ack` and `ship_dates {requested_ship, cancel_after}` where the brand's capabilities require them.\n\n**Output.** `202 Accepted` with the `Order`: `submitted` (with `vendor.order_numbers`), `submitting` (the portal is still answering; read it again), `awaiting_confirmation` (a person confirms in the app within 24 h), `staged_mismatch` (the basket differs; nothing was submitted), `submit_rejected` (the brand refused; nothing was placed), `submit_unknown` (the order MAY exist: never call this again; it is read back at +30 s, +2 min, +10 min and +1 h, then a person resolves it in the app) or `submit_failed`. A repeat on an order already in the protocol returns it unchanged.\n\n**Metering.** One `order_submit` usage event per call that reaches the gate; a repeat on an order already submitting is not metered.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `not_found` (404): The order, product or shipment does not exist for this account. → Check the id; list the collection to find the right one. Do not retry.\n- `conflict` (409): The request conflicts with current state: an Idempotency-Key reused with a different body, or an order that is not in the state this action needs. → Read the resource again; use a new Idempotency-Key for a different order. Do not retry unchanged.\n- `capability_unavailable` (422): The brand's connector does not offer this (for example catalog search, drop-ship, or future ordering). → Check capabilities in GET /v1/brands/{brand} and use another route (for example lookup by UPC instead of search). Do not retry.\n- `brand_not_supported` (404): The brand code in the path or body is not a brand Bridge to Brands supports. → Call GET /v1/brands for the valid codes. Do not retry.\n- `account_not_found` (404): The account (one of the retailer's logins to this brand) named in the request is not one of the brand's accounts. The detail lists the valid account names. → Pick one of the listed names (or ids from GET /v1/accounts), or omit account to use the brand's default account. Never guess: when the user's words do not clearly match one account, ask them.\n- `brand_not_connected` (409): The account has no enabled connection to this brand's dealer portal. → Tell the account owner to connect the brand at app.brdg2b.ai/brands. Do not retry until they have.\n- `credentials_invalid` (409): The brand's portal rejected the saved login (password changed or account locked). → Tell the account owner to re-enter the portal password at app.brdg2b.ai/brands. API keys can never do this. Do not retry.\n- `portal_down` (503): The brand's portal is down, slow, or refused the session; other brands are unaffected. → Retry after Retry-After seconds; keep serving other brands.\n- `portal_changed` (502): The brand's portal answered in a shape we no longer understand; our team is alerted. → Do not retry now; try again later, or finish in the portal window from the order in Bridge to Brands.\n- `portal_rejected` (422): The brand's portal refused the request (the dealer account is not entitled, or the portal refused a line or ship-to). → Show the user the problem; check the ship-to and lines. Do not retry unchanged.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 10/minute (class `orders`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`. Needs a key with the `orders:submit` scope that the account owner authorised. One submit per order, ever: there is no retry.\n\n**Brand variation.** Only brands with `capabilities.submit` true can be submitted; the account owner chooses per brand in Settings → Ordering whether submits need a person's confirmation. `submit_cancel_window` says whether a placed order can be cancelled. Read GET /v1/brands/{brand} capabilities rather than hard-coding a brand list; capabilities change as connectors gain features.","operationId":"submit_order","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,80}$","description":"Order id returned by POST /v1/orders or GET /v1/orders.","examples":["ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W"],"title":"Order Id"},"description":"Order id returned by POST /v1/orders or GET /v1/orders.","example":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderSubmit"},"examples":{"example_1":{"summary":"example-1","value":{"confirm":true}}}}}},"responses":{"202":{"description":"Accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"examples":{"example_1":{"summary":"Order","value":{"order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"on","kind":"drop_ship","status":"staged_in_portal","submitted":false,"message":"Staged as an unsubmitted draft in the On portal. Review and place it in Bridge to Brands.","source":"brdg2b","portal":{"url":"https://backstage.on-running.com/reorder/drafts/RO-884213","draft_id":"RO-884213","order_reference":"DS-1016-JANE","login_url":"https://backstage.on-running.com/login","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft RO-884213 as the On portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing."},"baskets":[{"basket_id":"RO-884213","ship_to":"Fleet Feet Columbia (613907)","po":"DS-1016-JANE","total_pieces":1,"portal_url":"https://backstage.on-running.com/reorder/drafts/RO-884213"}],"po":"DS-1016-JANE","ship_to_ref":"613907","surface":"rest","api_key_name":"Storefront integration","lines":{"staged":[{"variant_id":"3MD10340123-7.5","upc":null,"sku":null,"quantity":1,"unit_price":"80.00","currency":"USD"}],"skipped":[{"variant_id":null,"upc":"195394123456","sku":null,"quantity":1,"reason":"no inventory at this ship-to"}],"confirmed":[]},"vendor":null,"shipments":[],"error":null,"draft_left_note":null,"draft_acknowledged_at":null,"created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}},"example_2":{"summary":"Order","value":{"order_id":"ord_01JA2ZB3C4D5E6F7G8H9J0K1M2","brand":"brooks","kind":"fill_in","status":"partial","submitted":false,"message":"Staged 4 of 5 pairs as an unsubmitted basket in the Brooks portal; 1 line was skipped. Review and place it in Bridge to Brands.","source":"brdg2b","portal":{"url":"https://fasttrack.brooksrunning.com/cart?basket=B-552901","draft_id":"B-552901","order_reference":"FILL-1016-COLA","login_url":"https://fasttrack.brooksrunning.com/login","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft B-552901 as the Brooks portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing."},"baskets":[{"basket_id":"B-552901","ship_to":"Fleet Feet Columbia (1002)","po":"FILL-1016-COLA","total_pieces":4,"portal_url":"https://fasttrack.brooksrunning.com/cart?basket=B-552901"}],"po":"FILL-1016-COLA","ship_to_ref":"1002","surface":"rest","api_key_name":"Storefront integration","lines":{"staged":[{"variant_id":"1204431B189.070","upc":null,"sku":null,"quantity":2,"unit_price":"70.00","currency":"USD"},{"variant_id":"1204431B189.080","upc":null,"sku":"1204431B189","quantity":1,"unit_price":"70.00","currency":"USD"},{"variant_id":"1204431B189.095","upc":null,"sku":null,"quantity":1,"unit_price":"70.00","currency":"USD"}],"skipped":[{"variant_id":null,"upc":"195394123456","sku":null,"quantity":1,"reason":"unresolved"}],"confirmed":[]},"vendor":null,"shipments":[],"error":null,"draft_left_note":null,"draft_acknowledged_at":null,"created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `not_found`, `brand_not_supported`, `account_not_found`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"Not found","value":{"type":"https://brdg2b.ai/problems/not_found","title":"Not found","status":404,"detail":"no such order","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"brand_not_supported":{"summary":"Brand not supported","value":{"type":"https://brdg2b.ai/problems/brand_not_supported","title":"Brand not supported","status":404,"detail":"no such brand","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"account_not_found":{"summary":"Account not found","value":{"type":"https://brdg2b.ai/problems/account_not_found","title":"Account not found","status":404,"detail":"Brooks has no account 'amazon'; its accounts are \"Retail stores\", \"Amazon FBA\"","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"409":{"description":"Problem: `conflict`, `brand_not_connected`, `credentials_invalid`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Conflict","value":{"type":"https://brdg2b.ai/problems/conflict","title":"Conflict","status":409,"detail":"idempotency key was used with a different request","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"brand_not_connected":{"summary":"Brand not connected","value":{"type":"https://brdg2b.ai/problems/brand_not_connected","title":"Brand not connected","status":409,"detail":"This account has not connected this brand's dealer portal.","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"credentials_invalid":{"summary":"Portal credentials invalid","value":{"type":"https://brdg2b.ai/problems/credentials_invalid","title":"Portal credentials invalid","status":409,"detail":"The brand's portal rejected the saved login.","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"422":{"description":"Problem: `capability_unavailable`, `portal_rejected`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"capability_unavailable":{"summary":"Capability unavailable","value":{"type":"https://brdg2b.ai/problems/capability_unavailable","title":"Capability unavailable","status":422,"detail":"this brand has no catalog search","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"portal_rejected":{"summary":"Portal rejected the request","value":{"type":"https://brdg2b.ai/problems/portal_rejected","title":"Portal rejected the request","status":422,"detail":"The brand's portal refused this request.","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"502":{"description":"Problem: `portal_changed`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_changed":{"summary":"Portal changed","value":{"type":"https://brdg2b.ai/problems/portal_changed","title":"Portal changed","status":502,"detail":"The brand's portal answered in an unexpected shape.","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"503":{"description":"Problem: `portal_down`, `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_down":{"summary":"Portal unavailable","value":{"type":"https://brdg2b.ai/problems/portal_down","title":"Portal unavailable","status":503,"detail":"The brand's portal is not answering right now.","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks","retry_after":60}},"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/orders/{order_id}/submit","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"Submit a staged order to the brand (place it) — reference page","url":"https://brdg2b.ai/docs/api/submit-order"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","not_found","conflict","capability_unavailable","brand_not_supported","account_not_found","brand_not_connected","credentials_invalid","portal_down","portal_changed","portal_rejected","unavailable","internal"],"x-metering":{"metered":true,"operation":"order_submit","counts":"One `order_submit` usage event per call that reaches the gate; a repeat on an order already submitting is not metered.","recorded_by":"gateway"},"x-rate-limit":{"class":"orders","per_key":["10/minute"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/orders/{order_id}/cancel":{"post":{"tags":["Orders"],"summary":"Cancel a submitted order where the brand allows it","description":"**What it does.** Asks the brand's portal to cancel every vendor order of a `submitted` order.\n\n**When to call it.** Call it only when the user wants a placed order cancelled and the brand's `submit_cancel_window` allows it; otherwise tell them to contact the brand.\n\n**Inputs.** `order_id` (path). No body.\n\n**Output.** The `Order` with `status: cancelled`.\n\n**Metering.** Not metered.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `not_found` (404): The order, product or shipment does not exist for this account. → Check the id; list the collection to find the right one. Do not retry.\n- `conflict` (409): The request conflicts with current state: an Idempotency-Key reused with a different body, or an order that is not in the state this action needs. → Read the resource again; use a new Idempotency-Key for a different order. Do not retry unchanged.\n- `capability_unavailable` (422): The brand's connector does not offer this (for example catalog search, drop-ship, or future ordering). → Check capabilities in GET /v1/brands/{brand} and use another route (for example lookup by UPC instead of search). Do not retry.\n- `brand_not_supported` (404): The brand code in the path or body is not a brand Bridge to Brands supports. → Call GET /v1/brands for the valid codes. Do not retry.\n- `account_not_found` (404): The account (one of the retailer's logins to this brand) named in the request is not one of the brand's accounts. The detail lists the valid account names. → Pick one of the listed names (or ids from GET /v1/accounts), or omit account to use the brand's default account. Never guess: when the user's words do not clearly match one account, ask them.\n- `brand_not_connected` (409): The account has no enabled connection to this brand's dealer portal. → Tell the account owner to connect the brand at app.brdg2b.ai/brands. Do not retry until they have.\n- `credentials_invalid` (409): The brand's portal rejected the saved login (password changed or account locked). → Tell the account owner to re-enter the portal password at app.brdg2b.ai/brands. API keys can never do this. Do not retry.\n- `portal_down` (503): The brand's portal is down, slow, or refused the session; other brands are unaffected. → Retry after Retry-After seconds; keep serving other brands.\n- `portal_changed` (502): The brand's portal answered in a shape we no longer understand; our team is alerted. → Do not retry now; try again later, or finish in the portal window from the order in Bridge to Brands.\n- `portal_rejected` (422): The brand's portal refused the request (the dealer account is not entitled, or the portal refused a line or ship-to). → Show the user the problem; check the ship-to and lines. Do not retry unchanged.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 10/minute (class `orders`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`.\n\n**Brand variation.** Most brands allow no cancel through Bridge to Brands (`capability_unavailable` with what to do instead). Read GET /v1/brands/{brand} capabilities rather than hard-coding a brand list; capabilities change as connectors gain features.","operationId":"cancel_order","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,80}$","description":"Order id returned by POST /v1/orders or GET /v1/orders.","examples":["ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W"],"title":"Order Id"},"description":"Order id returned by POST /v1/orders or GET /v1/orders.","example":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"examples":{"example_1":{"summary":"Order","value":{"order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"on","kind":"drop_ship","status":"staged_in_portal","submitted":false,"message":"Staged as an unsubmitted draft in the On portal. Review and place it in Bridge to Brands.","source":"brdg2b","portal":{"url":"https://backstage.on-running.com/reorder/drafts/RO-884213","draft_id":"RO-884213","order_reference":"DS-1016-JANE","login_url":"https://backstage.on-running.com/login","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft RO-884213 as the On portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing."},"baskets":[{"basket_id":"RO-884213","ship_to":"Fleet Feet Columbia (613907)","po":"DS-1016-JANE","total_pieces":1,"portal_url":"https://backstage.on-running.com/reorder/drafts/RO-884213"}],"po":"DS-1016-JANE","ship_to_ref":"613907","surface":"rest","api_key_name":"Storefront integration","lines":{"staged":[{"variant_id":"3MD10340123-7.5","upc":null,"sku":null,"quantity":1,"unit_price":"80.00","currency":"USD"}],"skipped":[{"variant_id":null,"upc":"195394123456","sku":null,"quantity":1,"reason":"no inventory at this ship-to"}],"confirmed":[]},"vendor":null,"shipments":[],"error":null,"draft_left_note":null,"draft_acknowledged_at":null,"created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}},"example_2":{"summary":"Order","value":{"order_id":"ord_01JA2ZB3C4D5E6F7G8H9J0K1M2","brand":"brooks","kind":"fill_in","status":"partial","submitted":false,"message":"Staged 4 of 5 pairs as an unsubmitted basket in the Brooks portal; 1 line was skipped. Review and place it in Bridge to Brands.","source":"brdg2b","portal":{"url":"https://fasttrack.brooksrunning.com/cart?basket=B-552901","draft_id":"B-552901","order_reference":"FILL-1016-COLA","login_url":"https://fasttrack.brooksrunning.com/login","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft B-552901 as the Brooks portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing."},"baskets":[{"basket_id":"B-552901","ship_to":"Fleet Feet Columbia (1002)","po":"FILL-1016-COLA","total_pieces":4,"portal_url":"https://fasttrack.brooksrunning.com/cart?basket=B-552901"}],"po":"FILL-1016-COLA","ship_to_ref":"1002","surface":"rest","api_key_name":"Storefront integration","lines":{"staged":[{"variant_id":"1204431B189.070","upc":null,"sku":null,"quantity":2,"unit_price":"70.00","currency":"USD"},{"variant_id":"1204431B189.080","upc":null,"sku":"1204431B189","quantity":1,"unit_price":"70.00","currency":"USD"},{"variant_id":"1204431B189.095","upc":null,"sku":null,"quantity":1,"unit_price":"70.00","currency":"USD"}],"skipped":[{"variant_id":null,"upc":"195394123456","sku":null,"quantity":1,"reason":"unresolved"}],"confirmed":[]},"vendor":null,"shipments":[],"error":null,"draft_left_note":null,"draft_acknowledged_at":null,"created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `not_found`, `brand_not_supported`, `account_not_found`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"Not found","value":{"type":"https://brdg2b.ai/problems/not_found","title":"Not found","status":404,"detail":"no such order","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"brand_not_supported":{"summary":"Brand not supported","value":{"type":"https://brdg2b.ai/problems/brand_not_supported","title":"Brand not supported","status":404,"detail":"no such brand","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"account_not_found":{"summary":"Account not found","value":{"type":"https://brdg2b.ai/problems/account_not_found","title":"Account not found","status":404,"detail":"Brooks has no account 'amazon'; its accounts are \"Retail stores\", \"Amazon FBA\"","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"409":{"description":"Problem: `conflict`, `brand_not_connected`, `credentials_invalid`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"conflict":{"summary":"Conflict","value":{"type":"https://brdg2b.ai/problems/conflict","title":"Conflict","status":409,"detail":"idempotency key was used with a different request","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"brand_not_connected":{"summary":"Brand not connected","value":{"type":"https://brdg2b.ai/problems/brand_not_connected","title":"Brand not connected","status":409,"detail":"This account has not connected this brand's dealer portal.","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"credentials_invalid":{"summary":"Portal credentials invalid","value":{"type":"https://brdg2b.ai/problems/credentials_invalid","title":"Portal credentials invalid","status":409,"detail":"The brand's portal rejected the saved login.","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"422":{"description":"Problem: `capability_unavailable`, `portal_rejected`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"capability_unavailable":{"summary":"Capability unavailable","value":{"type":"https://brdg2b.ai/problems/capability_unavailable","title":"Capability unavailable","status":422,"detail":"this brand has no catalog search","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"portal_rejected":{"summary":"Portal rejected the request","value":{"type":"https://brdg2b.ai/problems/portal_rejected","title":"Portal rejected the request","status":422,"detail":"The brand's portal refused this request.","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"502":{"description":"Problem: `portal_changed`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_changed":{"summary":"Portal changed","value":{"type":"https://brdg2b.ai/problems/portal_changed","title":"Portal changed","status":502,"detail":"The brand's portal answered in an unexpected shape.","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"503":{"description":"Problem: `portal_down`, `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_down":{"summary":"Portal unavailable","value":{"type":"https://brdg2b.ai/problems/portal_down","title":"Portal unavailable","status":503,"detail":"The brand's portal is not answering right now.","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks","retry_after":60}},"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/orders/{order_id}/cancel","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"Cancel a submitted order where the brand allows it — reference page","url":"https://brdg2b.ai/docs/api/cancel-order"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","not_found","conflict","capability_unavailable","brand_not_supported","account_not_found","brand_not_connected","credentials_invalid","portal_down","portal_changed","portal_rejected","unavailable","internal"],"x-metering":{"metered":false,"operation":null,"counts":"Not metered.","recorded_by":"gateway"},"x-rate-limit":{"class":"orders","per_key":["10/minute"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/orders/{order_id}/shipments":{"get":{"tags":["Shipments"],"summary":"Get an order's shipments (tracking)","description":"**What it does.** Returns the tracked shipments of one order.\n\n**When to call it.** Call it when the user asks where an order is.\n\n**Inputs.** `order_id` (path).\n\n**Output.** `{data: Shipment[], next_cursor: null, meta}`. A `Shipment` has `carrier`, `tracking_number`, `tracking_url` (show it), `shipped_at`, `delivered_at`, `units`, `lines[]`.\n\n**Metering.** Not metered.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `not_found` (404): The order, product or shipment does not exist for this account. → Check the id; list the collection to find the right one. Do not retry.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 60/minute and 10/10second (class `order_reads`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`.\n\n**Brand variation.** Tracking exists only for brands with `capabilities.order_feed = true`; a drop-ship usually has one shipment, a multi-store fill-in several.","operationId":"list_order_shipments","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,80}$","description":"Order id returned by POST /v1/orders or GET /v1/orders.","examples":["ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W"],"title":"Order Id"},"description":"Order id returned by POST /v1/orders or GET /v1/orders.","example":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentPage"},"examples":{"example_1":{"summary":"ShipmentPage","value":{"data":[{"shipment_id":"shp_01JA3B4C5D6E7F8G9H0J1K2M3N","order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks","carrier":"UPS","tracking_number":"1Z999AA10123456784","tracking_url":"https://www.ups.com/track?tracknum=1Z999AA10123456784","shipped_at":"2026-10-18T00:00:00Z","delivered_at":null,"units":2,"lines":[{"variant_id":"1104541D033.095","quantity":2}]}],"next_cursor":null,"meta":{"count":1,"limit":25}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/orders/{order_id}/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/orders/{order_id}/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/orders/{order_id}/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/orders/{order_id}/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `not_found`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"Not found","value":{"type":"https://brdg2b.ai/problems/not_found","title":"Not found","status":404,"detail":"no such order","instance":"/v1/orders/{order_id}/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/orders/{order_id}/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/orders/{order_id}/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"503":{"description":"Problem: `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/orders/{order_id}/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"Get an order's shipments (tracking) — reference page","url":"https://brdg2b.ai/docs/api/list-order-shipments"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","not_found","unavailable","internal"],"x-metering":{"metered":false,"operation":null,"counts":"Not metered.","recorded_by":"gateway"},"x-rate-limit":{"class":"order_reads","per_key":["60/minute","10/10second"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/orders/{order_id}/refresh":{"post":{"tags":["Orders"],"summary":"Re-read an order from the portal now","description":"**What it does.** Asks the brand's portal for this order's latest status, confirmation and tracking now, instead of waiting for the next feed pass.\n\n**When to call it.** Call it when the user needs a fresher status than `vendor.as_of`; otherwise rely on the feed. Do not call it in a loop.\n\n**Inputs.** `order_id` (path). No body.\n\n**Output.** `202 Accepted` with the `Order` as re-read.\n\n**Metering.** One usage event per call (operation `order_refresh`): it is a portal read.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `not_found` (404): The order, product or shipment does not exist for this account. → Check the id; list the collection to find the right one. Do not retry.\n- `brand_not_supported` (404): The brand code in the path or body is not a brand Bridge to Brands supports. → Call GET /v1/brands for the valid codes. Do not retry.\n- `account_not_found` (404): The account (one of the retailer's logins to this brand) named in the request is not one of the brand's accounts. The detail lists the valid account names. → Pick one of the listed names (or ids from GET /v1/accounts), or omit account to use the brand's default account. Never guess: when the user's words do not clearly match one account, ask them.\n- `brand_not_connected` (409): The account has no enabled connection to this brand's dealer portal. → Tell the account owner to connect the brand at app.brdg2b.ai/brands. Do not retry until they have.\n- `credentials_invalid` (409): The brand's portal rejected the saved login (password changed or account locked). → Tell the account owner to re-enter the portal password at app.brdg2b.ai/brands. API keys can never do this. Do not retry.\n- `portal_down` (503): The brand's portal is down, slow, or refused the session; other brands are unaffected. → Retry after Retry-After seconds; keep serving other brands.\n- `portal_changed` (502): The brand's portal answered in a shape we no longer understand; our team is alerted. → Do not retry now; try again later, or finish in the portal window from the order in Bridge to Brands.\n- `portal_rejected` (422): The brand's portal refused the request (the dealer account is not entitled, or the portal refused a line or ship-to). → Show the user the problem; check the ship-to and lines. Do not retry unchanged.\n- `capability_unavailable` (422): The brand's connector does not offer this (for example catalog search, drop-ship, or future ordering). → Check capabilities in GET /v1/brands/{brand} and use another route (for example lookup by UPC instead of search). Do not retry.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 10/minute (class `orders`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`.\n\n**Brand variation.** Needs `capabilities.order_feed = true`; other brands return `capability_unavailable`.","operationId":"refresh_order","parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,80}$","description":"Order id returned by POST /v1/orders or GET /v1/orders.","examples":["ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W"],"title":"Order Id"},"description":"Order id returned by POST /v1/orders or GET /v1/orders.","example":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}],"responses":{"202":{"description":"Accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"},"examples":{"example_1":{"summary":"Order","value":{"order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"on","kind":"drop_ship","status":"staged_in_portal","submitted":false,"message":"Staged as an unsubmitted draft in the On portal. Review and place it in Bridge to Brands.","source":"brdg2b","portal":{"url":"https://backstage.on-running.com/reorder/drafts/RO-884213","draft_id":"RO-884213","order_reference":"DS-1016-JANE","login_url":"https://backstage.on-running.com/login","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft RO-884213 as the On portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing."},"baskets":[{"basket_id":"RO-884213","ship_to":"Fleet Feet Columbia (613907)","po":"DS-1016-JANE","total_pieces":1,"portal_url":"https://backstage.on-running.com/reorder/drafts/RO-884213"}],"po":"DS-1016-JANE","ship_to_ref":"613907","surface":"rest","api_key_name":"Storefront integration","lines":{"staged":[{"variant_id":"3MD10340123-7.5","upc":null,"sku":null,"quantity":1,"unit_price":"80.00","currency":"USD"}],"skipped":[{"variant_id":null,"upc":"195394123456","sku":null,"quantity":1,"reason":"no inventory at this ship-to"}],"confirmed":[]},"vendor":null,"shipments":[],"error":null,"draft_left_note":null,"draft_acknowledged_at":null,"created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}},"example_2":{"summary":"Order","value":{"order_id":"ord_01JA2ZB3C4D5E6F7G8H9J0K1M2","brand":"brooks","kind":"fill_in","status":"partial","submitted":false,"message":"Staged 4 of 5 pairs as an unsubmitted basket in the Brooks portal; 1 line was skipped. Review and place it in Bridge to Brands.","source":"brdg2b","portal":{"url":"https://fasttrack.brooksrunning.com/cart?basket=B-552901","draft_id":"B-552901","order_reference":"FILL-1016-COLA","login_url":"https://fasttrack.brooksrunning.com/login","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft B-552901 as the Brooks portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing."},"baskets":[{"basket_id":"B-552901","ship_to":"Fleet Feet Columbia (1002)","po":"FILL-1016-COLA","total_pieces":4,"portal_url":"https://fasttrack.brooksrunning.com/cart?basket=B-552901"}],"po":"FILL-1016-COLA","ship_to_ref":"1002","surface":"rest","api_key_name":"Storefront integration","lines":{"staged":[{"variant_id":"1204431B189.070","upc":null,"sku":null,"quantity":2,"unit_price":"70.00","currency":"USD"},{"variant_id":"1204431B189.080","upc":null,"sku":"1204431B189","quantity":1,"unit_price":"70.00","currency":"USD"},{"variant_id":"1204431B189.095","upc":null,"sku":null,"quantity":1,"unit_price":"70.00","currency":"USD"}],"skipped":[{"variant_id":null,"upc":"195394123456","sku":null,"quantity":1,"reason":"unresolved"}],"confirmed":[]},"vendor":null,"shipments":[],"error":null,"draft_left_note":null,"draft_acknowledged_at":null,"created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"404":{"description":"Problem: `not_found`, `brand_not_supported`, `account_not_found`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"not_found":{"summary":"Not found","value":{"type":"https://brdg2b.ai/problems/not_found","title":"Not found","status":404,"detail":"no such order","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"brand_not_supported":{"summary":"Brand not supported","value":{"type":"https://brdg2b.ai/problems/brand_not_supported","title":"Brand not supported","status":404,"detail":"no such brand","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"account_not_found":{"summary":"Account not found","value":{"type":"https://brdg2b.ai/problems/account_not_found","title":"Account not found","status":404,"detail":"Brooks has no account 'amazon'; its accounts are \"Retail stores\", \"Amazon FBA\"","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"409":{"description":"Problem: `brand_not_connected`, `credentials_invalid`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"brand_not_connected":{"summary":"Brand not connected","value":{"type":"https://brdg2b.ai/problems/brand_not_connected","title":"Brand not connected","status":409,"detail":"This account has not connected this brand's dealer portal.","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"credentials_invalid":{"summary":"Portal credentials invalid","value":{"type":"https://brdg2b.ai/problems/credentials_invalid","title":"Portal credentials invalid","status":409,"detail":"The brand's portal rejected the saved login.","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"422":{"description":"Problem: `portal_rejected`, `capability_unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_rejected":{"summary":"Portal rejected the request","value":{"type":"https://brdg2b.ai/problems/portal_rejected","title":"Portal rejected the request","status":422,"detail":"The brand's portal refused this request.","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}},"capability_unavailable":{"summary":"Capability unavailable","value":{"type":"https://brdg2b.ai/problems/capability_unavailable","title":"Capability unavailable","status":422,"detail":"this brand has no catalog search","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"502":{"description":"Problem: `portal_changed`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_changed":{"summary":"Portal changed","value":{"type":"https://brdg2b.ai/problems/portal_changed","title":"Portal changed","status":502,"detail":"The brand's portal answered in an unexpected shape.","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks"}}}}}},"503":{"description":"Problem: `portal_down`, `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"portal_down":{"summary":"Portal unavailable","value":{"type":"https://brdg2b.ai/problems/portal_down","title":"Portal unavailable","status":503,"detail":"The brand's portal is not answering right now.","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks","retry_after":60}},"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/orders/{order_id}/refresh","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"Re-read an order from the portal now — reference page","url":"https://brdg2b.ai/docs/api/refresh-order"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","not_found","brand_not_supported","account_not_found","brand_not_connected","credentials_invalid","portal_down","portal_changed","portal_rejected","capability_unavailable","unavailable","internal"],"x-metering":{"metered":true,"operation":"order_refresh","counts":"One usage event per call (operation `order_refresh`): it is a portal read.","recorded_by":"gateway"},"x-rate-limit":{"class":"orders","per_key":["10/minute"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/shipments":{"get":{"tags":["Shipments"],"summary":"List shipments across brands","description":"**What it does.** Lists every tracked shipment across brands, newest first — what is arriving.\n\n**When to call it.** Call it for a receiving view (\"what's arriving this week\").\n\n**Inputs.** Query, all optional: `since` (RFC 3339), `brand`; `limit` (1–100, default 25) and `cursor` (the previous page's `next_cursor`).\n\n**Output.** `{data: Shipment[], next_cursor, meta}`.\n\n**Metering.** Not metered.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 60/minute and 10/10second (class `order_reads`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`.\n\n**Brand variation.** Only brands with `capabilities.order_feed = true` report shipments.","operationId":"list_shipments","parameters":[{"name":"since","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only items at or after this time (RFC 3339 with offset).","examples":["2026-10-01T00:00:00Z"],"title":"Since"},"description":"Only items at or after this time (RFC 3339 with offset).","example":"2026-10-01T00:00:00Z"},{"name":"brand","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,39}$"},{"type":"null"}],"description":"Only this brand.","examples":["brooks"],"title":"Brand"},"description":"Only this brand."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":512},{"type":"null"}],"description":"Opaque cursor: the previous page's next_cursor.","examples":["b3JkOjI1"],"title":"Cursor"},"description":"Opaque cursor: the previous page's next_cursor."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size, 1–100.","examples":[25],"default":25,"title":"Limit"},"description":"Page size, 1–100."}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipmentPage"},"examples":{"example_1":{"summary":"ShipmentPage","value":{"data":[{"shipment_id":"shp_01JA3B4C5D6E7F8G9H0J1K2M3N","order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","brand":"brooks","carrier":"UPS","tracking_number":"1Z999AA10123456784","tracking_url":"https://www.ups.com/track?tracknum=1Z999AA10123456784","shipped_at":"2026-10-18T00:00:00Z","delivered_at":null,"units":2,"lines":[{"variant_id":"1104541D033.095","quantity":2}]}],"next_cursor":null,"meta":{"count":1,"limit":25}}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"503":{"description":"Problem: `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/shipments","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"List shipments across brands — reference page","url":"https://brdg2b.ai/docs/api/list-shipments"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","unavailable","internal"],"x-metering":{"metered":false,"operation":null,"counts":"Not metered.","recorded_by":"gateway"},"x-rate-limit":{"class":"order_reads","per_key":["60/minute","10/10second"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/usage":{"get":{"tags":["Usage"],"summary":"Your key's own usage counts","description":"**What it does.** Returns the calling key's own usage: requests, results, orders, lines and units, by outcome, grouped by day, brand or operation.\n\n**When to call it.** Call it to report or budget your own consumption; the cross-key dashboard is in the web app.\n\n**Inputs.** Query, all optional: `from` and `to` (RFC 3339; default the last 30 days up to now), `group_by` (`day` default, `brand`, `operation`).\n\n**Output.** `UsageReport`: `api_key_id`, `from`, `to`, `group_by`, `totals`, `groups[] {key, counts}`.\n\n**Metering.** Not metered.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 60/minute and 10/10second (class `catalog`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`. The window is at most 400 days.\n\n**Brand variation.** None.","operationId":"get_usage","parameters":[{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Window start, RFC 3339 (default: 30 days before `to`).","examples":["2026-10-01T00:00:00Z"],"title":"From"},"description":"Window start, RFC 3339 (default: 30 days before `to`)."},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Window end, RFC 3339 (default: now).","examples":["2026-10-16T00:00:00Z"],"title":"To"},"description":"Window end, RFC 3339 (default: now)."},{"name":"group_by","in":"query","required":false,"schema":{"$ref":"#/components/schemas/UsageGroupBy","description":"day, brand or operation.","examples":["brand"],"default":"day"},"description":"day, brand or operation.","example":"brand"}],"responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageReport"},"examples":{"example_1":{"summary":"UsageReport","value":{"api_key_id":"key_01JA2Z9K7Q8M3N4P5R6S7T8V9W","from":"2026-10-01T00:00:00Z","to":"2026-10-16T15:04:05Z","group_by":"day","totals":{"requests":120,"results":2400,"orders":3,"lines":14,"units":22,"by_status":{"ok":117,"portal_down":3}},"groups":[{"key":"2026-10-16","counts":{"requests":120,"results":2400,"orders":3,"lines":14,"units":22,"by_status":{"ok":117,"portal_down":3}}}]}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/usage","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/usage","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/usage","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/usage","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/usage","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/usage","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"503":{"description":"Problem: `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/usage","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"Your key's own usage counts — reference page","url":"https://brdg2b.ai/docs/api/get-usage"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","unavailable","internal"],"x-metering":{"metered":false,"operation":null,"counts":"Not metered.","recorded_by":"gateway"},"x-rate-limit":{"class":"catalog","per_key":["60/minute","10/10second"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/brand-requests":{"get":{"tags":["Brands"],"summary":"List this account's brand requests","description":"**What it does.** Lists this account's requests for new brands and where each stands.\n\n**When to call it.** Call it before POST /v1/brand-requests, or when the user asks whether a requested brand is ready.\n\n**Inputs.** None.\n\n**Output.** `{data: BrandRequest[]}`, newest first (see POST /v1/brand-requests). When `status` is `available`, `resolved_brand_code` is a brand in GET /v1/brands.\n\n**Metering.** Not metered.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 60/minute and 10/10second (class `catalog`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`.\n\n**Brand variation.** None.","operationId":"list_brand_requests","responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandRequestList"},"examples":{"example_1":{"summary":"BrandRequestList","value":{"data":[{"id":"breq_01JA2Z9K7Q8M3N4P5R6S7T8V9W","name":"Topo Athletic","portal_url":"https://b2b.topoathletic.com/login","has_credentials":false,"status":"pending","status_note":null,"resolved_brand_code":null,"requested_by":"key_01JA2Z9K7Q8M3N4P5R6S7T8V9W","created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}]}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/brand-requests","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/brand-requests","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/brand-requests","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/brand-requests","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/brand-requests","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"503":{"description":"Problem: `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/brand-requests","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"List this account's brand requests — reference page","url":"https://brdg2b.ai/docs/api/list-brand-requests"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","unavailable","internal"],"x-metering":{"metered":false,"operation":null,"counts":"Not metered.","recorded_by":"gateway"},"x-rate-limit":{"class":"catalog","per_key":["60/minute","10/10second"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}},"post":{"tags":["Brands"],"summary":"Ask for a brand that is not supported yet","description":"**What it does.** Records a request that Bridge to Brands build a connector for a brand's dealer portal that is not in GET /v1/brands.\n\n**When to call it.** Call it only after GET /v1/brands shows the brand is missing and the user wants it; call GET /v1/brand-requests first to avoid asking twice. Then tell the user the account owner can add the portal login at app.brdg2b.ai/brands so we can build and connect it.\n\n**Inputs.** Body: `name` (1–80 characters, e.g. `Topo Athletic`); `portal_url` (the https sign-in page of the dealer portal, e.g. `https://b2b.topoathletic.com/login`); `note` (optional, ≤ 1000 characters). There is no field for a username or password: keys and agents never carry portal logins.\n\n**Output.** `201 Created` with the `BrandRequest`: `id`, `name`, `portal_url`, `has_credentials`, `status` (`pending` at first; then `in_review`, `building`, `available` or `declined`), `status_note`, `resolved_brand_code` (the new brand code once available), `requested_by`, `created_at`, `updated_at`.\n\n**Metering.** Not metered: no portal is contacted.\n\n**Failure modes.** \n- `unauthorized` (401): No API key, or the key is unknown, malformed, revoked, expired, or used from an IP outside its allowlist. → Send Authorization: Bearer b2b_live_… with a current key; ask the account owner for a new key at app.brdg2b.ai/keys. Do not retry with the same key.\n- `forbidden` (403): The key is valid but its scopes or brand allowlist do not cover this operation (for example a read-only key placing an order). → Use a key with the needed scope (orders; orders:submit to submit, authorised by the account owner at app.brdg2b.ai/keys) or brand; ask the account owner. Do not retry.\n- `terms_required` (403): The account owner has not accepted the current Terms (grace over). → Tell the account owner to sign in at app.brdg2b.ai and accept the Terms. Keys and agents cannot accept them. Do not retry until they have.\n- `rate_limited` (429): This key (or its account, or the brand's portal) is over its rate limit. → Wait Retry-After seconds, then retry. Batch with POST /lookup and cache as_of instead of polling.\n- `validation_error` (400): The request failed validation: a missing or malformed field, an unknown field, a missing Idempotency-Key, or a rule such as a PO longer than the brand's po_max_length. → Fix the fields listed in errors[] and send again; do not retry unchanged.\n- `unavailable` (503): A Bridge to Brands dependency (database or worker) did not answer in time. → Retry after Retry-After seconds.\n- `internal` (500): Something failed on our side. → Retry once after a few seconds; if it repeats, contact support with the request_id.\n\n**Limits.** Rate limit per key: 60/minute and 10/10second (class `catalog`), and 600/minute per account across all its keys; over the limit returns `429 rate_limited` with `Retry-After`.\n\n**Brand variation.** None. Requests for the same portal host from many accounts are grouped; building a brand takes days, not seconds.","operationId":"create_brand_request","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandRequestCreate"},"examples":{"example_1":{"summary":"example-1","value":{"name":"Topo Athletic","portal_url":"https://b2b.topoathletic.com/login","note":"We order from them monthly."}}}}},"required":true},"responses":{"201":{"description":"OK.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BrandRequest"},"examples":{"example_1":{"summary":"BrandRequest","value":{"id":"breq_01JA2Z9K7Q8M3N4P5R6S7T8V9W","name":"Topo Athletic","portal_url":"https://b2b.topoathletic.com/login","has_credentials":false,"status":"pending","status_note":null,"resolved_brand_code":null,"requested_by":"key_01JA2Z9K7Q8M3N4P5R6S7T8V9W","created_at":"2026-10-16T15:04:05Z","updated_at":"2026-10-16T15:04:05Z"}}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}},"400":{"description":"Problem: `validation_error`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"validation_error":{"summary":"Bad request","value":{"type":"https://brdg2b.ai/problems/validation_error","title":"Bad request","status":400,"detail":"The request failed validation.","instance":"/v1/brand-requests","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","errors":[{"field":"lines.0","message":"Value error, identify the product"}]}}}}}},"401":{"description":"Problem: `unauthorized`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"WWW-Authenticate":{"$ref":"#/components/headers/WWWAuthenticate"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unauthorized":{"summary":"Unauthorized","value":{"type":"https://brdg2b.ai/problems/unauthorized","title":"Unauthorized","status":401,"detail":"invalid API key","instance":"/v1/brand-requests","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"403":{"description":"Problem: `forbidden`, `terms_required`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"forbidden":{"summary":"Forbidden","value":{"type":"https://brdg2b.ai/problems/forbidden","title":"Forbidden","status":403,"detail":"this API key's scope does not allow this operation","instance":"/v1/brand-requests","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}},"terms_required":{"summary":"Terms not accepted","value":{"type":"https://brdg2b.ai/problems/terms_required","title":"Terms not accepted","status":403,"detail":"the account owner must accept the current Terms of Service at app.brdg2b.ai before this account can be used","instance":"/v1/brand-requests","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"429":{"description":"Problem: `rate_limited`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"rate_limited":{"summary":"Too many requests","value":{"type":"https://brdg2b.ai/problems/rate_limited","title":"Too many requests","status":429,"detail":"rate limit exceeded","instance":"/v1/brand-requests","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":6}}}}}},"500":{"description":"Problem: `internal`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"internal":{"summary":"Internal error","value":{"type":"https://brdg2b.ai/problems/internal","title":"Internal error","status":500,"detail":"An unexpected error occurred.","instance":"/v1/brand-requests","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"}}}}}},"503":{"description":"Problem: `unavailable`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"unavailable":{"summary":"Service unavailable","value":{"type":"https://brdg2b.ai/problems/unavailable","title":"Service unavailable","status":503,"detail":"The service is temporarily unavailable.","instance":"/v1/brand-requests","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":30}}}}}}},"externalDocs":{"description":"Ask for a brand that is not supported yet — reference page","url":"https://brdg2b.ai/docs/api/create-brand-request"},"security":[{"ApiKeyBearer":[]}],"x-problems":["unauthorized","forbidden","terms_required","rate_limited","validation_error","unavailable","internal"],"x-metering":{"metered":false,"operation":null,"counts":"Not metered: no portal is contacted.","recorded_by":"gateway"},"x-rate-limit":{"class":"catalog","per_key":["60/minute","10/10second"],"per_account":"600/minute","key":"api_key_id","on_exceed":"429 rate_limited with Retry-After"}}},"/openapi.json":{"get":{"tags":["Meta"],"summary":"This OpenAPI 3.1 document","description":"**What it does.** Returns this API's OpenAPI 3.1 document.\n\n**When to call it.** Fetch it to generate a client or load the API into an agent.\n\n**Inputs.** None.\n\n**Output.** The OpenAPI document as JSON.\n\n**Metering.** Not metered.\n\n**Failure modes.** \nNone specific to this operation.\n\n**Limits.** Not rate limited by key; no authentication needed.\n\n**Brand variation.** None.","operationId":"get_openapi","responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object"},"example":{"openapi":"3.1.0","info":{"title":"Bridge to Brands API","version":"1.0.0"}}}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}}},"externalDocs":{"description":"This OpenAPI 3.1 document — reference page","url":"https://brdg2b.ai/docs/api/openapi"},"security":[],"x-problems":[],"x-metering":{"metered":false,"operation":null,"counts":"Not metered.","recorded_by":"gateway"}}},"/agents.md":{"get":{"tags":["Meta"],"summary":"The agent guide (AGENTS.md)","description":"**What it does.** Returns the one-page Markdown guide for coding agents: the happy path with real requests and responses, the error table and the frugality rules.\n\n**When to call it.** Read it once before integrating.\n\n**Inputs.** None.\n\n**Output.** `text/markdown`.\n\n**Metering.** Not metered.\n\n**Failure modes.** \nNone specific to this operation.\n\n**Limits.** Not rate limited by key; no authentication needed.\n\n**Brand variation.** None.","operationId":"get_agents_md","responses":{"200":{"description":"OK.","content":{"text/markdown":{"schema":{"type":"string"},"example":"# Bridge to Brands — agent guide\n…"}},"headers":{"X-Request-Id":{"$ref":"#/components/headers/XRequestId"}}}},"externalDocs":{"description":"The agent guide (AGENTS.md) — reference page","url":"https://brdg2b.ai/docs/api/for-agents"},"security":[],"x-problems":[],"x-metering":{"metered":false,"operation":null,"counts":"Not metered.","recorded_by":"gateway"}}}},"components":{"schemas":{"Account":{"properties":{"id":{"type":"string","title":"Id","description":"The account id; pass it (or the exact name) as account.","examples":["acct_01JB2C5V1C8ZK3V6Q4X9N7M2PA"]},"brand":{"type":"string","title":"Brand","description":"Brand code.","examples":["brooks"]},"name":{"type":"string","title":"Name","description":"The account's name.","examples":["Retail stores"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"What the account is for, written for people and agents.","examples":["The stores' account; ships to the three stores"]},"default":{"type":"boolean","title":"Default","description":"True for the account used when a call names none.","examples":[true]},"status":{"$ref":"#/components/schemas/ConnectionState","description":"connected | pending | invalid | error | disabled.","examples":["connected"]},"warehouses":{"items":{"type":"string"},"type":"array","title":"Warehouses","description":"Warehouses the portal showed for this login, when the brand's portal lists them (often empty).","examples":[["Brooks DC Indianapolis"]]},"ship_tos":{"$ref":"#/components/schemas/AccountShipTos","description":"The account's stores."}},"additionalProperties":false,"type":"object","required":["id","brand","name","description","default","status","ship_tos"],"title":"Account","description":"One login (\"account\") the retailer holds for a brand.","examples":[{"brand":"brooks","default":true,"description":"The stores' account; ships to the three stores","id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PA","name":"Retail stores","ship_tos":{"count":3,"labels":["Columbia","Lexington","Irmo"]},"status":"connected","warehouses":[]}]},"AccountAvailability":{"properties":{"account":{"$ref":"#/components/schemas/AccountSummary","description":"The account, with its description, so the answer can be explained in the user's words."},"grids":{"items":{"$ref":"#/components/schemas/AvailabilityGrid"},"type":"array","title":"Grids","description":"One grid per colourway (or the one asked for); empty when this account's read failed.","examples":[[{"as_of":"2026-10-16T15:04:05Z","brand":"brooks","cap_applied_by":"server","cap_threshold":200,"color_id":"120443189","color_name":"Black/Ebony/Pink","columns":[{"key":"7.0/B","size":"7","width":"B"}],"price":{"currency":"USD","retail":"140.00","wholesale":"70.00"},"rows":[{"cells":{"7.0/B":{"display":"200+","qty":200}},"ordering_mode":"at_once"},{"cells":{"7.0/B":{"display":"48","qty":48}},"date":"2026-11-15","ordering_mode":"future"}],"stale":false,"status":"ok","style_id":"120443"}]]},"as_of":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"As Of","description":"When this account's portal was asked.","examples":["2026-10-16T15:04:05Z"]},"stale":{"type":"boolean","title":"Stale","description":"True when served from an old snapshot (portal down).","examples":[false]},"error":{"anyOf":[{"$ref":"#/components/schemas/Problem"},{"type":"null"}],"description":"Why this account could not answer; the others still did.","examples":[null]}},"additionalProperties":false,"type":"object","required":["account","grids","as_of","stale","error"],"title":"AccountAvailability","description":"One account's answer in an availability comparison.","examples":[{"account":{"default":false,"description":"Amazon fulfilment account; ships from the Brooks DC to FBA warehouses","id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PB","name":"Amazon FBA"},"as_of":"2026-10-16T15:04:05Z","grids":[],"stale":false}]},"AccountList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Account"},"type":"array","title":"Data","description":"The accounts.","examples":[[{"brand":"brooks","default":true,"description":"The stores' account; ships to the three stores","id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PA","name":"Retail stores","ship_tos":{"count":3,"labels":["Columbia","Lexington","Irmo"]},"status":"connected","warehouses":[]}]]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Always null: one page.","examples":[null]},"meta":{"$ref":"#/components/schemas/PageMeta","description":"Page facts."}},"additionalProperties":false,"type":"object","required":["data","next_cursor","meta"],"title":"AccountList","description":"Every account (login) of every allowed brand, or of one brand.","examples":[{"data":[{"brand":"brooks","default":true,"description":"The stores' account; ships to the three stores","id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PA","name":"Retail stores","ship_tos":{"count":3,"labels":["Columbia","Lexington","Irmo"]},"status":"connected","warehouses":[]}],"meta":{"count":1}}]},"AccountRef":{"properties":{"id":{"type":"string","title":"Id","description":"The account id; pass it (or the exact name) as account.","examples":["acct_01JB2C5V1C8ZK3V6Q4X9N7M2PA"]},"name":{"type":"string","title":"Name","description":"The account's name, written by the retailer.","examples":["Retail stores"]}},"additionalProperties":false,"type":"object","required":["id","name"],"title":"AccountRef","description":"Which of the brand's logins (\"accounts\") an answer came from.\n\nA retailer may hold several logins to one brand (e.g. the stores and\nAmazon), each with its own warehouses, prices and availability. Calls\nthat name no ``account`` use the brand's default account.","examples":[{"id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PA","name":"Retail stores"}]},"AccountShipTos":{"properties":{"count":{"type":"integer","minimum":0,"title":"Count","description":"Number of ship-tos.","examples":[3]},"labels":{"items":{"type":"string"},"type":"array","title":"Labels","description":"Their names (the retailer's label, else the vendor's).","examples":[["Columbia","Lexington","Irmo"]]}},"additionalProperties":false,"type":"object","required":["count","labels"],"title":"AccountShipTos","description":"How many stores the account ships to, and their names.","examples":[{"count":3,"labels":["Columbia","Lexington","Irmo"]}]},"AccountSummary":{"properties":{"id":{"type":"string","title":"Id","description":"The account id.","examples":["acct_01JB2C5V1C8ZK3V6Q4X9N7M2PB"]},"name":{"type":"string","title":"Name","description":"The account's name.","examples":["Amazon FBA"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"What the account is for, written for people and agents; match the user's words against it.","examples":["Amazon fulfilment account; ships from the Brooks DC to FBA warehouses"]},"default":{"type":"boolean","title":"Default","description":"True for the account used when a call names none.","examples":[false]}},"additionalProperties":false,"type":"object","required":["id","name","description","default"],"title":"AccountSummary","description":"An account with the words the retailer wrote for it.","examples":[{"default":false,"description":"Amazon fulfilment account; ships from the Brooks DC to FBA warehouses","id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PB","name":"Amazon FBA"}]},"AvailabilityComparison":{"properties":{"brand":{"type":"string","title":"Brand","description":"Brand code.","examples":["brooks"]},"style_id":{"type":"string","title":"Style Id","description":"Vendor style id.","examples":["120443"]},"color_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Color Id","description":"The colourway asked for; null = every colourway.","examples":["120443189"]},"data":{"items":{"$ref":"#/components/schemas/AccountAvailability"},"type":"array","title":"Data","description":"One entry per account, default first.","examples":[[{"account":{"default":false,"description":"Amazon fulfilment account; ships from the Brooks DC to FBA warehouses","id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PB","name":"Amazon FBA"},"as_of":"2026-10-16T15:04:05Z","grids":[],"stale":false}]]},"meta":{"$ref":"#/components/schemas/PageMeta","description":"count = accounts compared."}},"additionalProperties":false,"type":"object","required":["brand","style_id","color_id","data","meta"],"title":"AvailabilityComparison","description":"Availability of one style on several accounts, side by side.","examples":[{"brand":"brooks","color_id":"120443189","data":[{"account":{"default":false,"description":"Amazon fulfilment account; ships from the Brooks DC to FBA warehouses","id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PB","name":"Amazon FBA"},"as_of":"2026-10-16T15:04:05Z","grids":[],"stale":false}],"meta":{"brand":"brooks","count":1},"style_id":"120443"}]},"AvailabilityGrid":{"properties":{"brand":{"type":"string","title":"Brand","description":"Brand code.","examples":["brooks"]},"style_id":{"type":"string","title":"Style Id","description":"Vendor style id.","examples":["120443"]},"color_id":{"type":"string","title":"Color Id","description":"Vendor colourway id.","examples":["120443189"]},"color_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Color Name","description":"Vendor colour name.","examples":["Black/Ebony/Pink"]},"status":{"$ref":"#/components/schemas/GridStatus","description":"ok = complete; partial = some sizes unknown; unsupported = the brand cannot report this; size_missing = the size is not offered; error = the read failed for this colourway.","examples":["ok"]},"columns":{"items":{"$ref":"#/components/schemas/GridColumn"},"type":"array","title":"Columns","description":"Size columns, in size-run order.","examples":[[{"key":"7.0/B","size":"7","width":"B"}]]},"rows":{"items":{"$ref":"#/components/schemas/GridRow"},"type":"array","title":"Rows","description":"Delivery windows; the date-null at_once row is stock now.","examples":[[{"cells":{"7.0/B":{"display":"200+","qty":200}},"ordering_mode":"at_once"},{"cells":{"7.0/B":{"display":"48","qty":48}},"date":"2026-11-15","ordering_mode":"future"}]]},"cap_threshold":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Cap Threshold","description":"Quantities at or above this display as 'N+'; null = uncapped.","examples":[200]},"cap_applied_by":{"anyOf":[{"$ref":"#/components/schemas/CapAppliedBy"},{"type":"null"}],"description":"server = the vendor caps counts; client = we cap the display but qty is exact.","examples":["server"]},"price":{"anyOf":[{"$ref":"#/components/schemas/Price"},{"type":"null"}],"description":"Colourway price for this dealer."},"as_of":{"type":"string","format":"date-time","title":"As Of","description":"When the portal was asked; cache on this.","examples":["2026-10-16T15:04:05Z"]},"stale":{"type":"boolean","title":"Stale","description":"True when the portal is down and this grid is the last snapshot, older than the usual freshness window; check as_of.","examples":[false]},"account":{"anyOf":[{"$ref":"#/components/schemas/AccountRef"},{"type":"null"}],"description":"The brand login (account) the grid was read on."}},"additionalProperties":false,"type":"object","required":["brand","style_id","color_id","color_name","status","columns","rows","cap_threshold","cap_applied_by","price","as_of","stale"],"title":"AvailabilityGrid","description":"Date × size availability for one colourway (the RunOps canonical shape).","examples":[{"as_of":"2026-10-16T15:04:05Z","brand":"brooks","cap_applied_by":"server","cap_threshold":200,"color_id":"120443189","color_name":"Black/Ebony/Pink","columns":[{"key":"7.0/B","size":"7","width":"B"}],"price":{"currency":"USD","retail":"140.00","wholesale":"70.00"},"rows":[{"cells":{"7.0/B":{"display":"200+","qty":200}},"ordering_mode":"at_once"},{"cells":{"7.0/B":{"display":"48","qty":48}},"date":"2026-11-15","ordering_mode":"future"}],"stale":false,"status":"ok","style_id":"120443"}]},"AvailabilityGridList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/AvailabilityGrid"},"type":"array","title":"Data","description":"One grid per colourway.","examples":[[{"as_of":"2026-10-16T15:04:05Z","brand":"brooks","cap_applied_by":"server","cap_threshold":200,"color_id":"120443189","color_name":"Black/Ebony/Pink","columns":[{"key":"7.0/B","size":"7","width":"B"}],"price":{"currency":"USD","retail":"140.00","wholesale":"70.00"},"rows":[{"cells":{"7.0/B":{"display":"200+","qty":200}},"ordering_mode":"at_once"},{"cells":{"7.0/B":{"display":"48","qty":48}},"date":"2026-11-15","ordering_mode":"future"}],"stale":false,"status":"ok","style_id":"120443"}]]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Always null: all colourways come in one response.","examples":[null]},"meta":{"$ref":"#/components/schemas/PageMeta","description":"Page facts, including as_of."}},"additionalProperties":false,"type":"object","required":["data","next_cursor","meta"],"title":"AvailabilityGridList","description":"One availability grid per colourway of a style.","examples":[{"data":[{"as_of":"2026-10-16T15:04:05Z","brand":"brooks","cap_applied_by":"server","cap_threshold":200,"color_id":"120443189","color_name":"Black/Ebony/Pink","columns":[{"key":"7.0/B","size":"7","width":"B"}],"price":{"currency":"USD","retail":"140.00","wholesale":"70.00"},"rows":[{"cells":{"7.0/B":{"display":"200+","qty":200}},"ordering_mode":"at_once"},{"cells":{"7.0/B":{"display":"48","qty":48}},"date":"2026-11-15","ordering_mode":"future"}],"stale":false,"status":"ok","style_id":"120443"}],"meta":{"as_of":"2026-10-16T15:04:05Z","brand":"brooks","count":1}}]},"Basket":{"properties":{"basket_id":{"type":"string","title":"Basket Id","description":"Vendor container id.","examples":["RO-884213"]},"ship_to":{"type":"string","title":"Ship To","description":"Destination store as the vendor names it.","examples":["Fleet Feet Columbia (613907)"]},"po":{"type":"string","title":"Po","description":"PO on the container.","examples":["DS-1016-JANE"]},"total_pieces":{"type":"integer","title":"Total Pieces","description":"Units in the container.","examples":[1]},"portal_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Portal Url","description":"Link to this container in the portal.","examples":["https://backstage.on-running.com/reorder/drafts/RO-884213"]}},"additionalProperties":false,"type":"object","required":["basket_id","ship_to","po","total_pieces","portal_url"],"title":"Basket","description":"One vendor container (draft/basket/cart) the order was staged into.","examples":[{"basket_id":"RO-884213","po":"DS-1016-JANE","portal_url":"https://backstage.on-running.com/reorder/drafts/RO-884213","ship_to":"Fleet Feet Columbia (613907)","total_pieces":1}]},"Brand":{"properties":{"code":{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,39}$","title":"Code","description":"The brand code used in every path and body.","examples":["brooks"]},"name":{"type":"string","title":"Name","description":"Display name.","examples":["Brooks"]},"platform":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Platform","description":"The portal platform the brand runs on (several brands share NuORDER, Elastic, Envoy…); null for a brand's own portal.","examples":[null,"nuorder"]},"support":{"$ref":"#/components/schemas/Support","description":"supported = live; coming_soon = listed, not callable yet.","examples":["supported"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"One line about the brand's portal.","examples":["Brooks Running FastTrack dealer portal."]},"capabilities":{"$ref":"#/components/schemas/BrandCapabilities","description":"What this brand's connector can do; check before calling."},"connection":{"$ref":"#/components/schemas/BrandConnection","description":"The connection of the brand's default account."},"accounts":{"items":{"$ref":"#/components/schemas/Account"},"type":"array","title":"Accounts","description":"Every login (account) this retailer holds for the brand, default first. Name one as account on any brand call; when there is more than one and the user's request does not say which, ask.","examples":[[{"brand":"brooks","default":true,"description":"The stores' account; ships to the three stores","id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PA","name":"Retail stores","ship_tos":{"count":3,"labels":["Columbia","Lexington","Irmo"]},"status":"connected","warehouses":[]}]]}},"additionalProperties":false,"type":"object","required":["code","name","platform","support","description","capabilities","connection"],"title":"Brand","description":"A supported brand, its capabilities, and this account's connection to it.","examples":[{"accounts":[{"brand":"brooks","default":true,"description":"The stores' account; ships to the three stores","id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PA","name":"Retail stores","ship_tos":{"count":3,"labels":["Columbia","Lexington","Irmo"]},"status":"connected","warehouses":[]}],"capabilities":{"catalog_search":true,"drop_ship":true,"drop_ship_max_per_send":1,"drop_ship_requires_email":false,"drop_ship_requires_phone":false,"future_window_at_stage":false,"order_feed":true,"order_feed_tracking":true,"ordering":true,"ordering_modes":["at_once","future"],"po_max_length":20,"portal_url":"https://fasttrack.brooksrunning.com","portal_window":true,"prices":true,"submit":false,"submit_contract_complete":true,"unmatched_hint":"Brooks SKUs look like 1204431B189 (style 120443, width 1B, colour 189).","width_axis":true},"code":"brooks","connection":{"connected_at":"2026-10-01T12:00:00Z","last_check_at":"2026-10-16T14:55:00Z","status":"connected"},"description":"Brooks Running FastTrack dealer portal.","name":"Brooks","support":"supported"}]},"BrandCapabilities":{"properties":{"catalog_search":{"type":"boolean","title":"Catalog Search","description":"True when GET /brands/{brand}/products (free-text search) works.","examples":[true]},"prices":{"type":"boolean","title":"Prices","description":"True when the portal shows this dealer's wholesale price.","examples":[true]},"width_axis":{"type":"boolean","title":"Width Axis","description":"True when sizes carry a separate width (columns like 7.0/B).","examples":[true]},"ordering_modes":{"items":{"$ref":"#/components/schemas/OrderingMode"},"type":"array","title":"Ordering Modes","description":"Which ordering modes the portal accepts.","examples":[["at_once","future"]]},"ordering":{"type":"boolean","title":"Ordering","description":"True when orders can be staged in this brand's portal.","examples":[true]},"drop_ship":{"type":"boolean","title":"Drop Ship","description":"True when the brand accepts drop-ship orders to a consumer.","examples":[true]},"drop_ship_requires_phone":{"type":"boolean","title":"Drop Ship Requires Phone","description":"True when a drop-ship needs consumer.phone.","examples":[false]},"drop_ship_requires_email":{"type":"boolean","title":"Drop Ship Requires Email","description":"True when a drop-ship needs consumer.email (the STORE's email, never the consumer's).","examples":[false]},"drop_ship_max_per_send":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Drop Ship Max Per Send","description":"Most drop-ship orders the portal takes per send; null = no limit.","examples":[1]},"po_max_length":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Po Max Length","description":"Longest PO the portal accepts; null = no stated limit.","examples":[20]},"submit":{"type":"boolean","title":"Submit","description":"True when the connector can place (submit) orders in this portal; whether an order is placed also needs the brand to be submit-verified and the account's caps and confirmation settings to allow it — otherwise it is staged for review and placing in Bridge to Brands.","examples":[false]},"submit_contract_complete":{"type":"boolean","title":"Submit Contract Complete","description":"True when every portal step of placing an order is built from evidence (it may still await its live test: see submit). False while a step still needs a recorded portal session, or when placing is not built at all; orders are then staged for review and placing in Bridge to Brands.","default":false,"examples":[true]},"order_feed":{"type":"boolean","title":"Order Feed","description":"True when order confirmations and status are read back from the portal (see order_feed_tracking for carrier tracking).","examples":[true]},"order_feed_tracking":{"type":"boolean","title":"Order Feed Tracking","description":"True when the order feed also returns shipments with carrier tracking; false = confirmations and status only (tracking not available for this brand).","default":false,"examples":[true]},"portal_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Portal Url","description":"The portal's home page.","examples":["https://fasttrack.brooksrunning.com"]},"unmatched_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unmatched Hint","description":"How this brand's SKUs look, for when a line cannot be resolved.","examples":["Brooks SKUs look like 1204431B189."]},"portal_window":{"type":"boolean","title":"Portal Window","description":"True when a buyer can open this brand's real portal, already signed in, inside the Bridge web app (the live portal window). Web app only; not an API operation.","default":false,"examples":[true]},"portal_window_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Portal Window Reason","description":"When portal_window is false, the technical reason (the portal's sign-in cannot be reproduced in a browser).","examples":[null]},"future_window_at_stage":{"type":"boolean","title":"Future Window At Stage","description":"True when a future order's delivery window (ship_dates.requested_ship) is set in the portal basket when the order is staged: the lines go into exactly that window, or are skipped when the brand offers none on that date. False = the brand sets the delivery window in its portal; check it before placing (the order's delivery_window.note says so).","default":false,"examples":[false]}},"additionalProperties":false,"type":"object","required":["catalog_search","prices","width_axis","ordering_modes","ordering","drop_ship","drop_ship_requires_phone","drop_ship_requires_email","drop_ship_max_per_send","po_max_length","submit","order_feed","portal_url","unmatched_hint"],"title":"BrandCapabilities","description":"What the brand's connector can do, normalised across brands.","examples":[{"catalog_search":true,"drop_ship":true,"drop_ship_max_per_send":1,"drop_ship_requires_email":false,"drop_ship_requires_phone":false,"future_window_at_stage":false,"order_feed":true,"order_feed_tracking":true,"ordering":true,"ordering_modes":["at_once","future"],"po_max_length":20,"portal_url":"https://fasttrack.brooksrunning.com","portal_window":true,"prices":true,"submit":false,"submit_contract_complete":true,"unmatched_hint":"Brooks SKUs look like 1204431B189 (style 120443, width 1B, colour 189).","width_axis":true}]},"BrandConnection":{"properties":{"status":{"$ref":"#/components/schemas/ConnectionState","description":"connected = ready; pending = saved, not yet checked; invalid = the owner must re-enter the password; error = the portal misbehaved at the last check; disabled = switched off; not_connected = never connected.","examples":["connected"]},"connected_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Connected At","description":"When the connection was first made.","examples":["2026-10-01T12:00:00Z"]},"last_check_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Check At","description":"When the login was last verified against the portal.","examples":["2026-10-16T14:55:00Z"]}},"additionalProperties":false,"type":"object","required":["status","connected_at","last_check_at"],"title":"BrandConnection","description":"This account's connection to the brand's portal.","examples":[{"connected_at":"2026-10-01T12:00:00Z","last_check_at":"2026-10-16T14:55:00Z","status":"connected"}]},"BrandList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Brand"},"type":"array","title":"Data","description":"The brands.","examples":[[{"accounts":[{"brand":"brooks","default":true,"description":"The stores' account; ships to the three stores","id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PA","name":"Retail stores","ship_tos":{"count":3,"labels":["Columbia","Lexington","Irmo"]},"status":"connected","warehouses":[]}],"capabilities":{"catalog_search":true,"drop_ship":true,"drop_ship_max_per_send":1,"drop_ship_requires_email":false,"drop_ship_requires_phone":false,"future_window_at_stage":false,"order_feed":true,"order_feed_tracking":true,"ordering":true,"ordering_modes":["at_once","future"],"po_max_length":20,"portal_url":"https://fasttrack.brooksrunning.com","portal_window":true,"prices":true,"submit":false,"submit_contract_complete":true,"unmatched_hint":"Brooks SKUs look like 1204431B189 (style 120443, width 1B, colour 189).","width_axis":true},"code":"brooks","connection":{"connected_at":"2026-10-01T12:00:00Z","last_check_at":"2026-10-16T14:55:00Z","status":"connected"},"description":"Brooks Running FastTrack dealer portal.","name":"Brooks","support":"supported"}]]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Always null: the brand list is one page.","examples":[null]},"meta":{"$ref":"#/components/schemas/PageMeta","description":"Page facts."}},"additionalProperties":false,"type":"object","required":["data","next_cursor","meta"],"title":"BrandList","description":"Every brand, one page.","examples":[{"data":[{"accounts":[{"brand":"brooks","default":true,"description":"The stores' account; ships to the three stores","id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PA","name":"Retail stores","ship_tos":{"count":3,"labels":["Columbia","Lexington","Irmo"]},"status":"connected","warehouses":[]}],"capabilities":{"catalog_search":true,"drop_ship":true,"drop_ship_max_per_send":1,"drop_ship_requires_email":false,"drop_ship_requires_phone":false,"future_window_at_stage":false,"order_feed":true,"order_feed_tracking":true,"ordering":true,"ordering_modes":["at_once","future"],"po_max_length":20,"portal_url":"https://fasttrack.brooksrunning.com","portal_window":true,"prices":true,"submit":false,"submit_contract_complete":true,"unmatched_hint":"Brooks SKUs look like 1204431B189 (style 120443, width 1B, colour 189).","width_axis":true},"code":"brooks","connection":{"connected_at":"2026-10-01T12:00:00Z","last_check_at":"2026-10-16T14:55:00Z","status":"connected"},"description":"Brooks Running FastTrack dealer portal.","name":"Brooks","support":"supported"}],"meta":{"count":1}}]},"BrandRequest":{"properties":{"id":{"type":"string","title":"Id","description":"Request id.","examples":["breq_01JA2Z9K7Q8M3N4P5R6S7T8V9W"]},"name":{"type":"string","title":"Name","description":"The requested brand.","examples":["Topo Athletic"]},"portal_url":{"type":"string","title":"Portal Url","description":"The dealer portal's sign-in page.","examples":["https://b2b.topoathletic.com/login"]},"has_credentials":{"type":"boolean","title":"Has Credentials","description":"True once the account owner added the portal login in the web app (keys never carry it).","examples":[false]},"status":{"$ref":"#/components/schemas/BrandRequestStatus","description":"pending, in_review, building, available (the brand is in GET /v1/brands as resolved_brand_code) or declined.","examples":["pending"]},"status_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Note","description":"Our team's note on the status.","examples":[null]},"resolved_brand_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resolved Brand Code","description":"The brand code once the request is available.","examples":[null]},"requested_by":{"type":"string","title":"Requested By","description":"The API key id (or user id) that asked.","examples":["key_01JA2Z9K7Q8M3N4P5R6S7T8V9W"]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When it was asked.","examples":["2026-10-16T15:04:05Z"]},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last status change.","examples":["2026-10-16T15:04:05Z"]}},"additionalProperties":false,"type":"object","required":["id","name","portal_url","has_credentials","status","status_note","resolved_brand_code","requested_by","created_at","updated_at"],"title":"BrandRequest","description":"One request for a new brand. The portal login, if any, is never returned.","examples":[{"created_at":"2026-10-16T15:04:05Z","has_credentials":false,"id":"breq_01JA2Z9K7Q8M3N4P5R6S7T8V9W","name":"Topo Athletic","portal_url":"https://b2b.topoathletic.com/login","requested_by":"key_01JA2Z9K7Q8M3N4P5R6S7T8V9W","status":"pending","updated_at":"2026-10-16T15:04:05Z"}]},"BrandRequestCreate":{"properties":{"name":{"type":"string","maxLength":80,"minLength":1,"title":"Name","description":"The brand's name as buyers know it.","examples":["Topo Athletic"]},"portal_url":{"type":"string","maxLength":500,"minLength":9,"pattern":"^https://\\S+$","title":"Portal Url","description":"The https sign-in page of the brand's dealer (B2B) portal.","examples":["https://b2b.topoathletic.com/login"]},"note":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Note","description":"Optional context for our team. Never a password.","examples":["We order from them monthly."]}},"additionalProperties":false,"type":"object","required":["name","portal_url"],"title":"BrandRequestCreate","description":"Ask Bridge to Brands to build a brand that is not in GET /v1/brands.","examples":[{"name":"Topo Athletic","note":"We order from them monthly.","portal_url":"https://b2b.topoathletic.com/login"}]},"BrandRequestList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/BrandRequest"},"type":"array","title":"Data","description":"Requests, newest first.","examples":[[{"created_at":"2026-10-16T15:04:05Z","has_credentials":false,"id":"breq_01JA2Z9K7Q8M3N4P5R6S7T8V9W","name":"Topo Athletic","portal_url":"https://b2b.topoathletic.com/login","requested_by":"key_01JA2Z9K7Q8M3N4P5R6S7T8V9W","status":"pending","updated_at":"2026-10-16T15:04:05Z"}]]}},"additionalProperties":false,"type":"object","required":["data"],"title":"BrandRequestList","description":"This account's brand requests, newest first.","examples":[{"data":[{"created_at":"2026-10-16T15:04:05Z","has_credentials":false,"id":"breq_01JA2Z9K7Q8M3N4P5R6S7T8V9W","name":"Topo Athletic","portal_url":"https://b2b.topoathletic.com/login","requested_by":"key_01JA2Z9K7Q8M3N4P5R6S7T8V9W","status":"pending","updated_at":"2026-10-16T15:04:05Z"}]}]},"BrandRequestStatus":{"type":"string","enum":["pending","in_review","building","available","declined"],"title":"BrandRequestStatus","description":"Where a brand request stands."},"CapAppliedBy":{"type":"string","enum":["client","server"],"title":"CapAppliedBy","description":"Who capped displayed quantities: the vendor (``server``) or us (``client``)."},"Colorway":{"properties":{"color_id":{"type":"string","title":"Color Id","description":"Vendor colourway id; pass it to availability and orders.","examples":["120443189"]},"name":{"type":"string","title":"Name","description":"Vendor colour name.","examples":["Black/Ebony/Pink"]},"image_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Image Url","description":"Vendor product photo, or null.","examples":["https://images.brooksrunning.com/120443189.jpg"]},"price":{"anyOf":[{"$ref":"#/components/schemas/Price"},{"type":"null"}],"description":"Colourway price for this dealer, or null when the portal shows none."}},"additionalProperties":false,"type":"object","required":["color_id","name","image_url","price"],"title":"Colorway","description":"One colour of a style.","examples":[{"color_id":"120443189","image_url":"https://images.brooksrunning.com/120443189.jpg","name":"Black/Ebony/Pink","price":{"currency":"USD","retail":"140.00","wholesale":"70.00"}}]},"ConfirmedLine":{"properties":{"variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Id","description":"Vendor variant.","examples":["1104541D033.095"]},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sku","description":"Vendor SKU.","examples":["1104541D033"]},"requested":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Requested","description":"Units ordered.","examples":[2]},"confirmed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Confirmed","description":"Units the vendor confirmed.","examples":[2]},"unit_cost":{"anyOf":[{"type":"string","pattern":"^\\d+\\.\\d{2}$"},{"type":"null"}],"title":"Unit Cost","description":"Confirmed unit cost, two decimals.","examples":["70.00"]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"ISO 4217 code.","examples":["USD"]}},"additionalProperties":false,"type":"object","required":["variant_id","sku","requested","confirmed","unit_cost","currency"],"title":"ConfirmedLine","description":"A line as the vendor confirmed it (order feed).","examples":[{"confirmed":2,"currency":"USD","requested":2,"sku":"1104541D033","unit_cost":"70.00","variant_id":"1104541D033.095"}]},"ConnectionState":{"type":"string","enum":["connected","pending","invalid","error","disabled","not_connected"],"title":"ConnectionState","description":"Health of this account's login to the brand's portal."},"ConsumerShipTo":{"properties":{"addressee":{"type":"string","maxLength":100,"minLength":1,"title":"Addressee","description":"Recipient name.","examples":["Jane Doe"]},"street":{"type":"string","maxLength":200,"minLength":1,"title":"Street","description":"Street line 1.","examples":["12 Main St"]},"street2":{"type":"string","maxLength":200,"title":"Street2","description":"Street line 2.","default":"","examples":["Apt 4"]},"city":{"type":"string","maxLength":100,"minLength":1,"title":"City","description":"City.","examples":["Columbia"]},"state":{"type":"string","maxLength":50,"minLength":2,"title":"State","description":"State or province code.","examples":["SC"]},"postal":{"type":"string","maxLength":20,"minLength":3,"title":"Postal","description":"Postal code.","examples":["29201"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","title":"Country","description":"ISO 3166 alpha-2 country; some brands ship to the US only.","default":"US","examples":["US"]},"phone":{"type":"string","maxLength":40,"title":"Phone","description":"Consumer phone; send it only when the brand's drop_ship_requires_phone is true.","default":"","examples":[""]},"email":{"type":"string","maxLength":320,"title":"Email","description":"The STORE's contact email, never the consumer's; send it only when drop_ship_requires_email is true.","default":"","examples":[""]}},"additionalProperties":false,"type":"object","required":["addressee","street","city","state","postal"],"title":"ConsumerShipTo","description":"The consumer's delivery address for a drop-ship. Personal data: never logged.","examples":[{"addressee":"Jane Doe","city":"Columbia","country":"US","email":"","phone":"","postal":"29201","state":"SC","street":"12 Main St","street2":""}]},"DeliveryWindow":{"properties":{"requested_ship":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Requested Ship","description":"The window's date the order asked for (ship_dates.requested_ship); null when the order gave none.","examples":["2027-01-15"]},"set_at_stage":{"type":"boolean","title":"Set At Stage","description":"True only when the lines were put in that window in the portal basket at staging (brand capability future_window_at_stage). False = the brand sets the window in its portal: check it before placing.","examples":[false]},"note":{"type":"string","title":"Note","description":"The plain sentence to show the buyer.","examples":["Brooks sets the delivery window in its portal. Check it before placing."]},"window_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Window Id","description":"The portal's window id, when its catalog names one.","examples":[null]},"windows":{"items":{"type":"string"},"type":"array","title":"Windows","description":"The portal's names of the window(s) the lines went into (empty unless set_at_stage).","examples":[["Jan 1 2027 - Jun 30 2027"]]}},"additionalProperties":false,"type":"object","required":["requested_ship","set_at_stage","note"],"title":"DeliveryWindow","description":"A future order's delivery window as staging left it (2026-10-17).","examples":[{"note":"Brooks sets the delivery window in its portal. Check it before placing.","requested_ship":"2027-01-15","set_at_stage":false,"windows":[]}]},"FutureWindow":{"properties":{"date":{"type":"string","format":"date","title":"Date","description":"Ship date.","examples":["2026-11-15"]},"qty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Qty","description":"Units in the window; null when hidden.","examples":[48]},"display":{"type":"string","title":"Display","description":"What to show a human.","examples":["48"]},"ordering_mode":{"$ref":"#/components/schemas/OrderingMode","description":"Ordering mode of the window.","examples":["future"]}},"additionalProperties":false,"type":"object","required":["date","qty","display","ordering_mode"],"title":"FutureWindow","description":"A dated delivery window for one size.","examples":[{"date":"2026-11-15","display":"48","ordering_mode":"future","qty":48}]},"GridCell":{"properties":{"qty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Qty","description":"Units available; null when the vendor hides the count.","examples":[200]},"display":{"type":"string","title":"Display","description":"What to show a human: '47', '200+' (capped), or '—'.","examples":["200+"]},"order_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Order Limit","description":"Most units one order may take, when the vendor says.","examples":[null]}},"additionalProperties":false,"type":"object","required":["qty","display"],"title":"GridCell","description":"Quantity available for one size in one delivery window.","examples":[{"display":"200+","qty":200}]},"GridColumn":{"properties":{"key":{"type":"string","title":"Key","description":"Column key used in rows[].cells and lookup size_key.","examples":["7.0/B"]},"size":{"type":"string","title":"Size","description":"The size as the vendor prints it.","examples":["7"]},"width":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Width","description":"Width letter(s) when the brand has a width axis.","examples":["B"]}},"additionalProperties":false,"type":"object","required":["key","size","width"],"title":"GridColumn","description":"One size (and width) column of a grid.","examples":[{"key":"7.0/B","size":"7","width":"B"}]},"GridRow":{"properties":{"date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Date","description":"Ship date (YYYY-MM-DD) of a future window; null = available now.","examples":[null,"2026-11-15"]},"ordering_mode":{"$ref":"#/components/schemas/OrderingMode","description":"at_once for stock now (or dated warehouse stock), future for a pre-book window.","examples":["at_once"]},"cells":{"additionalProperties":{"$ref":"#/components/schemas/GridCell"},"type":"object","title":"Cells","description":"Quantity per column key.","examples":[{"7.0/B":{"display":"200+","qty":200}}]}},"additionalProperties":false,"type":"object","required":["date","ordering_mode","cells"],"title":"GridRow","description":"One delivery window: now (date null) or a future date.","examples":[{"cells":{"7.0/B":{"display":"200+","qty":200}},"ordering_mode":"at_once"}]},"GridStatus":{"type":"string","enum":["ok","partial","unsupported","size_missing","error"],"title":"GridStatus","description":"Outcome of an availability read (the RunOps contract ``STATUS_*``)."},"Immediate":{"properties":{"qty":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Qty","description":"Units available now; null when hidden.","examples":[12]},"display":{"type":"string","title":"Display","description":"What to show a human.","examples":["12"]}},"additionalProperties":false,"type":"object","required":["qty","display"],"title":"Immediate","description":"Stock available now for one size.","examples":[{"display":"12","qty":12}]},"LookupItem":{"properties":{"variant_id":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Variant Id","description":"Vendor variant id from an earlier lookup or availability call; exact and cheapest.","examples":["1204431B189.070"]},"upc":{"anyOf":[{"type":"string","pattern":"^\\d{8,14}$"},{"type":"null"}],"title":"Upc","description":"Barcode: UPC-A, EAN-13 or GTIN-14 digits.","examples":["195394123456"]},"sku":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Sku","description":"The retailer's SKU; decoded per brand or matched by search. Add size/width/color when the SKU names only the style.","examples":["1204431B189"]},"style_code":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Style Code","description":"A vendor style code as printed on the box, when no SKU is at hand.","examples":["120443"]},"style_id":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Style Id","description":"Vendor style id from the catalog; needs color_id and size.","examples":["120443"]},"color_id":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Color Id","description":"Vendor colourway id from the catalog.","examples":["120443189"]},"color":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Color","description":"Colour name or code that narrows a SKU match.","examples":["Black/Ebony/Pink"]},"size":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Size","description":"Size as the retailer writes it.","examples":["8"]},"width":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Width","description":"Width letter(s) for brands with a width axis.","examples":["B"]},"client_ref":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Client Ref","description":"Your own id for the line, echoed back unchanged.","examples":["pos-line-17"]}},"additionalProperties":false,"type":"object","title":"LookupItem","description":"One product to resolve.","examples":[{"client_ref":"pos-line-17","size":"8","sku":"1204431B189","width":"B"}]},"LookupRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/LookupItem"},"type":"array","maxItems":200,"minItems":1,"title":"Items","description":"The products, each in any accepted form.","examples":[[{"client_ref":"pos-line-17","size":"8","sku":"1204431B189","width":"B"},{"upc":"195394123456"},{"color_id":"120443189","size":"9.5","style_id":"120443"}]]}},"additionalProperties":false,"type":"object","required":["items"],"title":"LookupRequest","description":"Up to 200 products to resolve and price in one call.","examples":[{"items":[{"client_ref":"pos-line-17","size":"8","sku":"1204431B189","width":"B"},{"upc":"195394123456"},{"color_id":"120443189","size":"9.5","style_id":"120443"}]}]},"LookupResponse":{"properties":{"brand":{"type":"string","title":"Brand","description":"Brand code.","examples":["brooks"]},"items":{"items":{"$ref":"#/components/schemas/LookupResult"},"type":"array","title":"Items","description":"One result per input item, same order.","examples":[[{"color_id":"120443189","confidence":"0.90","future":[{"date":"2026-11-15","display":"48","ordering_mode":"future","qty":48}],"immediate":{"display":"12","qty":12},"input":{"client_ref":"pos-line-17","size":"8","sku":"1204431B189","width":"B"},"match_method":"sku_decode","price":{"currency":"USD","retail":"140.00","wholesale":"70.00"},"resolved":true,"size_key":"8.0/B","style_id":"120443","variant_id":"1204431B189.080"}]]},"unmatched_hint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Unmatched Hint","description":"How this brand's identifiers look; show it next to unresolved items.","examples":["Brooks SKUs look like 1204431B189."]},"meta":{"$ref":"#/components/schemas/PageMeta","description":"count, as_of and the account read."}},"additionalProperties":false,"type":"object","required":["brand","items","unmatched_hint","meta"],"title":"LookupResponse","description":"Every item, in request order, resolved or not.","examples":[{"brand":"brooks","items":[{"color_id":"120443189","confidence":"0.90","future":[{"date":"2026-11-15","display":"48","ordering_mode":"future","qty":48}],"immediate":{"display":"12","qty":12},"input":{"client_ref":"pos-line-17","size":"8","sku":"1204431B189","width":"B"},"match_method":"sku_decode","price":{"currency":"USD","retail":"140.00","wholesale":"70.00"},"resolved":true,"size_key":"8.0/B","style_id":"120443","variant_id":"1204431B189.080"},{"future":[],"input":{"upc":"195394123456"},"reason":"unresolved","resolved":false}],"meta":{"as_of":"2026-10-16T15:04:05Z","brand":"brooks","count":2},"unmatched_hint":"Brooks SKUs look like 1204431B189 (style 120443, width 1B, colour 189)."}]},"LookupResult":{"properties":{"input":{"$ref":"#/components/schemas/LookupItem","description":"The item as you sent it."},"resolved":{"type":"boolean","title":"Resolved","description":"True when the item matched one vendor variant.","examples":[true]},"variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Id","description":"Vendor variant id; order by this.","examples":["1204431B189.080"]},"style_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Style Id","description":"Vendor style id.","examples":["120443"]},"color_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Color Id","description":"Vendor colourway id.","examples":["120443189"]},"size_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Size Key","description":"The grid column key of the size.","examples":["8.0/B"]},"match_method":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Match Method","description":"barcode_api, sku_decode, search or manual.","examples":["sku_decode"]},"confidence":{"anyOf":[{"type":"string","pattern":"^(0\\.\\d{2}|1\\.00)$"},{"type":"null"}],"title":"Confidence","description":"Match confidence 0.00–1.00 as a string (barcode 0.99, SKU decode 0.90, search 0.60).","examples":["0.90"]},"immediate":{"anyOf":[{"$ref":"#/components/schemas/Immediate"},{"type":"null"}],"description":"Stock available now."},"future":{"items":{"$ref":"#/components/schemas/FutureWindow"},"type":"array","title":"Future","description":"Dated windows.","examples":[[{"date":"2026-11-15","display":"48","ordering_mode":"future","qty":48}]]},"order_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Order Limit","description":"Most units one order may take, when the vendor says.","examples":[null]},"price":{"anyOf":[{"$ref":"#/components/schemas/Price"},{"type":"null"}],"description":"This size's price for this dealer."},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why the item did not resolve (null when resolved).","examples":[null,"unresolved"]},"product_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Product Name","description":"The style's name as the brand shows it (added 2026-10-17).","examples":["Ghost 17"]},"color_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Color Name","description":"The colourway's name (added 2026-10-17).","examples":["Black/Ebony/Pink"]},"size":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Size","description":"The size as the grid labels it (added 2026-10-17).","examples":["8"]},"width":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Width","description":"The width, for brands with a width axis (added 2026-10-17).","examples":["B"]}},"additionalProperties":false,"type":"object","required":["input","resolved","variant_id","style_id","color_id","size_key","match_method","confidence","immediate","future","order_limit","price","reason"],"title":"LookupResult","description":"How one item resolved, with its availability and price.","examples":[{"color_id":"120443189","confidence":"0.90","future":[{"date":"2026-11-15","display":"48","ordering_mode":"future","qty":48}],"immediate":{"display":"12","qty":12},"input":{"client_ref":"pos-line-17","size":"8","sku":"1204431B189","width":"B"},"match_method":"sku_decode","price":{"currency":"USD","retail":"140.00","wholesale":"70.00"},"resolved":true,"size_key":"8.0/B","style_id":"120443","variant_id":"1204431B189.080"}]},"Order":{"properties":{"order_id":{"type":"string","title":"Order Id","description":"Order id.","examples":["ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W"]},"brand":{"type":"string","title":"Brand","description":"Brand code.","examples":["on"]},"kind":{"$ref":"#/components/schemas/OrderKind","description":"fill_in or drop_ship.","examples":["drop_ship"]},"status":{"$ref":"#/components/schemas/OrderStatus","description":"pending = being staged; staged_in_portal = in the draft, not submitted; partial = staged with some lines skipped; failed = nothing reached the vendor (see error); draft_left_behind = a draft may hold this order, acknowledge before re-sending; submitted / confirmed / partially_shipped / shipped / invoiced / cancelled = the vendor's progress from the order feed. Submit protocol: verified = the staged basket was read back and matches; awaiting_confirmation = a person must confirm in the app (24 h); submitting = sent once, awaiting the answer; staged_mismatch = the basket differs from the request, nothing submitted; submit_rejected = the brand refused, nothing placed; submit_unknown = the answer was unclear, the order MAY exist — never resend, it is read back automatically; submit_failed = not found after every read-back, the basket is still in the portal.","examples":["staged_in_portal"]},"submitted":{"type":"boolean","title":"Submitted","description":"true only when the brand placed the order: a vendor order number was returned or a read-back of the portal found it. false for a staged order (a human reviews and places it in Bridge to Brands).","examples":[false]},"message":{"type":"string","title":"Message","description":"One sentence to show the user.","examples":["Staged as an unsubmitted draft in the On portal. Review and place it in Bridge to Brands."]},"source":{"$ref":"#/components/schemas/OrderSource","description":"brdg2b = staged through this API; portal = read from the vendor's order book.","examples":["brdg2b"]},"portal":{"anyOf":[{"$ref":"#/components/schemas/PortalLink"},{"type":"null"}],"description":"Where to finish the order. Always show url and instructions."},"baskets":{"items":{"$ref":"#/components/schemas/Basket"},"type":"array","title":"Baskets","description":"One entry per vendor container.","examples":[[{"basket_id":"RO-884213","po":"DS-1016-JANE","portal_url":"https://backstage.on-running.com/reorder/drafts/RO-884213","ship_to":"Fleet Feet Columbia (613907)","total_pieces":1}]]},"po":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Po","description":"Your PO.","examples":["DS-1016-JANE"]},"ship_to_ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ship To Ref","description":"Store ref.","examples":["613907"]},"surface":{"anyOf":[{"$ref":"#/components/schemas/Surface"},{"type":"null"}],"description":"Where the order came in: rest, mcp or web.","examples":["rest"]},"api_key_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key Name","description":"Name of the key that staged it.","examples":["Storefront integration"]},"lines":{"$ref":"#/components/schemas/OrderLines","description":"Lines by outcome."},"vendor":{"anyOf":[{"$ref":"#/components/schemas/VendorOrder"},{"type":"null"}],"description":"The vendor's record, once the order feed has seen it."},"shipments":{"items":{"$ref":"#/components/schemas/Shipment"},"type":"array","title":"Shipments","description":"Tracked shipments.","examples":[[{"brand":"brooks","carrier":"UPS","lines":[{"quantity":2,"variant_id":"1104541D033.095"}],"order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","shipment_id":"shp_01JA3B4C5D6E7F8G9H0J1K2M3N","shipped_at":"2026-10-18T00:00:00Z","tracking_number":"1Z999AA10123456784","tracking_url":"https://www.ups.com/track?tracknum=1Z999AA10123456784","units":2}]]},"error":{"anyOf":[{"$ref":"#/components/schemas/OrderError"},{"type":"null"}],"description":"Why the order failed, when it did."},"draft_left_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Left Note","description":"For draft_left_behind: what went wrong, in the vendor's terms.","examples":[null,"the ship-to address did not save on the draft"]},"draft_acknowledged_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Draft Acknowledged At","description":"When the account acknowledged the left-behind draft.","examples":[null]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Created (UTC).","examples":["2026-10-16T15:04:05Z"]},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"Last changed (UTC).","examples":["2026-10-16T15:04:05Z"]},"submission":{"anyOf":[{"$ref":"#/components/schemas/Submission"},{"type":"null"}],"description":"How the order was (not) submitted and why; null for portal-sourced orders.","examples":[{"mode_effective":"stage","reason":"submitting to Brooks is not verified yet; the order is staged for you to submit in the portal"}]},"confirm_expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Confirm Expires At","description":"For awaiting_confirmation: when the 24 h confirmation window ends (the order then stays staged).","examples":[null]},"events":{"items":{"$ref":"#/components/schemas/OrderEvent"},"type":"array","title":"Events","description":"The submission timeline, oldest first.","examples":[[]]},"caps_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caps Note","description":"Why the account's amount caps were not applied to this order (the brand shows no prices); absent when they were. Units and lines caps always apply.","examples":[null]},"delivery_window":{"anyOf":[{"$ref":"#/components/schemas/DeliveryWindow"},{"type":"null"}],"description":"A future order's delivery window at staging: whether the portal basket was put in the requested window, and the sentence to show. Absent for an at-once order.","examples":[{"note":"Brooks sets the delivery window in its portal. Check it before placing.","requested_ship":"2027-01-15","set_at_stage":false,"windows":[]}]},"account":{"anyOf":[{"$ref":"#/components/schemas/AccountRef"},{"type":"null"}],"description":"The brand login (account) the order was placed on (or the order feed read it on). Absent for test-mode orders.","examples":[{"id":"acct_01JB2C5V1C8ZK3V6Q4X9N7M2PA","name":"Retail stores"}]}},"additionalProperties":false,"type":"object","required":["order_id","brand","kind","status","submitted","message","source","portal","baskets","po","ship_to_ref","surface","api_key_name","lines","vendor","shipments","error","draft_left_note","draft_acknowledged_at","created_at","updated_at"],"title":"Order","description":"An order: staged by Bridge to Brands, or read from the portal's order book.","examples":[{"api_key_name":"Storefront integration","baskets":[{"basket_id":"RO-884213","po":"DS-1016-JANE","portal_url":"https://backstage.on-running.com/reorder/drafts/RO-884213","ship_to":"Fleet Feet Columbia (613907)","total_pieces":1}],"brand":"on","created_at":"2026-10-16T15:04:05Z","kind":"drop_ship","lines":{"confirmed":[],"skipped":[{"quantity":1,"reason":"no inventory at this ship-to","upc":"195394123456"}],"staged":[{"currency":"USD","quantity":1,"unit_price":"80.00","variant_id":"3MD10340123-7.5"}]},"message":"Staged as an unsubmitted draft in the On portal. Review and place it in Bridge to Brands.","order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","po":"DS-1016-JANE","portal":{"draft_id":"RO-884213","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft RO-884213 as the On portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing.","login_url":"https://backstage.on-running.com/login","order_reference":"DS-1016-JANE","url":"https://backstage.on-running.com/reorder/drafts/RO-884213"},"ship_to_ref":"613907","shipments":[],"source":"brdg2b","status":"staged_in_portal","submitted":false,"surface":"rest","updated_at":"2026-10-16T15:04:05Z"},{"api_key_name":"Storefront integration","baskets":[{"basket_id":"B-552901","po":"FILL-1016-COLA","portal_url":"https://fasttrack.brooksrunning.com/cart?basket=B-552901","ship_to":"Fleet Feet Columbia (1002)","total_pieces":4}],"brand":"brooks","created_at":"2026-10-16T15:04:05Z","kind":"fill_in","lines":{"confirmed":[],"skipped":[{"quantity":1,"reason":"unresolved","upc":"195394123456"}],"staged":[{"currency":"USD","quantity":2,"unit_price":"70.00","variant_id":"1204431B189.070"},{"currency":"USD","quantity":1,"sku":"1204431B189","unit_price":"70.00","variant_id":"1204431B189.080"},{"currency":"USD","quantity":1,"unit_price":"70.00","variant_id":"1204431B189.095"}]},"message":"Staged 4 of 5 pairs as an unsubmitted basket in the Brooks portal; 1 line was skipped. Review and place it in Bridge to Brands.","order_id":"ord_01JA2ZB3C4D5E6F7G8H9J0K1M2","po":"FILL-1016-COLA","portal":{"draft_id":"B-552901","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft B-552901 as the Brooks portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing.","login_url":"https://fasttrack.brooksrunning.com/login","order_reference":"FILL-1016-COLA","url":"https://fasttrack.brooksrunning.com/cart?basket=B-552901"},"ship_to_ref":"1002","shipments":[],"source":"brdg2b","status":"partial","submitted":false,"surface":"rest","updated_at":"2026-10-16T15:04:05Z"}]},"OrderCreate":{"properties":{"brand":{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,39}$","title":"Brand","description":"Brand code from GET /v1/brands.","examples":["brooks"]},"kind":{"$ref":"#/components/schemas/OrderKind","description":"fill_in = to one of your stores; drop_ship = to a consumer.","examples":["fill_in"]},"ship_to_ref":{"type":"string","maxLength":64,"minLength":1,"title":"Ship To Ref","description":"Your store's ref from GET /v1/brands/{brand}/ship-tos: the destination for a fill-in, the billing store for a drop-ship.","examples":["1002"]},"po":{"type":"string","maxLength":64,"minLength":1,"title":"Po","description":"Your PO number, sent to the portal exactly as typed; at most the brand's po_max_length.","examples":["FILL-1016-COLA"]},"lines":{"items":{"$ref":"#/components/schemas/OrderLineIn"},"type":"array","maxItems":500,"minItems":1,"title":"Lines","description":"The lines; each names the product in any accepted form.","examples":[[{"quantity":2,"variant_id":"1204431B189.070"},{"ordering_mode":"at_once","quantity":1,"upc":"195394123456"},{"quantity":1,"size":"8","sku":"1204431B189","width":"B"},{"color_id":"120443189","quantity":1,"size":"9.5","style_id":"120443"}]]},"consumer":{"anyOf":[{"$ref":"#/components/schemas/ConsumerShipTo"},{"type":"null"}],"description":"Required for drop_ship, forbidden for fill_in."},"confirm":{"type":"boolean","title":"Confirm","description":"Set true to confirm a large order (above the account's confirmation threshold) or a drop-ship when the server asks, and — for mode=submit — only after the user approved submitting this exact order.","default":false,"examples":[false]},"mode":{"anyOf":[{"type":"string","enum":["stage","submit"]},{"type":"null"}],"title":"Mode","description":"stage = leave an unsubmitted draft for a human; submit = place the order with the brand where every gate allows it (key scope orders:submit, the account's per-brand mode, a submit-verified brand, confirm=true). Omitted = the account's per-brand setting. The response's submission.mode_effective says what happened and why.","examples":["stage"]},"terms_ack":{"type":"boolean","title":"Terms Ack","description":"true when the user accepted the brand's order terms; required to submit where capabilities say submit_requires_terms_ack.","default":false,"examples":[false]},"ship_dates":{"anyOf":[{"$ref":"#/components/schemas/ShipDates"},{"type":"null"}],"description":"Requested ship / cancel-after dates; required to submit where capabilities say submit_requires_ship_dates."},"account":{"anyOf":[{"type":"string","maxLength":60,"minLength":1},{"type":"null"}],"title":"Account","description":"Which of the brand's logins to order on: the account id or its exact name (GET /v1/accounts). Omitted = the brand's default account. ship_to_ref must be one of that account's ship-tos.","examples":["Amazon FBA"]}},"additionalProperties":false,"type":"object","required":["brand","kind","ship_to_ref","po","lines"],"title":"OrderCreate","description":"Place one order in one brand's portal: submitted within the account's\ncaps and confirmation settings where the brand is verified, staged with a\nlink otherwise.","examples":[{"brand":"brooks","kind":"fill_in","lines":[{"quantity":2,"variant_id":"1204431B189.070"},{"ordering_mode":"at_once","quantity":1,"upc":"195394123456"},{"quantity":1,"size":"8","sku":"1204431B189","width":"B"},{"color_id":"120443189","quantity":1,"size":"9.5","style_id":"120443"}],"po":"FILL-1016-COLA","ship_to_ref":"1002"},{"brand":"on","consumer":{"addressee":"Jane Doe","city":"Columbia","country":"US","email":"","phone":"","postal":"29201","state":"SC","street":"12 Main St","street2":""},"kind":"drop_ship","lines":[{"quantity":1,"variant_id":"3MD10340123-7.5"}],"po":"DS-1016-JANE","ship_to_ref":"613907"}]},"OrderError":{"properties":{"code":{"type":"string","title":"Code","description":"The problem code (the last path segment of the problem type URI, e.g. portal_down, portal_rejected, credentials_invalid).","examples":["portal_down"]},"message":{"type":"string","title":"Message","description":"One sentence for a person; never portal PII.","examples":["The brand's portal is not answering right now."]}},"additionalProperties":false,"type":"object","required":["code","message"],"title":"OrderError","description":"Why the order failed or its outcome is unknown: the same ``{code,\nmessage}`` shape on ``/v1``, MCP and the web app (since 2026-10-16).","examples":[{"code":"portal_down","message":"The brand's portal is not answering right now."}]},"OrderEvent":{"properties":{"at":{"type":"string","format":"date-time","title":"At","description":"When (UTC).","examples":["2026-10-16T15:04:05Z"]},"step":{"type":"string","title":"Step","description":"stage, gate, verify, confirm, lease, submit, outcome, read_back, resolve, cancel or expire.","examples":["verify"]},"outcome":{"type":"string","title":"Outcome","description":"What the step concluded (ok, mismatch, sent, submitted, rejected, unknown, found, not_found, …).","examples":["ok"]},"note":{"type":"string","title":"Note","description":"One plain sentence; never a name, address or PO.","examples":["3 lines, 4 units match the container"]}},"additionalProperties":false,"type":"object","required":["at","step","outcome","note"],"title":"OrderEvent","description":"One step of the submission timeline (audited, no personal data).","examples":[{"at":"2026-10-16T15:04:05Z","note":"the request asked to stage only","outcome":"stage","step":"gate"}]},"OrderKind":{"type":"string","enum":["fill_in","drop_ship","unknown"],"title":"OrderKind"},"OrderLineIn":{"properties":{"variant_id":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Variant Id","description":"Vendor variant id from an earlier lookup or availability call; exact and cheapest.","examples":["1204431B189.070"]},"upc":{"anyOf":[{"type":"string","pattern":"^\\d{8,14}$"},{"type":"null"}],"title":"Upc","description":"Barcode: UPC-A, EAN-13 or GTIN-14 digits.","examples":["195394123456"]},"sku":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Sku","description":"The retailer's SKU; decoded per brand or matched by search. Add size/width/color when the SKU names only the style.","examples":["1204431B189"]},"style_code":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Style Code","description":"A vendor style code as printed on the box, when no SKU is at hand.","examples":["120443"]},"style_id":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Style Id","description":"Vendor style id from the catalog; needs color_id and size.","examples":["120443"]},"color_id":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Color Id","description":"Vendor colourway id from the catalog.","examples":["120443189"]},"color":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Color","description":"Colour name or code that narrows a SKU match.","examples":["Black/Ebony/Pink"]},"size":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Size","description":"Size as the retailer writes it.","examples":["8"]},"width":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Width","description":"Width letter(s) for brands with a width axis.","examples":["B"]},"client_ref":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Client Ref","description":"Your own id for the line, echoed back unchanged.","examples":["pos-line-17"]},"quantity":{"type":"integer","maximum":999,"minimum":1,"title":"Quantity","description":"Units (pairs) to stage.","examples":[2]},"ordering_mode":{"$ref":"#/components/schemas/OrderingMode","description":"at_once (default) or future; must be in the brand's capabilities.ordering_modes.","default":"at_once","examples":["at_once"]}},"additionalProperties":false,"type":"object","required":["quantity"],"title":"OrderLineIn","description":"One order line: a product in any accepted form plus a quantity.","examples":[{"quantity":2,"variant_id":"1204431B189.070"}]},"OrderLines":{"properties":{"staged":{"items":{"$ref":"#/components/schemas/StagedLine"},"type":"array","title":"Staged","description":"Lines in the draft.","examples":[[{"currency":"USD","quantity":1,"unit_price":"80.00","variant_id":"3MD10340123-7.5"}]]},"skipped":{"items":{"$ref":"#/components/schemas/SkippedLine"},"type":"array","title":"Skipped","description":"Lines not staged, with reasons.","examples":[[{"quantity":1,"reason":"no inventory at this ship-to","upc":"195394123456"}]]},"confirmed":{"items":{"$ref":"#/components/schemas/ConfirmedLine"},"type":"array","title":"Confirmed","description":"Lines as the vendor confirmed them (after submission).","examples":[[{"confirmed":2,"currency":"USD","requested":2,"sku":"1104541D033","unit_cost":"70.00","variant_id":"1104541D033.095"}]]}},"additionalProperties":false,"type":"object","required":["staged","skipped","confirmed"],"title":"OrderLines","description":"The order's lines by outcome.","examples":[{"confirmed":[],"skipped":[{"quantity":1,"reason":"no inventory at this ship-to","upc":"195394123456"}],"staged":[{"currency":"USD","quantity":1,"unit_price":"80.00","variant_id":"3MD10340123-7.5"}]}]},"OrderPage":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Order"},"type":"array","title":"Data","description":"Orders.","examples":[[{"api_key_name":"Storefront integration","baskets":[{"basket_id":"RO-884213","po":"DS-1016-JANE","portal_url":"https://backstage.on-running.com/reorder/drafts/RO-884213","ship_to":"Fleet Feet Columbia (613907)","total_pieces":1}],"brand":"on","created_at":"2026-10-16T15:04:05Z","kind":"drop_ship","lines":{"confirmed":[],"skipped":[{"quantity":1,"reason":"no inventory at this ship-to","upc":"195394123456"}],"staged":[{"currency":"USD","quantity":1,"unit_price":"80.00","variant_id":"3MD10340123-7.5"}]},"message":"Staged as an unsubmitted draft in the On portal. Review and place it in Bridge to Brands.","order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","po":"DS-1016-JANE","portal":{"draft_id":"RO-884213","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft RO-884213 as the On portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing.","login_url":"https://backstage.on-running.com/login","order_reference":"DS-1016-JANE","url":"https://backstage.on-running.com/reorder/drafts/RO-884213"},"ship_to_ref":"613907","shipments":[],"source":"brdg2b","status":"staged_in_portal","submitted":false,"surface":"rest","updated_at":"2026-10-16T15:04:05Z"}]]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as ?cursor= for the next page; null on the last page.","examples":["b3JkOjI1"]},"meta":{"$ref":"#/components/schemas/PageMeta","description":"Page facts."}},"additionalProperties":false,"type":"object","required":["data","next_cursor","meta"],"title":"OrderPage","description":"One page of orders, newest first.","examples":[{"data":[{"api_key_name":"Storefront integration","baskets":[{"basket_id":"RO-884213","po":"DS-1016-JANE","portal_url":"https://backstage.on-running.com/reorder/drafts/RO-884213","ship_to":"Fleet Feet Columbia (613907)","total_pieces":1}],"brand":"on","created_at":"2026-10-16T15:04:05Z","kind":"drop_ship","lines":{"confirmed":[],"skipped":[{"quantity":1,"reason":"no inventory at this ship-to","upc":"195394123456"}],"staged":[{"currency":"USD","quantity":1,"unit_price":"80.00","variant_id":"3MD10340123-7.5"}]},"message":"Staged as an unsubmitted draft in the On portal. Review and place it in Bridge to Brands.","order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","po":"DS-1016-JANE","portal":{"draft_id":"RO-884213","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft RO-884213 as the On portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing.","login_url":"https://backstage.on-running.com/login","order_reference":"DS-1016-JANE","url":"https://backstage.on-running.com/reorder/drafts/RO-884213"},"ship_to_ref":"613907","shipments":[],"source":"brdg2b","status":"staged_in_portal","submitted":false,"surface":"rest","updated_at":"2026-10-16T15:04:05Z"}],"meta":{"count":1,"limit":25},"next_cursor":"b3JkOjI1"}]},"OrderSource":{"type":"string","enum":["brdg2b","portal"],"title":"OrderSource","description":"Origin: staged through Bridge to Brands, or read from the portal's book."},"OrderStatus":{"type":"string","enum":["pending","staged_in_portal","partial","failed","draft_left_behind","submitted","confirmed","partially_shipped","shipped","invoiced","cancelled","verified","awaiting_confirmation","submitting","staged_mismatch","submit_rejected","submit_unknown","submit_failed"],"title":"OrderStatus"},"OrderSubmit":{"properties":{"confirm":{"type":"boolean","title":"Confirm","description":"Must be true, sent only after the user approved submitting this exact order (the refusal names the units, lines and brand).","default":false,"examples":[true]},"terms_ack":{"type":"boolean","title":"Terms Ack","description":"true when the user accepted the brand's order terms (capabilities.submit_requires_terms_ack).","default":false,"examples":[false]},"ship_dates":{"anyOf":[{"$ref":"#/components/schemas/ShipDates"},{"type":"null"}],"description":"Requested ship / cancel-after dates (capabilities.submit_requires_ship_dates)."}},"additionalProperties":false,"type":"object","title":"OrderSubmit","description":"``POST /v1/orders/{order_id}/submit`` body.","examples":[{"confirm":true}]},"OrderingMode":{"type":"string","enum":["at_once","future"],"title":"OrderingMode","description":"When goods ship: ``at_once`` (stock now) or ``future`` (a dated window)."},"PageMeta":{"properties":{"count":{"type":"integer","minimum":0,"title":"Count","description":"Number of items in data on this page.","examples":[1]},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"The page size that was applied (max 100).","examples":[25]},"as_of":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"As Of","description":"When the portal was asked (RFC 3339 UTC); null for results that come from Bridge to Brands' own records.","examples":["2026-10-16T15:04:05Z"]},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand","description":"The brand the page belongs to, when there is one.","examples":["brooks"]},"account":{"anyOf":[{"$ref":"#/components/schemas/AccountRef"},{"type":"null"}],"description":"The brand login (account) the page was read on, for results that come from a portal."}},"additionalProperties":false,"type":"object","required":["count"],"title":"PageMeta","description":"Facts about one page of results.","examples":[{"as_of":"2026-10-16T15:04:05Z","count":1,"limit":25}]},"PortalLink":{"properties":{"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"The deepest link available: the draft or basket itself, else the portal's orders page. A reference: the buyer reviews and places the order in Bridge to Brands and never needs to sign in to the portal.","examples":["https://backstage.on-running.com/reorder/drafts/RO-884213"]},"draft_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft Id","description":"The vendor's draft/basket id.","examples":["RO-884213"]},"order_reference":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Reference","description":"The reference the portal shows (usually the PO).","examples":["DS-1016-JANE"]},"login_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Login Url","description":"The portal's sign-in page (a reference only; Bridge to Brands signs in for the buyer).","examples":["https://backstage.on-running.com/login"]},"instructions":{"type":"string","title":"Instructions","description":"One sentence telling a human how to finish it in Bridge to Brands.","examples":["To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft RO-884213 as the On portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing."]}},"additionalProperties":false,"type":"object","required":["url","draft_id","order_reference","login_url","instructions"],"title":"PortalLink","description":"Where the staged draft sits in the portal; the human reviews and places\nit in Bridge (the app's order page and its signed-in portal window).","examples":[{"draft_id":"RO-884213","instructions":"To finish, open this order in Bridge to Brands (app.brdg2b.ai/orders) — no portal sign-in needed: review draft RO-884213 as the On portal holds it, then place it from Bridge, or in the signed-in portal window where the brand is not yet verified for placing.","login_url":"https://backstage.on-running.com/login","order_reference":"DS-1016-JANE","url":"https://backstage.on-running.com/reorder/drafts/RO-884213"}]},"Price":{"properties":{"wholesale":{"anyOf":[{"type":"string","pattern":"^\\d+\\.\\d{2}$"},{"type":"null"}],"title":"Wholesale","description":"The dealer's own cost per unit, two decimals; null when the portal does not show it.","examples":["70.00"]},"retail":{"anyOf":[{"type":"string","pattern":"^\\d+\\.\\d{2}$"},{"type":"null"}],"title":"Retail","description":"Manufacturer's suggested retail price per unit, two decimals; null when unknown.","examples":["140.00"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","title":"Currency","description":"ISO 4217 currency code.","examples":["USD"]}},"additionalProperties":false,"type":"object","required":["wholesale","retail","currency"],"title":"Price","description":"What the vendor charges this dealer, and the MSRP. Strings, never floats.","examples":[{"currency":"USD","retail":"140.00","wholesale":"70.00"}]},"Problem":{"additionalProperties":false,"description":"RFC 9457 problem details (``application/problem+json``).","examples":[{"brand":"brooks","detail":"The brand's portal is not answering right now.","instance":"/v1/brands/brooks/products","request_id":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W","retry_after":60,"status":503,"title":"Portal unavailable","type":"https://brdg2b.ai/problems/portal_down"}],"properties":{"type":{"description":"Stable URI naming the problem type; branch on this, not on title or detail.","examples":["https://brdg2b.ai/problems/portal_down"],"title":"Type","type":"string"},"title":{"description":"Short human summary of the type.","examples":["Portal unavailable"],"title":"Title","type":"string"},"status":{"description":"The HTTP status code.","examples":[503],"title":"Status","type":"integer"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Human explanation of this occurrence; never contains portal excerpts or personal data.","examples":["The brand's portal is not answering right now."],"title":"Detail"},"instance":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The request path that failed.","examples":["/v1/brands/brooks/products"],"title":"Instance"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"Echo of X-Request-Id; quote it to support.","examples":["req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"],"title":"Request Id"},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"The brand whose portal caused the problem (portal-side problems only).","examples":["brooks"],"title":"Brand"},"retry_after":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Seconds to wait before retrying; same as the Retry-After header.","examples":[60],"title":"Retry After"},"draft_id":{"anyOf":[{"type":"string"},{"type":"null"}],"default":null,"description":"For draft_left_behind: the vendor's id of the draft that may already hold this order.","examples":["RO-884213"],"title":"Draft Id"},"errors":{"anyOf":[{"items":{"$ref":"#/components/schemas/ProblemFieldError"},"type":"array"},{"type":"null"}],"default":null,"description":"For validation_error: every invalid field.","examples":[[{"field":"po","message":"Field required"}]],"title":"Errors"}},"required":["type","title","status"],"title":"Problem","type":"object"},"ProblemFieldError":{"properties":{"field":{"type":"string","title":"Field","description":"Dotted path of the invalid field.","examples":["lines.0.quantity"]},"message":{"type":"string","title":"Message","description":"What is wrong with it (never echoes the value).","examples":["Input should be greater than or equal to 1"]}},"additionalProperties":false,"type":"object","required":["field","message"],"title":"ProblemFieldError","description":"One invalid field in a ``validation_error``.","examples":[{"field":"lines.0.quantity","message":"Input should be greater than or equal to 1"}]},"Product":{"properties":{"brand":{"type":"string","title":"Brand","description":"Brand code.","examples":["brooks"]},"style_id":{"type":"string","title":"Style Id","description":"Vendor style id; use it in product and availability paths.","examples":["120443"]},"name":{"type":"string","title":"Name","description":"Style name.","examples":["Ghost 17"]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender","description":"The vendor's own gender word, unnormalised.","examples":["women"]},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"The vendor's own category word, unnormalised.","examples":["road"]},"colorways":{"items":{"$ref":"#/components/schemas/Colorway"},"type":"array","title":"Colorways","description":"Colourways found.","examples":[[{"color_id":"120443189","image_url":"https://images.brooksrunning.com/120443189.jpg","name":"Black/Ebony/Pink","price":{"currency":"USD","retail":"140.00","wholesale":"70.00"}}]]},"as_of":{"type":"string","format":"date-time","title":"As Of","description":"When the portal was asked (RFC 3339 UTC).","examples":["2026-10-16T15:04:05Z"]},"ordering_modes":{"items":{"type":"string","enum":["at_once","future"]},"type":"array","title":"Ordering Modes","description":"The order books the style appears in: `at_once` (stock now) and/or `future` (pre-book / season). Filter a search with `mode`. Empty when unknown.","examples":[["at_once","future"]]}},"additionalProperties":false,"type":"object","required":["brand","style_id","name","gender","category","colorways","as_of"],"title":"Product","description":"A style and its colourways, as the portal lists it.","examples":[{"as_of":"2026-10-16T15:04:05Z","brand":"brooks","category":"road","colorways":[{"color_id":"120443189","image_url":"https://images.brooksrunning.com/120443189.jpg","name":"Black/Ebony/Pink","price":{"currency":"USD","retail":"140.00","wholesale":"70.00"}}],"gender":"women","name":"Ghost 17","style_id":"120443"}]},"ProductDetail":{"properties":{"brand":{"type":"string","title":"Brand","description":"Brand code.","examples":["brooks"]},"style_id":{"type":"string","title":"Style Id","description":"Vendor style id; use it in product and availability paths.","examples":["120443"]},"name":{"type":"string","title":"Name","description":"Style name.","examples":["Ghost 17"]},"gender":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Gender","description":"The vendor's own gender word, unnormalised.","examples":["women"]},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Category","description":"The vendor's own category word, unnormalised.","examples":["road"]},"colorways":{"items":{"$ref":"#/components/schemas/Colorway"},"type":"array","title":"Colorways","description":"Colourways found.","examples":[[{"color_id":"120443189","image_url":"https://images.brooksrunning.com/120443189.jpg","name":"Black/Ebony/Pink","price":{"currency":"USD","retail":"140.00","wholesale":"70.00"}}]]},"as_of":{"type":"string","format":"date-time","title":"As Of","description":"When the portal was asked (RFC 3339 UTC).","examples":["2026-10-16T15:04:05Z"]},"ordering_modes":{"items":{"type":"string","enum":["at_once","future"]},"type":"array","title":"Ordering Modes","description":"The order books the style appears in: `at_once` (stock now) and/or `future` (pre-book / season). Filter a search with `mode`. Empty when unknown.","examples":[["at_once","future"]]},"account":{"anyOf":[{"$ref":"#/components/schemas/AccountRef"},{"type":"null"}],"description":"The brand login (account) it was read on."},"size_columns":{"items":{"$ref":"#/components/schemas/GridColumn"},"type":"array","title":"Size Columns","description":"Every size column the style is made in.","examples":[[{"key":"7.0/B","size":"7","width":"B"}]]},"images":{"items":{"type":"string"},"type":"array","title":"Images","description":"Vendor image URLs.","examples":[["https://images.brooksrunning.com/120443189.jpg"]]}},"additionalProperties":false,"type":"object","required":["brand","style_id","name","gender","category","colorways","as_of","size_columns","images"],"title":"ProductDetail","description":"A style with its full size run and images.","examples":[{"as_of":"2026-10-16T15:04:05Z","brand":"brooks","category":"road","colorways":[{"color_id":"120443189","image_url":"https://images.brooksrunning.com/120443189.jpg","name":"Black/Ebony/Pink","price":{"currency":"USD","retail":"140.00","wholesale":"70.00"}}],"gender":"women","images":["https://images.brooksrunning.com/120443189.jpg"],"name":"Ghost 17","size_columns":[{"key":"7.0/B","size":"7","width":"B"},{"key":"7.5/B","size":"7.5","width":"B"}],"style_id":"120443"}]},"ProductPage":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Product"},"type":"array","title":"Data","description":"Matching styles.","examples":[[{"as_of":"2026-10-16T15:04:05Z","brand":"brooks","category":"road","colorways":[{"color_id":"120443189","image_url":"https://images.brooksrunning.com/120443189.jpg","name":"Black/Ebony/Pink","price":{"currency":"USD","retail":"140.00","wholesale":"70.00"}}],"gender":"women","name":"Ghost 17","style_id":"120443"}]]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as ?cursor= for the next page; null on the last page.","examples":["c2VhcmNoOjI1"]},"meta":{"$ref":"#/components/schemas/ProductPageMeta","description":"Page facts, including as_of and whether the portal's answer was truncated."}},"additionalProperties":false,"type":"object","required":["data","next_cursor","meta"],"title":"ProductPage","description":"One page of catalog search results.","examples":[{"data":[{"as_of":"2026-10-16T15:04:05Z","brand":"brooks","category":"road","colorways":[{"color_id":"120443189","image_url":"https://images.brooksrunning.com/120443189.jpg","name":"Black/Ebony/Pink","price":{"currency":"USD","retail":"140.00","wholesale":"70.00"}}],"gender":"women","name":"Ghost 17","style_id":"120443"}],"meta":{"as_of":"2026-10-16T15:04:05Z","brand":"brooks","count":1,"limit":25},"next_cursor":"c2VhcmNoOjI1"}]},"ProductPageMeta":{"properties":{"count":{"type":"integer","minimum":0,"title":"Count","description":"Number of items in data on this page.","examples":[1]},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"The page size that was applied (max 100).","examples":[25]},"as_of":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"As Of","description":"When the portal was asked (RFC 3339 UTC); null for results that come from Bridge to Brands' own records.","examples":["2026-10-16T15:04:05Z"]},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand","description":"The brand the page belongs to, when there is one.","examples":["brooks"]},"account":{"anyOf":[{"$ref":"#/components/schemas/AccountRef"},{"type":"null"}],"description":"The brand login (account) the page was read on, for results that come from a portal."},"truncated":{"type":"boolean","title":"Truncated","description":"True when the brand's portal returned only part of the matches and offers no next page (next_cursor is null): narrow the query to see the rest. Diadora caps a search at 8 articles.","default":false,"examples":[true]},"note":{"type":"string","title":"Note","description":"Why this page is partial or empty, in words a buyer can act on; \"\" when there is nothing to say.","default":"","examples":["narrow the search (an article code such as 181846 matches exactly)"]}},"additionalProperties":false,"type":"object","required":["count"],"title":"ProductPageMeta","description":"Page facts for catalog search, plus whether the portal's answer was partial.","examples":[{"as_of":"2026-10-16T15:04:05Z","brand":"diadora","count":8,"limit":25,"note":"Diadora's search answered with only part of the matches and offers no next page; narrow the search (an article code such as 181846 matches exactly)","truncated":true}]},"ShipDates":{"properties":{"requested_ship":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Requested Ship","description":"When the brand should ship (ISO date, today or later).","examples":["2026-11-02"]},"cancel_after":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Cancel After","description":"Cancel if not shipped by this date (on or after requested_ship).","examples":["2026-11-30"]}},"additionalProperties":false,"type":"object","title":"ShipDates","description":"Requested ship and cancel-after dates, for brands that need them at submit.","examples":[{"cancel_after":"2026-11-30","requested_ship":"2026-11-02"}]},"ShipTo":{"properties":{"ref":{"type":"string","title":"Ref","description":"The vendor's store number; send it as ship_to_ref.","examples":["1002"]},"account_ref":{"type":"string","title":"Account Ref","description":"The vendor's account handle for the store (informational).","examples":["0001234567"]},"name":{"type":"string","title":"Name","description":"Store name at the vendor.","examples":["Fleet Feet Columbia"]},"city":{"type":"string","title":"City","description":"City.","examples":["Columbia"]},"state":{"type":"string","title":"State","description":"State or province.","examples":["SC"]},"postal":{"type":"string","title":"Postal","description":"Postal code.","examples":["29201"]},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label","description":"The account's own name for the store, when set in the app.","examples":["Columbia"]}},"additionalProperties":false,"type":"object","required":["ref","account_ref","name","city","state","postal","label"],"title":"ShipTo","description":"One of the account's stores as the vendor knows it.","examples":[{"account_ref":"0001234567","city":"Columbia","label":"Columbia","name":"Fleet Feet Columbia","postal":"29201","ref":"1002","state":"SC"}]},"ShipToList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/ShipTo"},"type":"array","title":"Data","description":"Ship-tos.","examples":[[{"account_ref":"0001234567","city":"Columbia","label":"Columbia","name":"Fleet Feet Columbia","postal":"29201","ref":"1002","state":"SC"}]]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Always null: one page.","examples":[null]},"meta":{"$ref":"#/components/schemas/PageMeta","description":"Page facts."}},"additionalProperties":false,"type":"object","required":["data","next_cursor","meta"],"title":"ShipToList","description":"The brand's ship-tos for this account.","examples":[{"data":[{"account_ref":"0001234567","city":"Columbia","label":"Columbia","name":"Fleet Feet Columbia","postal":"29201","ref":"1002","state":"SC"}],"meta":{"brand":"brooks","count":1}}]},"Shipment":{"properties":{"shipment_id":{"type":"string","title":"Shipment Id","description":"Shipment id.","examples":["shp_01JA3B4C5D6E7F8G9H0J1K2M3N"]},"order_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Id","description":"The order it belongs to.","examples":["ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W"]},"brand":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Brand","description":"Brand code.","examples":["brooks"]},"carrier":{"type":"string","title":"Carrier","description":"Carrier name.","examples":["UPS"]},"tracking_number":{"type":"string","title":"Tracking Number","description":"Tracking number.","examples":["1Z999AA10123456784"]},"tracking_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracking Url","description":"Carrier tracking link; show it to the user.","examples":["https://www.ups.com/track?tracknum=1Z999AA10123456784"]},"shipped_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Shipped At","description":"When it shipped.","examples":["2026-10-18T00:00:00Z"]},"delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Delivered At","description":"When it was delivered, if known.","examples":[null]},"units":{"type":"integer","title":"Units","description":"Units in the shipment.","examples":[2]},"lines":{"items":{"$ref":"#/components/schemas/ShipmentLine"},"type":"array","title":"Lines","description":"Variants and quantities.","examples":[[{"quantity":2,"variant_id":"1104541D033.095"}]]},"account":{"anyOf":[{"$ref":"#/components/schemas/AccountRef"},{"type":"null"}],"description":"The brand login (account) the order is on."}},"additionalProperties":false,"type":"object","required":["shipment_id","order_id","brand","carrier","tracking_number","tracking_url","shipped_at","delivered_at","units","lines"],"title":"Shipment","description":"One tracked shipment.","examples":[{"brand":"brooks","carrier":"UPS","lines":[{"quantity":2,"variant_id":"1104541D033.095"}],"order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","shipment_id":"shp_01JA3B4C5D6E7F8G9H0J1K2M3N","shipped_at":"2026-10-18T00:00:00Z","tracking_number":"1Z999AA10123456784","tracking_url":"https://www.ups.com/track?tracknum=1Z999AA10123456784","units":2}]},"ShipmentLine":{"properties":{"variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Id","description":"Vendor variant.","examples":["1104541D033.095"]},"quantity":{"type":"integer","title":"Quantity","description":"Units shipped.","examples":[2]}},"additionalProperties":false,"type":"object","required":["variant_id","quantity"],"title":"ShipmentLine","description":"Units of one variant in a shipment.","examples":[{"quantity":2,"variant_id":"1104541D033.095"}]},"ShipmentPage":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Shipment"},"type":"array","title":"Data","description":"Shipments.","examples":[[{"brand":"brooks","carrier":"UPS","lines":[{"quantity":2,"variant_id":"1104541D033.095"}],"order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","shipment_id":"shp_01JA3B4C5D6E7F8G9H0J1K2M3N","shipped_at":"2026-10-18T00:00:00Z","tracking_number":"1Z999AA10123456784","tracking_url":"https://www.ups.com/track?tracknum=1Z999AA10123456784","units":2}]]},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as ?cursor= for the next page; null on the last page.","examples":[null]},"meta":{"$ref":"#/components/schemas/PageMeta","description":"Page facts."}},"additionalProperties":false,"type":"object","required":["data","next_cursor","meta"],"title":"ShipmentPage","description":"One page of shipments, newest first.","examples":[{"data":[{"brand":"brooks","carrier":"UPS","lines":[{"quantity":2,"variant_id":"1104541D033.095"}],"order_id":"ord_01JA2Z9K7Q8M3N4P5R6S7T8V9W","shipment_id":"shp_01JA3B4C5D6E7F8G9H0J1K2M3N","shipped_at":"2026-10-18T00:00:00Z","tracking_number":"1Z999AA10123456784","tracking_url":"https://www.ups.com/track?tracknum=1Z999AA10123456784","units":2}],"meta":{"count":1,"limit":25}}]},"SkippedLine":{"properties":{"variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Id","description":"Vendor variant, if resolved.","examples":[null]},"upc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upc","description":"Barcode you sent, if any.","examples":["195394123456"]},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sku","description":"SKU you sent, if any.","examples":[null]},"quantity":{"type":"integer","title":"Quantity","description":"Units requested.","examples":[1]},"reason":{"type":"string","title":"Reason","description":"Why it was skipped: 'unresolved' or the portal's reason.","examples":["no inventory at this ship-to"]}},"additionalProperties":false,"type":"object","required":["variant_id","upc","sku","quantity","reason"],"title":"SkippedLine","description":"A line that was not staged, and why.","examples":[{"quantity":1,"reason":"no inventory at this ship-to","upc":"195394123456"}]},"StagedLine":{"properties":{"variant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Variant Id","description":"Vendor variant staged.","examples":["3MD10340123-7.5"]},"upc":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upc","description":"Barcode you sent, if any.","examples":[null]},"sku":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Sku","description":"SKU you sent, if any.","examples":[null]},"quantity":{"type":"integer","title":"Quantity","description":"Units staged.","examples":[1]},"unit_price":{"anyOf":[{"type":"string","pattern":"^\\d+\\.\\d{2}$"},{"type":"null"}],"title":"Unit Price","description":"Dealer unit price, two decimals.","examples":["80.00"]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"ISO 4217 code.","examples":["USD"]}},"additionalProperties":false,"type":"object","required":["variant_id","upc","sku","quantity","unit_price","currency"],"title":"StagedLine","description":"A line that reached the portal draft.","examples":[{"currency":"USD","quantity":1,"unit_price":"80.00","variant_id":"3MD10340123-7.5"}]},"Submission":{"properties":{"mode_effective":{"type":"string","enum":["stage","submit"],"title":"Mode Effective","description":"stage = a human submits in the portal; submit = Bridge to Brands places it through the submit protocol.","examples":["stage"]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why the order was staged rather than submitted, in one sentence; null when it submits.","examples":["this account stages Brooks orders (Settings → Ordering)"]},"submitted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Submitted At","description":"When the brand accepted it (or the read-back proved it).","examples":[null]},"read_back_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Read Back At","description":"When a read-back of the portal's order history settled it.","examples":[null]},"cancel_window":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cancel Window","description":"What the brand allows after submit: none, until_processing or <n>h; null = unknown (cancel through the brand).","examples":[null]}},"additionalProperties":false,"type":"object","required":["mode_effective","reason","submitted_at","read_back_at","cancel_window"],"title":"Submission","description":"How the order was (or was not) submitted (docs/ORDER_SUBMIT.md).","examples":[{"mode_effective":"stage","reason":"submitting to Brooks is not verified yet; the order is staged for you to submit in the portal"}]},"Support":{"type":"string","enum":["supported","coming_soon"],"title":"Support","description":"Whether Bridge to Brands reaches the brand today."},"Surface":{"type":"string","enum":["rest","mcp","web","worker"],"title":"Surface","description":"Where the call came in."},"UsageCounts":{"properties":{"requests":{"type":"integer","title":"Requests","description":"Metered requests.","examples":[120]},"results":{"type":"integer","title":"Results","description":"Products or grids returned.","examples":[2400]},"orders":{"type":"integer","title":"Orders","description":"Orders staged.","examples":[3]},"lines":{"type":"integer","title":"Lines","description":"Order lines staged.","examples":[14]},"units":{"type":"integer","title":"Units","description":"Units staged.","examples":[22]},"by_status":{"additionalProperties":{"type":"integer"},"type":"object","title":"By Status","description":"Requests by outcome: ok, partial, client_error, portal_down, portal_rejected, rate_limited.","examples":[{"ok":117,"portal_down":3}]}},"additionalProperties":false,"type":"object","required":["requests","results","orders","lines","units","by_status"],"title":"UsageCounts","description":"Counts for one group (or the total).","examples":[{"by_status":{"ok":117,"portal_down":3},"lines":14,"orders":3,"requests":120,"results":2400,"units":22}]},"UsageGroup":{"properties":{"key":{"type":"string","title":"Key","description":"The day (YYYY-MM-DD), brand code or operation name.","examples":["2026-10-16"]},"counts":{"$ref":"#/components/schemas/UsageCounts","description":"Counts for the group."}},"additionalProperties":false,"type":"object","required":["key","counts"],"title":"UsageGroup","description":"Counts for one day, brand or operation.","examples":[{"counts":{"by_status":{"ok":117,"portal_down":3},"lines":14,"orders":3,"requests":120,"results":2400,"units":22},"key":"2026-10-16"}]},"UsageGroupBy":{"type":"string","enum":["day","brand","operation"],"title":"UsageGroupBy","description":"How ``GET /v1/usage`` groups counts."},"UsageReport":{"properties":{"api_key_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key Id","description":"The key the counts belong to (the caller).","examples":["key_01JA2Z9K7Q8M3N4P5R6S7T8V9W"]},"from":{"type":"string","format":"date-time","title":"From","description":"Window start (inclusive).","examples":["2026-10-01T00:00:00Z"]},"to":{"type":"string","format":"date-time","title":"To","description":"Window end (exclusive).","examples":["2026-10-16T15:04:05Z"]},"group_by":{"$ref":"#/components/schemas/UsageGroupBy","description":"Grouping applied.","examples":["day"]},"totals":{"$ref":"#/components/schemas/UsageCounts","description":"Totals over the window."},"groups":{"items":{"$ref":"#/components/schemas/UsageGroup"},"type":"array","title":"Groups","description":"One entry per group.","examples":[[{"counts":{"by_status":{"ok":117,"portal_down":3},"lines":14,"orders":3,"requests":120,"results":2400,"units":22},"key":"2026-10-16"}]]}},"additionalProperties":false,"type":"object","required":["api_key_id","from","to","group_by","totals","groups"],"title":"UsageReport","description":"The calling key's own usage.","examples":[{"api_key_id":"key_01JA2Z9K7Q8M3N4P5R6S7T8V9W","from":"2026-10-01T00:00:00Z","group_by":"day","groups":[{"counts":{"by_status":{"ok":117,"portal_down":3},"lines":14,"orders":3,"requests":120,"results":2400,"units":22},"key":"2026-10-16"}],"to":"2026-10-16T15:04:05Z","totals":{"by_status":{"ok":117,"portal_down":3},"lines":14,"orders":3,"requests":120,"results":2400,"units":22}}]},"VendorOrder":{"properties":{"order_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Order Number","description":"Vendor order number.","examples":["4512030"]},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Normalised vendor status.","examples":["shipped"]},"status_raw":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status Raw","description":"Status as the portal words it.","examples":["Invoiced"]},"confirmed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Confirmed At","description":"When the vendor confirmed it.","examples":["2026-10-17T14:02:00Z"]},"invoice_numbers":{"items":{"type":"string"},"type":"array","title":"Invoice Numbers","description":"Vendor invoices.","examples":[["9123001"]]},"portal_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Portal Url","description":"The order in the portal's order book.","examples":["https://fasttrack.brooksrunning.com/order-book/4512030"]},"as_of":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"As Of","description":"When the feed last read it.","examples":["2026-10-18T06:00:00Z"]},"order_numbers":{"items":{"type":"string"},"type":"array","title":"Order Numbers","description":"Every vendor order number of this order: a portal may split one submit into several vendor orders under the same PO.","examples":[["4512030"]]}},"additionalProperties":false,"type":"object","required":["order_number","status","status_raw","confirmed_at","invoice_numbers","portal_url","as_of"],"title":"VendorOrder","description":"The vendor's own record of the order, from the order feed.","examples":[{"as_of":"2026-10-18T06:00:00Z","confirmed_at":"2026-10-17T14:02:00Z","invoice_numbers":["9123001"],"order_number":"4512030","portal_url":"https://fasttrack.brooksrunning.com/order-book/4512030","status":"shipped","status_raw":"Invoiced"}]}},"securitySchemes":{"ApiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"b2b_<live|test>_<prefix8>_<secret32>","description":"An API key from app.brdg2b.ai/keys, sent as `Authorization: Bearer b2b_live_…`. `b2b_test_` keys reach the fake portals."}},"headers":{"XRequestId":{"description":"Echo of the request id; quote it to support.","schema":{"type":"string"},"example":"req_01JA2Z9K7Q8M3N4P5R6S7T8V9W"},"RetryAfter":{"description":"Seconds to wait before retrying.","schema":{"type":"integer"},"example":60},"WWWAuthenticate":{"description":"Always `Bearer`.","schema":{"type":"string"},"example":"Bearer realm=\"brdg2b\""}}},"tags":[{"name":"Brands","description":"Which brands exist, what each can do, and whether this account is connected. Start here."},{"name":"Catalog","description":"Search, product detail, availability grids and bulk lookup by SKU/UPC, with this dealer's prices."},{"name":"Ship-tos","description":"The account's stores as each brand knows them; `ref` is the `ship_to_ref` of every order."},{"name":"Orders","description":"Place fill-in and drop-ship orders in a brand's portal (submitted within your caps and confirmation settings where the brand is verified, otherwise staged for review and placing in Bridge to Brands) and follow them through the vendor's order book."},{"name":"Shipments","description":"Tracking numbers and carrier links from the order feed."},{"name":"Usage","description":"The calling key's own metered usage."},{"name":"Meta","description":"This document and the agent guide."}],"externalDocs":{"description":"Agent guide (AGENTS.md)","url":"https://brdg2b.ai/docs/for-agents"}}