{"openapi":"3.1.0","info":{"title":"CommerceBook API","version":"1.0.0","summary":"Work your leads, CRM, capacity, messages and costs, or run your seller catalog and orders, with your own agent.","description":"Keyed access for a member, with one of two kinds of key: an agent link key (the agent link https://commercebook.ai/agent/<token>, 90 days) reaches what its member’s kind reaches, plus GET /instructions, and a named key (made at Agent access) reaches the warehouse operations for a warehouse, or /seller/* and GET /me for a seller. Every key starts read-only: an agent link key carries the activities its owner turned on at Agent access, a named key carries the permissions chosen when it was made, and a call outside them answers 403 not_permitted with the activity and a hint. Send the key as Authorization: Bearer; every call runs as your member through the same rules as the app, is recorded on your ledger with the key id, and counts toward 600 calls per key per hour, and in the API a product listing is a lot (lot_id, lot_code, the /lots paths).","contact":{"name":"CommerceBook","url":"https://commercebook.ai"}},"servers":[{"url":"https://commercebook.ai/api/v1"}],"security":[{"bearerKey":[]}],"tags":[{"name":"Account"},{"name":"Leads"},{"name":"CRM"},{"name":"Capacity"},{"name":"Messages"},{"name":"Costs"},{"name":"Network"},{"name":"Settings"},{"name":"Seller"},{"name":"Profile"},{"name":"Facilities"},{"name":"Shipping","description":"Shipping profiles set by the seller: regions, rates, transit days; the quote for a destination."},{"name":"Payments"},{"name":"Market"},{"name":"Feedback"}],"paths":{"/me":{"get":{"operationId":"getMe","tags":["Account"],"summary":"Your member, verification and counts","security":[{"bearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/standing":{"get":{"operationId":"getMyStanding","tags":["Account"],"summary":"Your accuracy standing: strikes and whether you may post","security":[{"bearerKey":[]}],"description":"Strikes in 90 and 365 days, fabricated-contact strikes, posting_suspended_until, status and the rule’s numbers. A strike comes from a confirmed fabricated contact or from an operator finding that a declared fact was false; volumes smaller than posted carry no strike. Three in 90 days suspend posting for 30 days; five in a year, or two fabricated contacts, remove the member from the Lead Exchange pending review (see /policies). Any key.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Standing"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/instructions":{"get":{"operationId":"getInstructions","tags":["Account"],"summary":"The briefing of a role: buyer, seller or warehouse","security":[{},{"bearerKey":[]}],"description":"Markdown. Role names the briefing (buyer, seller or warehouse) with a key or without one, and the first line of every answer names the other two briefings with their addresses. Without a key and without role: the buyer briefing (how the market is read, priced with shipping and bought, the rules, what is coming and how to send feedback). With an agent link key and without role: the briefing of its member’s kind rendered from live state; a login that holds both kinds gets both joined under one line, and kind names one; a role the login does not hold answers the public copy of that briefing. ?format=json returns the state the keyed document is rendered from.","parameters":[{"name":"role","in":"query","schema":{"type":"string","description":"buyer, seller or warehouse: the briefing to return.","enum":["buyer","seller","warehouse"]}},{"name":"kind","in":"query","schema":{"type":"string","description":"warehouse, seller or buyer.","enum":["warehouse","seller","buyer"]}},{"name":"format","in":"query","schema":{"type":"string","description":"json for the state instead of the document (a key only).","enum":["json"]}}],"responses":{"200":{"description":"The document","content":{"text/markdown":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"The live state (format=json)."}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/open":{"get":{"operationId":"listOpenLeads","tags":["Leads"],"summary":"Open leads on the exchange","security":[{"bearerKey":[]}],"description":"Other members’ open leads by default. include_own=true adds your own open leads in the same list, as the app’s Open Leads shows them; each item carries own.","parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}},{"name":"service","in":"query","schema":{"type":"string"}},{"name":"market","in":"query","schema":{"type":"string","description":"City, ST. Anywhere leads (location_any) match every market."}},{"name":"include_own","in":"query","schema":{"type":"boolean","default":false,"description":"true adds your own open leads (own: true on each)."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"next_cursor":{"oneOf":[{"type":"string","description":"Pass back as ?cursor= for the next page."},{"type":"null"}]}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/mine":{"get":{"operationId":"listMyLeads","tags":["Leads"],"summary":"Your posted leads, drafts included","security":[{"bearerKey":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}},{"name":"service","in":"query","schema":{"type":"string"}},{"name":"market","in":"query","schema":{"type":"string","description":"City, ST. Anywhere leads (location_any) match every market."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"next_cursor":{"oneOf":[{"type":"string","description":"Pass back as ?cursor= for the next page."},{"type":"null"}]}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads":{"post":{"operationId":"postLead","tags":["Leads"],"summary":"Post a lead from a CRM deal or from fields","security":[{"bearerKey":[]}],"description":"Writes the draft and lists it in the same call (draft: true keeps it a draft). The identity check runs on the server and refuses a need text that names the shipper (409 summary_names_shipper). outcome is posted, draft, blocked or duplicate. Leads must be true; confirmed false leads earn strikes that suspend posting (see /policies). While posting is suspended the call answers 403 posting_suspended with the end date as detail. With no price (no price_flat_cents, price_pct or terms) the lead takes your Lead defaults (GET /settings/lead-defaults): the price, and the buyer places unless exclusivity or max_buyers is sent. A deal whose CRM tags carry dnc, do-not-contact, do-not-solicit or do-not-call is refused (409 do_not_solicit). product, current_provider, inbound_mode, units_per_order and rate_expectation are kept in the lead attributes and count toward quality, the lead quality score in the answer (0 to 9).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"deal_id":{"type":"string","description":"Post from this CRM deal: its company, contact, need, service and market fill whatever the other fields leave out.","format":"uuid"},"company_name":{"type":"string","description":"The shipper. Kept private; the identity check refuses a need text that names it."},"contact_name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"need":{"type":"string","description":"What the prospect needs, in your own words (2,000 characters). This is what buyers read."},"title":{"type":"string","description":"The title buyers see first (80 characters). Without one the lead takes the generated title: services, location, volume band.","maxLength":80},"summary_short":{"type":"string","description":"The one-line summary under the title (140 characters), such as Short-term plywood, one container. Without one the lead takes the first sentence of the need.","maxLength":140},"lead_source":{"type":"string","enum":["own","referral"],"default":"own","description":"own: the lead came to you directly; referral: a lead company referred it."},"referral_source":{"type":"string","description":"The lead company that referred it (60 characters), for example Fulfill.com. Only on a referral; the card reads Referred lead when blank.","maxLength":60},"service":{"type":"string","description":"The primary service, for example Fulfillment or Storage."},"market":{"type":"string","description":"City, ST of the need. Still accepted; markets takes several."},"markets":{"type":"array","items":{"type":"string","description":"City, ST"},"maxItems":10,"description":"Several locations in order, at most 10; the first is the primary. market is folded in when it is not listed."},"location_any":{"type":"boolean","description":"Anywhere: the prospect has no preferred place. markets are cleared.","default":false},"replace_draft":{"type":"string","description":"One of your drafts this post replaces, as Save Draft does in the app.","format":"uuid"},"terms":{"type":"string","enum":["flat","pct","both"],"default":"flat"},"price_flat_cents":{"type":"integer","description":"The flat price; 0 posts a free lead.","minimum":0},"price_pct":{"type":"number","minimum":0,"maximum":100},"exclusivity":{"type":"string","enum":["exclusive","open"],"default":"exclusive"},"max_buyers":{"type":"integer","minimum":1,"maximum":50,"default":1},"origin_market":{"type":"string"},"radius_mi":{"type":"integer","minimum":0,"maximum":1000},"volume_band":{"type":"string"},"window_start":{"type":"string","format":"date"},"window_end":{"type":"string","format":"date"},"last_contact_at":{"type":"string","format":"date"},"pallets_on_hand":{"type":"integer"},"pallets_inbound_month":{"type":"integer"},"orders_month":{"type":"integer"},"skus":{"type":"integer"},"containers_month":{"type":"integer"},"sqft":{"type":"integer"},"units_month":{"type":"integer"},"success_fee_pct":{"type":"number","minimum":0,"maximum":50},"draft":{"type":"boolean","description":"true saves the draft without listing it.","default":false},"product":{"type":"string","description":"The product, such as boxed candles (200 characters).","maxLength":200},"current_provider":{"type":"string","description":"The prospect’s current warehouse or 3PL (200 characters); a buyer sees it after purchase.","maxLength":200},"inbound_mode":{"type":"array","items":{"type":"string","enum":["parcel","pallet","container"]},"maxItems":3,"description":"How the goods arrive."},"units_per_order":{"type":"integer","description":"Units per order; with orders_month it is the order profile.","minimum":0},"rate_expectation":{"type":"string","description":"The budget or rate expectation in the prospect’s words (200 characters).","maxLength":200}}}}}},"responses":{"201":{"description":"Posted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostOutcome"}}}},"202":{"description":"pending_owner_confirmation: over the key’s spending cap or confirm amount, or an action the owner confirms. Not executed; it waits for the owner (GET /keys/{id}/pending).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingOwnerConfirmation"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}/claim":{"post":{"operationId":"claimLead","tags":["Leads"],"summary":"Claim a lead","security":[{"bearerKey":[]}],"description":"A free lead, or a deployment without card payments, claims on the demo path (payment demo). A priced lead with payments configured is paid without a client secret: method balance pays from the member’s balance at once (no processing line), method card charges the owner’s saved card off-session (price plus 2.90 percent plus 30 cents). Without method: the balance when it covers the price, else the saved card. The answer is status paid with claim_id, amount_cents (the buyer total), processing_cents and method; the contact is revealed at once. 409 no_payment_method (hint: the owner saves a card at Settings, Payment methods, or funds the balance at Settings, Balance); 409 balance_insufficient with shortfall_cents; 409 payment_needs_owner when the card needs the bank’s check (a pending row with reason card_authentication waits at Agent access); 403 not_permitted with activity payments until the owner turns payments on. The spending cap and the confirm amount apply to the buyer total.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lead.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"operation_id":{"type":"string","description":"Idempotency key of the payment; the request id by default."},"method":{"type":"string","description":"balance or card; without it the balance when it covers the price, else the saved card.","enum":["balance","card"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ClaimOutcome"},{"$ref":"#/components/schemas/PaidClaim"}]}}}},"202":{"description":"pending_owner_confirmation: over the key’s spending cap or confirm amount, or an action the owner confirms. Not executed; it waits for the owner (GET /keys/{id}/pending).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingOwnerConfirmation"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/crm/deals":{"get":{"operationId":"listDeals","tags":["CRM"],"summary":"Your deals","security":[{"bearerKey":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}},{"name":"stage","in":"query","schema":{"type":"string","enum":["new","qualified","discovery","site_visit","quoted","negotiating","won","onboarding","live","lost","offered"],"description":"quoted is Quote sent. Won, onboarding and live count as won. offered is accepted and keeps the deal’s stage (a listing is the exchange link)."}},{"name":"archived","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Deal"}},"next_cursor":{"oneOf":[{"type":"string","description":"Pass back as ?cursor= for the next page."},{"type":"null"}]}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createDeal","tags":["CRM"],"summary":"Create a deal","security":[{"bearerKey":[]}],"description":"Also Add a lead on the Leads screen: contact_name, email and phone write the contact with the deal, and markets (City, ST, in order) or location_any keep the locations as a confirmed fact (the first place in target_market). The identity check does not run on the deal, which is your own record; it runs on the text you share. then_share true, or an object with the POST /leads fields (price_flat_cents, max_buyers, need, service, markets and the rest), posts the new deal to the exchange right after, as Save and share does; share in the answer is what POST /leads answered (an error or pending_owner_confirmation leaves the deal created).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The deal name.","maxLength":200},"stage":{"type":"string","enum":["new","qualified","discovery","site_visit","quoted","negotiating","won","onboarding","live","lost","offered"],"description":"quoted is Quote sent. Won, onboarding and live count as won. offered is accepted and keeps the deal’s stage (a listing is the exchange link)."},"service":{"oneOf":[{"type":"string"},{"type":"null"}]},"target_market":{"oneOf":[{"type":"string"},{"type":"null"}]},"value_cents":{"oneOf":[{"type":"integer","minimum":0},{"type":"null"}]},"monthly_revenue_cents":{"oneOf":[{"type":"integer","minimum":0},{"type":"null"}]},"description":{"oneOf":[{"type":"string"},{"type":"null"}]},"expected_closing_date":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"company_id":{"oneOf":[{"type":"string","description":"One of your companies.","format":"uuid"},{"type":"null"}]},"company_name":{"oneOf":[{"type":"string","description":"Finds your company of that name or creates it."},{"type":"null"}]},"attributes":{"type":"object","additionalProperties":true},"contact_name":{"type":"string","description":"The contact at the company.","maxLength":200},"email":{"type":"string","description":"The contact email.","maxLength":200},"phone":{"type":"string","description":"The contact phone.","maxLength":60},"markets":{"type":"array","items":{"type":"string","description":"City, ST."}},"location_any":{"type":"boolean","description":"true: Anywhere."},"then_share":{"oneOf":[{"type":"boolean"},{"type":"object","additionalProperties":true,"description":"The POST /leads fields, without deal_id and the contact."}]}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/crm/deals/{id}":{"patch":{"operationId":"updateDeal","tags":["CRM"],"summary":"Update a deal","security":[{"bearerKey":[]}],"description":"The named fields only. A stage change runs the same rules as the board (crm_set_deal_stage); entering Qualified, Site visit, Quote sent or Onboarding ticks that checklist item when it is blank. checklist sets or clears the dated items; follow_up_due sets the next follow-up.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The deal.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The deal name.","maxLength":200},"stage":{"type":"string","enum":["new","qualified","discovery","site_visit","quoted","negotiating","won","onboarding","live","lost","offered"],"description":"quoted is Quote sent. Won, onboarding and live count as won. offered is accepted and keeps the deal’s stage (a listing is the exchange link)."},"service":{"oneOf":[{"type":"string"},{"type":"null"}]},"target_market":{"oneOf":[{"type":"string"},{"type":"null"}]},"value_cents":{"oneOf":[{"type":"integer","minimum":0},{"type":"null"}]},"monthly_revenue_cents":{"oneOf":[{"type":"integer","minimum":0},{"type":"null"}]},"description":{"oneOf":[{"type":"string"},{"type":"null"}]},"expected_closing_date":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"company_id":{"oneOf":[{"type":"string","description":"One of your companies.","format":"uuid"},{"type":"null"}]},"company_name":{"oneOf":[{"type":"string","description":"Finds your company of that name or creates it."},{"type":"null"}]},"attributes":{"type":"object","additionalProperties":true},"archived":{"type":"boolean"},"checklist":{"type":"object","properties":{"qualified":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"meeting_held":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"site_visited":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"quote_sent":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"contract_sent":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"contract_signed":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"onboarding_started":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]}},"additionalProperties":false,"description":"Each item a date, or null when not done."},"follow_up_due":{"oneOf":[{"type":"string","description":"The next follow-up.","format":"date"},{"type":"null"}]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"getDeal","tags":["CRM"],"summary":"One deal with its notes","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The deal.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deal"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteDeal","tags":["CRM"],"summary":"Delete a deal, or hide a GoHighLevel deal","security":[{"bearerKey":[]}],"description":"A typed, CSV or agent deal: as the record screen, archive first (PATCH archived true), then delete; 409 deal_not_archived otherwise. The Leads screen does both in one Delete. A GoHighLevel deal is not deleted, because GoHighLevel keeps the opportunity and the next sync would bring it back: it is archived and hidden (deleted false, hidden true), archived or not before. The Leads table leaves it out (GET /leads/table?deleted=true lists it), the sync leaves it alone, and PATCH archived false restores it.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The deal.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"},"hidden":{"type":"boolean"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/capacity/requests":{"get":{"operationId":"listCapacityRequests","tags":["Capacity"],"summary":"Capacity requests you sent and the ones your node received","security":[{"bearerKey":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}},{"name":"direction","in":"query","schema":{"type":"string","enum":["sent","received"]}},{"name":"status","in":"query","schema":{"type":"string","enum":["requested","quoted","accepted","declined","withdrawn"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CapacityRequest"}},"next_cursor":{"oneOf":[{"type":"string","description":"Pass back as ?cursor= for the next page."},{"type":"null"}]}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"requestCapacity","tags":["Capacity"],"summary":"Ask another warehouse for pallet positions","security":[{"bearerKey":[]}],"description":"Quoted at once when the node has a rate card; otherwise the node member prepares the quote.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"node_id":{"type":"string","description":"The node, from GET /network/members.","format":"uuid"},"member_id":{"type":"string","description":"Or the member whose one node to ask.","format":"uuid"},"positions":{"type":"integer","minimum":1},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"requirements":{"type":"string"},"for":{"type":"string","description":"Shown to the node as the requester name; your member name by default."}},"required":["positions","start_date","end_date"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapacityRequest"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/capacity/requests/{id}/quote":{"post":{"operationId":"quoteCapacityRequest","tags":["Capacity"],"summary":"Quote a request your node received","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The request.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quote_cents":{"type":"integer","minimum":1},"note":{"type":"string"}},"required":["quote_cents"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapacityRequest"}}}},"202":{"description":"pending_owner_confirmation: over the key’s spending cap or confirm amount, or an action the owner confirms. Not executed; it waits for the owner (GET /keys/{id}/pending).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingOwnerConfirmation"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/threads":{"get":{"operationId":"listThreads","tags":["Messages"],"summary":"Your inbox","security":[{"bearerKey":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Thread"}},"next_cursor":{"oneOf":[{"type":"string"},{"type":"null"}]},"total":{"type":"integer"}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/threads/{id}":{"get":{"operationId":"getThread","tags":["Messages"],"summary":"One thread with its messages","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The thread.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ThreadDetail"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"sendMessage","tags":["Messages"],"summary":"Send a message in an open thread","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The thread.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","maxLength":4000},"attachment":{"$ref":"#/components/schemas/Attachment"}},"required":["body"]}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"type":"object","properties":{"message_id":{"type":"string","format":"uuid"},"thread_id":{"type":"string","format":"uuid"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/request":{"post":{"operationId":"requestMessage","tags":["Messages"],"summary":"Send the first message to a member","security":[{"bearerKey":[]}],"description":"Opens a thread in requested; the member accepts in the app. An open or requested thread with that member is returned instead of a second one.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"body":{"type":"string","maxLength":4000},"attachment":{"$ref":"#/components/schemas/Attachment"}},"required":["member_id","body"]}}}},"responses":{"201":{"description":"Requested","content":{"application/json":{"schema":{"type":"object","properties":{"thread_id":{"type":"string","format":"uuid"}}}}}},"202":{"description":"pending_owner_confirmation: over the key’s spending cap or confirm amount, or an action the owner confirms. Not executed; it waits for the owner (GET /keys/{id}/pending).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingOwnerConfirmation"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/costs/prices":{"get":{"operationId":"listPrices","tags":["Costs"],"summary":"Your Prices as the app computes them","security":[{"bearerKey":[]}],"description":"Your invoiced items, merged by category, unit and key spec, each against the lowest equivalent network quote in your region.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"region":{"oneOf":[{"type":"string"},{"type":"null"}]},"items":{"type":"array","items":{"$ref":"#/components/schemas/PriceRow"}},"line_count":{"type":"integer"},"invoice_count":{"type":"integer"}},"required":["items"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/network/members":{"get":{"operationId":"listMembers","tags":["Network"],"summary":"The member directory, public fields only","security":[{"bearerKey":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MemberPublic"}},"next_cursor":{"oneOf":[{"type":"string","description":"Pass back as ?cursor= for the next page."},{"type":"null"}]}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/me":{"get":{"operationId":"getSellerMe","tags":["Seller"],"summary":"Your seller, readiness and counts","security":[{"bearerKey":[]}],"description":"GET /me answers the same for the key of a seller.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerMe"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/catalog/lots":{"get":{"operationId":"listSellerLots","tags":["Seller"],"summary":"Your products (lots in the API)","security":[{"bearerKey":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}},{"name":"status","in":"query","schema":{"type":"string","enum":["draft","active","paused","sold_out","withdrawn"]}},{"name":"state","in":"query","schema":{"type":"string","enum":["live","held","draft","stale","sold_out"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SellerLot"}},"next_cursor":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/catalog/lots/{id}":{"get":{"operationId":"getSellerLot","tags":["Seller"],"summary":"The record an agent reads for one product, with its audit trail","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The product (lot_id).","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"The product record an agent reads (seller_lot_record, 056): the product data template v1.1 field names, plus audit, the product ledger newest first."}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateSellerLot","tags":["Seller"],"summary":"Edit a product, or publish a draft","security":[{"bearerKey":[]}],"description":"The seller product page’s edit, the same function (seller_lot_update): the named fields only. A new quantity confirms the count, and now becomes its count date (typed); it cannot go below what is reserved or sold; quantity 0 makes a live product sold out. photos replaces the photos (up to 11 https links, the first is the main photo). publish true publishes a draft by the import rule: the seller must be able to sell (business details, payouts and policies done) and the product needs stock and a price. One operation id per change (D6), one ledger row with the fields that changed.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The product (lot_id).","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":150},"description":{"type":"string","description":"Plain text; an empty string clears it.","maxLength":5000},"condition":{"type":"string","enum":["new","open_box","used","refurbished","defective"]},"quantity":{"type":"integer","description":"On hand.","minimum":0},"unit_price_cents":{"type":"integer","description":"The price of one unit, in cents.","minimum":1},"min_qty":{"type":"integer","minimum":1},"photos":{"type":"array","items":{"type":"string","format":"uri"},"maxItems":11},"publish":{"type":"boolean","description":"true: publish a Draft."},"return_window_days":{"type":"integer","description":"The product’s own return terms (093); 0 is no returns.","minimum":0,"maximum":365},"return_method":{"type":"string","enum":["by_mail","same_warehouse","no_returns"]},"restocking_fee_pct":{"type":"number","minimum":0,"maximum":100},"return_terms":{"type":"null","description":"null clears the product’s own terms, so it inherits the category or default terms."},"price_schedule":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"min_qty":{"type":"integer","minimum":1},"unit_price_cents":{"type":"integer","minimum":1}},"required":["min_qty","unit_price_cents"]},"minItems":2,"maxItems":10,"description":"The tiers, ascending by min_qty: {min_qty, unit_price_cents}; the first tier starts at min_qty 1 (or at the offer minimum) and its price is the unit price; each later tier has a larger min_qty and a lower price; 2 to 10 tiers."},{"type":"null"}],"description":"Price by quantity: the tiers (the first tier's price becomes the unit price); null goes back to one price. A bad schedule is refused with 400 invalid_input, detail price_schedule: <reason>."},"schedule_kind":{"type":"string","enum":["volume","graduated"],"description":"How the tiers apply (default volume). volume: every unit is priced at the price of the highest tier the quantity reaches. graduated: the units within each tier are priced at that tier’s price."},"ship_from":{"oneOf":[{"type":"string","minLength":1,"maxLength":60},{"type":"null"}],"description":"The ship-from address by label or id (GET /seller/ship-from); null follows the default. Refused with ship_from_unknown (detail: your labels) for a label you do not have, and with ship_from_stored_at_warehouse for a product stored at a warehouse."},"goods_kind":{"type":"string","description":"new, used, or surplus (new goods sold below list). A used or surplus product goes live only with a condition, at least two photos, weight, size and its own terms.","enum":["new","used","surplus"]},"pickup":{"type":"boolean","description":"true offers free local pickup; buyers in the same 3-digit ZIP area as the pickup address read \"Pickup free in <city>\"."},"package":{"oneOf":[{"type":"object","properties":{"weight_lb":{"type":"number","exclusiveMinimum":0},"length_in":{"type":"number","exclusiveMinimum":0},"width_in":{"type":"number","exclusiveMinimum":0},"height_in":{"type":"number","exclusiveMinimum":0}},"required":["weight_lb","length_in","width_in","height_in"]},{"type":"null"}]},"shipping":{"type":"object","properties":{"kind":{"type":"string","description":"calculated: quoted live to the buyer’s ZIP; flat: amount_cents per order; free.","enum":["calculated","flat","free"]},"amount_cents":{"type":"integer","description":"For flat only.","minimum":0,"maximum":100000}},"required":["kind"]},"operation_id":{"type":"string","description":"Idempotency key (8 to 96 characters)."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"lot_id":{"type":"string","format":"uuid"},"fields":{"type":"array","items":{"type":"string","enum":["title","description","condition","quantity","price","min_qty","pictures","return_terms","ship_from","goods_kind","pickup","package","shipping"]}},"goods_kind":{"type":"string","enum":["new","used","surplus"]},"pickup_enabled":{"type":"boolean"},"used_missing":{"type":"array","items":{"type":"string","enum":["condition","photos","weight","dimensions","terms"]},"description":"What a used or surplus product still needs before it can go live; empty when nothing is missing."},"published":{"type":"boolean"},"lot_status":{"type":"string"},"state":{"type":"string","enum":["live","held","draft","stale","sold_out"]},"offer_status":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["lot_id","fields","published","lot_status","state"]}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it (quantity_below_reserved: the quantity is below what is reserved or sold). used_lot_incomplete: a used or surplus product cannot go live yet; detail names the missing fields (condition, photos, weight, dimensions, terms).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks catalog write; activity names it and hint where the owner turns it on.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: not a product of this seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"lot_state: withdrawn (the product cannot change), not_draft, not_live (selling is not on yet), not_publishable (no stock or no price) or no_price.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/catalog/upsert":{"post":{"operationId":"upsertSellerCatalog","tags":["Seller"],"summary":"Load or update your catalog from template records","security":[{"bearerKey":[]}],"description":"Up to 500 records of the product data template v1.1, the same diff import as the seller portal. Each item_id makes one product listing: a product, its lot, one manifest line and one offer. dry_run true returns the diff (created, changed with the fields, skipped with reasons) and writes nothing. A product goes on sale at once when you are live and enable_checkout is true; before that it loads as a draft you can see and cannot sell. feed_action delete withdraws the product. Price by quantity: a record carries offer {price_mode: schedule, schedule_kind, price_schedule}. volume: every unit is priced at the price of the highest tier the quantity reaches. graduated: the units within each tier are priced at that tier’s price. A bad schedule is refused with 400 invalid_input, detail price_schedule: <reason>.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"item_id":{"type":"string","description":"Tier 1. Stable and unique; the SKU and the lot code of the product."},"title":{"type":"string","description":"Tier 1. Under 150 characters."},"description":{"type":"string","description":"Tier 1. Plain text, under 5,000 characters."},"brand":{"type":"string"},"seller_name":{"type":"string"},"category":{"type":"string","description":"A CommerceBook category key, for example home_textiles."},"condition":{"type":"string","enum":["new","refurbished","used","open_box","defective"]},"price":{"type":["number","string"],"description":"Unit price in dollars."},"currency":{"type":"string","enum":["USD"]},"sale_price":{"type":["number","string"]},"sale_price_effective":{"type":"string","description":"start/end ISO dates"},"availability":{"type":"string","enum":["in_stock","out_of_stock","preorder","backorder"]},"inventory_quantity":{"type":["integer","string"]},"inventory_as_of":{"type":"string","description":"ISO 8601 with zone; the count date.","format":"date-time"},"image_link":{"type":"string","format":"uri"},"additional_image_link":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"enable_search":{"type":["boolean","string"]},"enable_checkout":{"type":["boolean","string"],"description":"true puts the product on sale once you are live."},"gtin":{"type":"string"},"mpn":{"type":"string"},"title_holder":{"type":"string","enum":["owned","custodial"]},"ship_from":{"type":"string","description":"The ship-from address of a seller-held product, by the label or id of one of your addresses (GET /seller/ship-from); blank follows your default. An unknown label skips the record with reason ship_from_unknown and your labels; a product stored at a warehouse (title_holder custodial) skips with ship_from_stored_at_warehouse. Buyers see only the city and state."},"count_source":{"type":"string","enum":["wms_count","seller_statement"]},"shipping_methods":{"type":"string","description":"How the goods reach the buyer, comma separated: pickup, ship, parcel, ltl."},"channels":{"type":"string","description":"The older name of shipping_methods, still read."},"price_on_request":{"type":["boolean","string"],"description":"True lists the product with no public price (\"Quote on request\"); the price on the record stays private, and buyers post a request the seller quotes."},"feed_opt_out":{"type":["boolean","string"],"description":"True keeps the product on the market and out of the outside feeds."},"ship_days":{"type":["integer","string"]},"shipping":{"type":"string","description":"zone:service:price, for example US:ground:0.00"},"min_order_qty":{"type":["integer","string"]},"quantity_price_tiers":{"type":"string","description":"qty:price list, for example 12:22.00; 48:20.50 (a volume schedule from a feed)."},"condition_note":{"type":"string"},"feed_action":{"type":"string","enum":["upsert","delete"]},"offer":{"type":"object","description":"Price by quantity on this record. price may then be left out: the first tier is the unit price. A bad schedule is refused with 400 invalid_input, detail price_schedule: <reason>.","properties":{"price_mode":{"type":"string","enum":["fixed","schedule"],"description":"schedule prices the product by quantity from price_schedule; fixed (the default) is one price."},"schedule_kind":{"type":"string","enum":["volume","graduated"],"description":"How the tiers apply (default volume). volume: every unit is priced at the price of the highest tier the quantity reaches. graduated: the units within each tier are priced at that tier’s price."},"price_schedule":{"type":"array","items":{"type":"object","properties":{"min_qty":{"type":"integer","minimum":1},"unit_price_cents":{"type":"integer","minimum":1}},"required":["min_qty","unit_price_cents"]},"minItems":2,"maxItems":10,"description":"The tiers, ascending by min_qty: {min_qty, unit_price_cents}; the first tier starts at min_qty 1 (or at the offer minimum) and its price is the unit price; each later tier has a larger min_qty and a lower price; 2 to 10 tiers."}}}},"required":["item_id"],"additionalProperties":true,"description":"One record of the CommerceBook product data template v1.1 (ACP field names). Every other template field is accepted and kept in the product specs."}},"dry_run":{"type":"boolean","default":false},"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96}},"required":["records"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogUpsertResult"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/catalog/lots/{id}/hold":{"post":{"operationId":"holdSellerLot","tags":["Seller"],"summary":"Pause sales of a product","security":[{"bearerKey":[]}],"description":"Pauses the product’s live offers until you resume sales (409 lot_state when none is live).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The product (lot_id).","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"},"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"lot_id, offers, status paused, state."}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/catalog/lots/{id}/release":{"post":{"operationId":"releaseSellerLot","tags":["Seller"],"summary":"Resume sales of a paused product","security":[{"bearerKey":[]}],"description":"Puts the paused offers back on the market through the same checks as publishing (you must be live; a product stored at a warehouse needs its warehouse agreement accepted).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The product (lot_id).","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/catalog/reconcile":{"get":{"operationId":"reconcileSellerCatalog","tags":["Seller"],"summary":"Check the stock of your products against the warehouse count","security":[{"bearerKey":[]}],"description":"The stock problems of your products against the count on record (the evidence count and its count date), and the stale counts: a count is stale when it is older than 72 hours. Writes nothing.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconcileResult"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/catalog/verify":{"post":{"operationId":"verifySellerCatalog","tags":["Seller"],"summary":"Confirm the count of every product","security":[{"bearerKey":[]}],"description":"After a physical count matched: every product that is not withdrawn keeps its quantity on hand as the count, and now becomes its count date (cycle_count).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"stamped (the number of products confirmed), as_of (the count date)."}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/orders":{"get":{"operationId":"listSellerOrders","tags":["Seller"],"summary":"Orders of your products","security":[{"bearerKey":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}},{"name":"status","in":"query","schema":{"type":"string","enum":["created","authorised","released","accepted","completed","cancelled","failed"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SellerOrder"}},"next_cursor":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/orders/{id}":{"get":{"operationId":"getSellerOrder","tags":["Seller"],"summary":"One order with payment, fulfillment, disputes, refunds and transitions","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The order.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerOrder"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/orders/{id}/release":{"post":{"operationId":"releaseSellerOrder","tags":["Seller"],"summary":"Release an order to ship","security":[{"bearerKey":[]}],"description":"market_fulfillment_release: the order must be authorised with no open dispute. Shoppers have 30 days from delivery to file a dispute, or longer when the seller sets it. A shipped order over $500 needs evidence, the count and at least one photo (409 release_evidence_required). You are paid 2 business days after delivery unless a dispute is open; a shipped order with no delivery event starts that clock 14 business days after release.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The order.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"evidence":{"type":"object","properties":{"count":{"type":"integer","minimum":1},"photos":{"type":"array","items":{"type":"string","description":"A photo link or a member-media path."},"minItems":1,"maxItems":20},"note":{"type":"string","maxLength":1000}},"required":["count","photos"]},"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/orders/{id}/ship":{"post":{"operationId":"shipSellerOrder","tags":["Seller"],"summary":"Mark a released order shipped or picked up","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The order.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["shipped","picked_up"],"default":"shipped"},"carrier":{"type":"string"},"tracking":{"type":"string"},"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96},"buy_label":{"type":"boolean","description":"True buys the label for the quoted service at the live price, charged to your balance (needs payments write; past the key’s confirm amount or 30-day cap it answers 202 pending_owner_confirmation and waits for the owner); the carrier and tracking are written for you, and label_url is a 10-minute link to the PDF. Omit it to send your own carrier and tracking."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"202":{"description":"pending_owner_confirmation: a label bought with a key above the owner’s confirm amount or past the 30-day spending cap is not bought; it waits for the owner at Settings, Agent access (pending_id, reason, amount_cents). An approved item runs once.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"},"detail":{"oneOf":[{"type":"string"},{"type":"null"}]},"pending_id":{"type":"string","format":"uuid"},"reason":{"type":"string"},"amount_cents":{"type":"integer"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/orders/{id}/cancel":{"post":{"operationId":"cancelSellerOrder","tags":["Seller"],"summary":"Cancel an order before release","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The order.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"},"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/disputes":{"get":{"operationId":"listSellerDisputes","tags":["Seller"],"summary":"Disputes on your orders (the latest per order)","security":[{"bearerKey":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}},{"name":"status","in":"query","schema":{"type":"string","enum":["open","needs_evidence","resolved_buyer","resolved_seller","withdrawn"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true}},"next_cursor":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/disputes/{id}/reply":{"post":{"operationId":"replySellerDispute","tags":["Seller"],"summary":"Answer a dispute with a note and evidence","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The dispute.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":4000},"evidence":{"type":"object","additionalProperties":true,"description":"Links, tracking numbers, photo URLs, as key and value."},"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96}},"required":["note"]}}}},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/policies":{"get":{"operationId":"getSellerPolicies","tags":["Seller"],"summary":"Your policies","security":[{"bearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerPolicies"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateSellerPolicies","tags":["Seller"],"summary":"Change your policies","security":[{"bearerKey":[]}],"description":"The named fields only. The owner accepts the policies in person on the seller portal; an agent never accepts them (POST /seller/policies/accept answers 403 owner_accepts_policies).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerPolicyFields"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerPolicies"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/payouts/statement":{"get":{"operationId":"getSellerStatement","tags":["Seller"],"summary":"Your payout statement","security":[{"bearerKey":[]}],"description":"Each charged sale and settled refund with its order, amount, CommerceBook fee, card fee (processing) and your proceeds; totals and the amount not charged yet (pending, the card on hold).","parameters":[{"name":"from","in":"query","schema":{"type":"string","description":"All time by default.","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","description":"Inclusive; all time by default.","format":"date"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"from, to, lines, totals, pending_cents, pending_count."}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/performance":{"get":{"operationId":"getSellerPerformance","tags":["Seller"],"summary":"Your seller sheet, live","security":[{"bearerKey":[]}],"description":"The seller sheet v1: identity, catalog completeness, fulfillment, the 90 day and lifetime rates with the counts behind each, policies.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerSheet"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/delegations":{"get":{"operationId":"listSellerDelegations","tags":["Seller"],"summary":"Your warehouse agreements (delegations in the API) with the warehouses that store and ship for you","security":[{"bearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true}}},"required":["items"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"requestSellerDelegation","tags":["Seller"],"summary":"Ask a warehouse for a warehouse agreement to store and ship your goods","security":[{"bearerKey":[]}],"description":"The warehouse answers from its own account. 503 not_ready until the warehouse agreement functions are in place.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"warehouse_member_id":{"type":"string","format":"uuid"},"facility_id":{"type":"string","format":"uuid"},"terms":{"type":"string"},"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96}},"required":["warehouse_member_id"]}}}},"responses":{"201":{"description":"Requested","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (own_lead, already_claimed, thread_not_open, summary_names_shipper, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"not_ready: the warehouse agreement functions are not applied yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/events":{"get":{"operationId":"listSellerEvents","tags":["Seller"],"summary":"Your ledger: what happened and whether your agent did it","security":[{"bearerKey":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}},{"name":"agent_only","in":"query","schema":{"type":"boolean","default":false}},{"name":"object_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true}},"next_cursor":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired (an agent link past its 90 days).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example leads:write), activity names the activity and hint where the owner turns it on (every key starts read-only, payments off). membership_suspended: the member was removed from the exchange or banned, and the key may only read. posting_suspended: posting is suspended for confirmed false leads; detail is the date it ends. role_not_permitted: the login that issued the key has a role on the account (admin, sales or ops) that may not run this action; detail is domain:level, role the key's role, roles the roles that may. key_issuer_removed: the login that issued the key no longer holds the account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","tags":["Account"],"summary":"This document","security":[],"responses":{"200":{"description":"The OpenAPI 3.1 document."}}}},"/leads/{id}":{"get":{"operationId":"getLead","tags":["Leads"],"summary":"One lead as the exchange shows it","security":[{"bearerKey":[]}],"description":"quality is the lead quality: score 0 to 9 by a fixed rule over the fields present (service, location, volume, timing, product, current provider, inbound mode, order profile, budget), present lists them, and missing lists the absent ones on your own lead only (null for a buyer).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lead.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateLead","tags":["Leads"],"summary":"Add details to a lead you posted","security":[{"bearerKey":[]}],"description":"Add details on My Listings: your draft or open lead, before any buyer claims it (409 lead_has_claims after one). A field you send replaces the stored one, null clears it, and a field you leave out stays. The product, the current provider (shown to a buyer after purchase), the inbound mode, units per order and the budget are kept in the lead attributes; the volumes and the window are the lead columns. The summary and the scope of work stay as they are. The answer carries the new quality.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lead.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product":{"oneOf":[{"type":"string","maxLength":200},{"type":"null"}]},"current_provider":{"oneOf":[{"type":"string","maxLength":200},{"type":"null"}]},"inbound_mode":{"oneOf":[{"type":"array","items":{"type":"string","enum":["parcel","pallet","container"]},"maxItems":3},{"type":"null"}]},"units_per_order":{"oneOf":[{"type":"integer","minimum":0},{"type":"null"}]},"rate_expectation":{"oneOf":[{"type":"string","description":"The budget or rate expectation in the prospect’s words, such as about $4 a pick.","maxLength":200},{"type":"null"}]},"orders_month":{"oneOf":[{"type":"integer"},{"type":"null"}]},"pallets_on_hand":{"oneOf":[{"type":"integer"},{"type":"null"}]},"pallets_inbound_month":{"oneOf":[{"type":"integer"},{"type":"null"}]},"units_month":{"oneOf":[{"type":"integer"},{"type":"null"}]},"containers_month":{"oneOf":[{"type":"integer"},{"type":"null"}]},"sqft":{"oneOf":[{"type":"integer"},{"type":"null"}]},"skus":{"oneOf":[{"type":"integer"},{"type":"null"}]},"window_start":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"window_end":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"quality":{"$ref":"#/components/schemas/LeadQuality"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}/buy":{"post":{"operationId":"buyLead","tags":["Leads"],"summary":"Buy a lead, within the limits on your key","security":[{"bearerKey":[]}],"description":"The purchase as the claim sheet does it, inside the money ceilings the owner set on Agent access (per action and per day; none by default). Over a ceiling the call is refused with 403 needs_approval and an approval item; once the owner approves it, the same call passes once. A free lead, or a deployment without card payments, claims at once (payment demo). Otherwise the card path of a Stripe PaymentIntent for the price, and in Stripe test mode payment_method (a test token such as pm_card_visa) confirms it at once. The claim is written when the payment succeeds.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lead.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"operation_id":{"type":"string","description":"Idempotency key of the card payment; the request id by default."},"payment_method":{"type":"string","description":"Stripe test mode only: a test payment method id (pm_card_visa)."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClaimOutcome"}}}},"202":{"description":"pending_owner_confirmation: over the key’s spending cap or confirm amount, or an action the owner confirms. Not executed; it waits for the owner (GET /keys/{id}/pending).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingOwnerConfirmation"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}/withdraw":{"post":{"operationId":"withdrawLead","tags":["Leads"],"summary":"Withdraw a lead you posted","security":[{"bearerKey":[]}],"description":"Takes your draft or open lead off the exchange. Refused once a buyer has claimed it (409 lead_has_claims).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lead.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"already":{"type":"boolean"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}/places":{"patch":{"operationId":"setLeadPlaces","tags":["Leads"],"summary":"Change how many buyers may buy a lead","security":[{"bearerKey":[]}],"description":"One place makes the lead exclusive; more makes it open to that many buyers.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lead.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"places":{"type":"integer","minimum":1,"maximum":50}},"required":["places"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"max_buyers":{"type":"integer"},"status":{"type":"string"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}/text":{"patch":{"operationId":"setLeadText","tags":["Leads"],"summary":"Change the title, the summary or the source of a lead you posted","security":[{"bearerKey":[]}],"description":"Edit text on My Listings: your draft or open lead. Each field you send replaces the stored one; a field you leave out stays as it is. The title (80) and the one-line summary (140) pass the same identity check as the need (400 invalid_input with title_names_company or summary_short_names_company). lead_source own clears referral_source; a blank referral_source keeps the lead referred with no name.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lead.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":80},"summary_short":{"type":"string","maxLength":140},"lead_source":{"type":"string","enum":["own","referral"]},"referral_source":{"type":"string","maxLength":60}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"summary_short":{"type":"string"},"lead_source":{"type":"string"},"referral_source":{"oneOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}/price":{"patch":{"operationId":"setLeadPrice","tags":["Leads"],"summary":"Change the price of a lead you posted","security":[{"bearerKey":[]}],"description":"Edit Price on My Listings: your draft or open lead, before any buyer claims it (409 lead_has_claims after one). price_cents 0 is a free lead. A percentage stays as it is: a price on a percentage lead makes the terms both, and 0 on a both lead leaves the percentage alone.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lead.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"price_cents":{"type":"integer","description":"The flat price in cents.","minimum":0,"maximum":100000000}},"required":["price_cents"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"price_cents":{"type":"integer"},"terms":{"type":"string"},"status":{"type":"string"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}/introduction":{"post":{"operationId":"sendLeadIntroduction","tags":["Leads"],"summary":"Send the introduction to the buyers of your lead","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lead.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","maxLength":2000}}}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"type":"object","properties":{"introduction_id":{"type":"string","format":"uuid"},"sent_at":{"type":"string"},"already_sent":{"type":"boolean"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}/call":{"post":{"operationId":"scheduleLeadCall","tags":["Leads"],"summary":"Schedule the call with the buyers of your lead","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lead.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"at":{"type":"string","description":"ISO 8601 with zone.","format":"date-time"}},"required":["at"]}}}},"responses":{"201":{"description":"Scheduled","content":{"application/json":{"schema":{"type":"object","properties":{"call_id":{"type":"string","format":"uuid"},"scheduled_at":{"type":"string"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}/rating":{"post":{"operationId":"rateLead","tags":["Leads"],"summary":"Rate a lead you bought as described or overstated","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lead.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rating":{"type":"string","enum":["as_described","overstated"]}},"required":["rating"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"rating":{"type":"string"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}/mark":{"post":{"operationId":"markLead","tags":["Leads"],"summary":"Pass on a lead or save it","security":[{"bearerKey":[]}],"description":"Pass and Save on the exchange: your own note on another member’s lead, kept for your login. pass lists the lead last; save keeps it under the Saved chip; null clears the mark. A lead you cannot read answers not_found; your own lead answers own_lead. Every role may mark.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lead.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mark":{"oneOf":[{"type":"string","enum":["pass","save"]},{"type":"null"}]}},"required":["mark"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"mark":{"oneOf":[{"type":"string"},{"type":"null"}]},"saved":{"type":"boolean"},"passed":{"type":"boolean"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}/stars":{"post":{"operationId":"starLead","tags":["Leads"],"summary":"Give a lead you bought 1 to 5 stars","security":[{"bearerKey":[]}],"description":"One rating per purchase, within 30 days of the purchase. The stars count toward the poster rating that buyers see on every lead of that poster. A second rating answers already_rated; a purchase older than 30 days answers rating_window_closed; no purchase of the lead by you answers not_found (detail claim).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lead you bought.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stars":{"type":"integer","description":"1 to 5.","minimum":1,"maximum":5}},"required":["stars"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"claim_id":{"type":"string","format":"uuid"},"lead_id":{"type":"string","format":"uuid"},"stars":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/earnings":{"get":{"operationId":"getLeadEarnings","tags":["Leads"],"summary":"What each of your leads earned","security":[{"bearerKey":[]}],"description":"One row per lead you posted (drafts left out), newest first: sales, the amount buyers paid, the CommerceBook fee, your proceeds, the part held until the dispute window ends, the part paid out and refunds. Totals sum the rows; waiting is the payout waiting for your bank details, if any.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"service":{"oneOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"listed_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"price_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"terms":{"oneOf":[{"type":"string"},{"type":"null"}]},"max_buyers":{"oneOf":[{"type":"integer"},{"type":"null"}]},"sales":{"type":"integer"},"gross_cents":{"type":"integer"},"fee_cents":{"type":"integer"},"net_cents":{"type":"integer"},"held_cents":{"type":"integer"},"paid_out_cents":{"type":"integer"},"refunded_cents":{"type":"integer"},"last_sale_at":{"oneOf":[{"type":"string"},{"type":"null"}]}}}},"totals":{"type":"object","properties":{"leads":{"type":"integer"},"sales":{"type":"integer"},"gross_cents":{"type":"integer"},"fee_cents":{"type":"integer"},"net_cents":{"type":"integer"},"held_cents":{"type":"integer"},"paid_out_cents":{"type":"integer"}}},"waiting":{"type":"object","additionalProperties":true,"description":"The payout waiting for your bank details, or null."}},"required":["items","totals"]}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/statement":{"get":{"operationId":"getLeadStatement","tags":["Leads"],"summary":"Your lead sales statement","security":[{"bearerKey":[]}],"description":"One line per sale of your leads in the window, newest first: the amount, the CommerceBook fee, your proceeds, refunds and the payout state (held, waiting, paid_out or refunded). from and to are ISO 8601 times; all time by default; to is exclusive.","parameters":[{"name":"from","in":"query","schema":{"type":"string","description":"All time by default.","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","description":"Exclusive; all time by default.","format":"date-time"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"oneOf":[{"type":"string"},{"type":"null"}]},"to":{"oneOf":[{"type":"string"},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string"},"kind":{"type":"string"},"claim_id":{"type":"string","format":"uuid"},"lead_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"service":{"oneOf":[{"type":"string"},{"type":"null"}]},"payment":{"type":"string"},"amount_cents":{"type":"integer"},"fee_cents":{"type":"integer"},"proceeds_cents":{"type":"integer"},"refunded_cents":{"type":"integer"},"payout_status":{"type":"string","enum":["held","waiting","paid_out","refunded"]},"window_ends_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"paid_out_at":{"oneOf":[{"type":"string"},{"type":"null"}]}}}},"totals":{"type":"object","properties":{"amount_cents":{"type":"integer"},"fee_cents":{"type":"integer"},"proceeds_cents":{"type":"integer"},"refunded_cents":{"type":"integer"}}},"waiting":{"type":"object","additionalProperties":true,"description":"The payout waiting for your bank details, or null."}},"required":["lines","totals"]}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/{id}/challenge":{"post":{"operationId":"challengeLead","tags":["Leads"],"summary":"Challenge a listing that duplicates your prospect","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lead.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"evidence":{"type":"string","maxLength":4000}},"required":["evidence"]}}}},"responses":{"201":{"description":"Filed","content":{"application/json":{"schema":{"type":"object","properties":{"challenge_id":{"type":"string","format":"uuid"},"lead_id":{"type":"string","format":"uuid"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/claims":{"get":{"operationId":"listMyClaims","tags":["Leads"],"summary":"The leads you bought","security":[{"bearerKey":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"A claim: id, lead_id, deal_id, amount_cents, payment_status, payout_status, dispute_window_ends_at, refunded_cents, won_at."}},"next_cursor":{"oneOf":[{"type":"string"},{"type":"null"}]},"total":{"type":"integer"}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/claims/{id}/outcome":{"post":{"operationId":"logClaimOutcome","tags":["Leads"],"summary":"Record what happened with a lead you bought","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The claim.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"outcome":{"type":"string","description":"The outcome key the claim sheet offers."}},"required":["outcome"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"claim_id":{"type":"string","format":"uuid"},"outcome":{"type":"string"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/claims/{id}/defect":{"post":{"operationId":"reportClaimDefect","tags":["Leads"],"summary":"Report a defect on a lead you bought","security":[{"bearerKey":[]}],"description":"Within 7 days of buying the lead. Six kinds are refund reasons: email_bounced, phone_invalid, already_client and duplicate are checked at once; never_asked waits for the prospect’s reply; fabricated (a contact that does not exist) needs evidence, is decided at review, and a confirmed one refunds the lead and is a strike against the seller. overstated (volumes smaller than posted) needs evidence and is an annotation on the seller’s record: it refunds nothing and is never a strike (see /policies).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The claim.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","description":"The defect kind the defect sheet offers: email_bounced, phone_invalid, already_client, duplicate, never_asked, overstated or fabricated."},"evidence":{"type":"string","maxLength":4000}},"required":["kind"]}}}},"responses":{"201":{"description":"Reported","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"defect_id, kind, checked, awaiting_reply, annotation, refunded_cents, amount_cents."}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/crm/deals/{id}/notes":{"post":{"operationId":"addDealNote","tags":["CRM"],"summary":"Add a note to a deal","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The deal.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","maxLength":8000},"type":{"type":"string"}},"required":["text"]}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deal_id":{"type":"string","format":"uuid"},"text":{"type":"string"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/crm/import":{"post":{"operationId":"importDeals","tags":["CRM"],"summary":"Import deals from a CSV file or rows","security":[{"bearerKey":[]}],"description":"The Import button of the CRM: send csv (the file text; the same column names as the sample, and HubSpot style exports are renamed the same way) or rows (objects with name, company, service, stage, target_market, monthly_revenue in dollars, description, expected_closing_date). One deal per row; a company is found by name or created. dry_run true returns what would be created and writes nothing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"csv":{"type":"string"},"rows":{"type":"array","items":{"type":"object","additionalProperties":true}},"dry_run":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"type":"boolean"},"counts":{"type":"object","properties":{"created":{"type":"integer"},"skipped":{"type":"integer"}}},"created":{"type":"array","items":{"type":"object","additionalProperties":true}},"skipped":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"reason":{"type":"string"}}}}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/capacity/requests/{id}/accept":{"post":{"operationId":"acceptCapacityQuote","tags":["Capacity"],"summary":"Accept the quote on a request you sent","security":[{"bearerKey":[]}],"description":"Writes the contract record in the ledger of both members. Nothing is paid.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The request.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapacityRequest"}}}},"202":{"description":"pending_owner_confirmation: over the key’s spending cap or confirm amount, or an action the owner confirms. Not executed; it waits for the owner (GET /keys/{id}/pending).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PendingOwnerConfirmation"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/capacity/requests/{id}/quote/withdraw":{"post":{"operationId":"withdrawCapacityQuote","tags":["Capacity"],"summary":"Take back a quote before it is accepted","security":[{"bearerKey":[]}],"description":"The request your node received returns to requested.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The request.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapacityRequest"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/capacity/requests/{id}/withdraw":{"post":{"operationId":"withdrawCapacityRequest","tags":["Capacity"],"summary":"Withdraw a request you sent","security":[{"bearerKey":[]}],"description":"While the request is requested or quoted it becomes withdrawn, withdrawn_at is stamped and the thread with the warehouse, when one exists, gets the note \"Request withdrawn.\". A second call answers the withdrawn row. Once accepted (or declined) it answers 409 capacity_state; send the warehouse a message instead.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The request you sent.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapacityRequest"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/threads/{id}/respond":{"post":{"operationId":"respondToThread","tags":["Messages"],"summary":"Accept or ignore a message request","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The thread.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"accept":{"type":"boolean"}},"required":["accept"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"thread_id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/threads/{id}/read":{"post":{"operationId":"markThreadRead","tags":["Messages"],"summary":"Mark a thread read","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The thread.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"thread_id":{"type":"string","format":"uuid"},"read":{"type":"boolean"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/threads/{id}/mute":{"post":{"operationId":"muteThread","tags":["Messages"],"summary":"Mute or unmute a thread","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The thread.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"muted":{"type":"boolean"}},"required":["muted"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"thread_id":{"type":"string","format":"uuid"},"muted":{"type":"boolean"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/threads/{id}/report":{"post":{"operationId":"reportThread","tags":["Messages"],"summary":"Report a thread or one message to CommerceBook","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The thread.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":1000},"message_id":{"type":"string","format":"uuid"}},"required":["reason"]}}}},"responses":{"201":{"description":"Reported","content":{"application/json":{"schema":{"type":"object","properties":{"report_id":{"type":"string","format":"uuid"},"thread_id":{"type":"string","format":"uuid"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/members/{id}/block":{"post":{"operationId":"blockMember","tags":["Messages"],"summary":"Block or unblock a member","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The member.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"block":{"type":"boolean"}},"required":["block"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"blocked":{"type":"boolean"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/groups":{"post":{"operationId":"createGroup","tags":["Messages"],"summary":"Start a group with members you already message","security":[{"bearerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"member_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":2,"maxItems":20},"subject":{"type":"string"},"body":{"type":"string","maxLength":4000}},"required":["member_ids","subject","body"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"thread_id":{"type":"string","format":"uuid"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/attachables":{"get":{"operationId":"listAttachables","tags":["Messages"],"summary":"The records you can attach to a message","security":[{"bearerKey":[]}],"description":"Your leads, deals, facilities and capacity requests as attachment cards; send one as attachment {type, id, label} on a message.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"leads":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"deals":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"facilities":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"capacity_requests":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}}}}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/unread":{"get":{"operationId":"getUnreadCount","tags":["Messages"],"summary":"How many messages wait unread","security":[{"bearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"unread":{"type":"integer"}}}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/network/members/{id}":{"get":{"operationId":"getMember","tags":["Network"],"summary":"One member’s public card","security":[{"bearerKey":[]}],"description":"The public row, facilities, the node (with its rate card) and the member record (member since, leads posted, reply time).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The member.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/network/delegations":{"get":{"operationId":"listWarehouseDelegations","tags":["Network"],"summary":"Sellers asking your warehouse for a warehouse agreement to store and ship their goods","security":[{"bearerKey":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"A warehouse agreement (a delegation in the API): id, status, seller, facility, terms, requested_at."}},"next_cursor":{"oneOf":[{"type":"string"},{"type":"null"}]},"total":{"type":"integer"}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/network/delegations/{id}/respond":{"post":{"operationId":"respondToDelegation","tags":["Network"],"summary":"Accept or decline a seller’s request for a warehouse agreement","security":[{"bearerKey":[]}],"description":"Nothing stored with you is offered for sale until you accept.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The warehouse agreement (delegation id).","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"accept":{"type":"boolean"}},"required":["accept"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/network/delegations/{id}/end":{"post":{"operationId":"endDelegation","tags":["Network"],"summary":"End a warehouse agreement","security":[{"bearerKey":[]}],"description":"The products stored under it stop selling (their offers pause).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The warehouse agreement (delegation id).","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/settings":{"get":{"operationId":"getSettings","tags":["Settings"],"summary":"Your phone, who sees it and how you hear about messages","security":[{"bearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactSettings"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/settings/contact":{"patch":{"operationId":"updateContactSettings","tags":["Settings"],"summary":"Change your phone, its visibility or message notifications","security":[{"bearerKey":[]}],"description":"The named fields only; phone null clears it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"oneOf":[{"type":"string","maxLength":30},{"type":"null"}]},"phone_visibility":{"type":"string","enum":["members","public","hidden"]},"message_notify":{"type":"string","enum":["immediate","daily","none"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactSettings"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/agent/limits":{"get":{"operationId":"getAgentLimits","tags":["Account"],"summary":"The limits on this key and what waits for the owner","security":[{"bearerKey":[]}],"description":"The money ceilings per action and per day, the areas that need the owner’s approval, what the key spent today and the approval items not yet used. A named key or an agent link key, of a warehouse or a seller.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentLimits"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/entity":{"get":{"operationId":"getSellerEntity","tags":["Seller"],"summary":"Your business details and what they still need","security":[{"bearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"entity":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"missing":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"ready":{"type":"object","additionalProperties":true}}}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateSellerEntity","tags":["Seller"],"summary":"Fill in your business details","security":[{"bearerKey":[]}],"description":"The fields of the Business, Tax, Address, Person and Owners steps: legal_name, entity_type, ein (only the last four digits are kept), address_line1, address_line2, city, state, postal_code, country, responsible_name, responsible_title, responsible_email, responsible_phone, beneficial_owners, w9_status. An unknown field is refused by name.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"entity":{"type":"object","additionalProperties":true},"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96}},"required":["entity"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"entity, missing, ready, status."}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/fulfillment":{"patch":{"operationId":"setSellerFulfillment","tags":["Seller"],"summary":"Choose how your orders ship","security":[{"bearerKey":[]}],"description":"self with ship_from, cutoff_local (HH:MM) and carriers; or warehouse, and with warehouse_member_id (from GET /seller/delegations/warehouses) the request for a warehouse agreement goes out in the same call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fulfillment_mode":{"type":"string","enum":["self","warehouse"]},"ship_from":{"type":"object","additionalProperties":true,"description":"address_line1, address_line2, city, state, postal_code."},"cutoff_local":{"type":"string"},"carriers":{"type":"array","items":{"type":"string"}},"warehouse_member_id":{"type":"string","format":"uuid"},"facility_id":{"type":"string","format":"uuid"},"terms":{"type":"string"},"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96}},"required":["fulfillment_mode"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"entity, missing, ready, and delegation (the warehouse agreement) when one was requested."}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/policies/accept":{"post":{"operationId":"acceptSellerPolicies","tags":["Seller"],"summary":"Accept your seller policies (the owner only)","security":[{"bearerKey":[]}],"description":"Always answers 403 owner_accepts_policies with a key: an agent never accepts the policies for the owner. The owner accepts them in person, signed in on the seller portal (https://seller.commercebook.ai/sell?step=policies); GET /seller/me then shows policies_accepted.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"string"},"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"policies, ready, status."}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"owner_accepts_policies: the owner accepts the policies in person; hint says where.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/delegations/warehouses":{"get":{"operationId":"listDelegationWarehouses","tags":["Seller"],"summary":"Verified warehouses that can store and ship for you","security":[{"bearerKey":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"member_id, name, facilities."}},"next_cursor":{"oneOf":[{"type":"string"},{"type":"null"}]},"total":{"type":"integer"}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/delegations/{id}/end":{"post":{"operationId":"endSellerDelegation","tags":["Seller"],"summary":"End your warehouse agreement with a warehouse","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The warehouse agreement (delegation id).","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/ship-from":{"get":{"operationId":"listSellerShipFrom","tags":["Seller"],"summary":"Your ship-from addresses","security":[{"bearerKey":[]}],"description":"Every address you ship from, the default first, with the products that name each one. You can ship from more than one address; buyers see only the city and state. The street lines, the postal code and the phone stay with you, the operator and the carrier label. Needs the business details activity (read). The MCP tool is commercebook_seller_products action ship_from.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ShipFrom"}},"default_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"rule":{"type":"string"}},"required":["items"]}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createSellerShipFrom","tags":["Seller"],"summary":"Add a ship-from address","security":[{"bearerKey":[]}],"description":"label is your own name for the place (\"Home\", \"Dallas branch\"), never shown to a buyer. The first address becomes the default; is_default true makes a new one the default. A product names its address by label or id (ship_from on POST /seller/catalog/upsert, the CSV import and PATCH /seller/catalog/lots/{id}); a product that names none ships from the default. Needs the business details activity (write). The MCP tool is commercebook_seller_products action ship_from_set.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","maxLength":60},"address_line1":{"type":"string","maxLength":200},"address_line2":{"oneOf":[{"type":"string","maxLength":200},{"type":"null"}]},"city":{"type":"string"},"state":{"type":"string","description":"Two letters.","minLength":2,"maxLength":2},"postal_code":{"type":"string","description":"Five digits, or ZIP+4."},"country":{"type":"string","description":"US."},"phone":{"oneOf":[{"type":"string","description":"For the carrier label.","maxLength":30},{"type":"null"}]},"is_default":{"type":"boolean"},"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96}},"required":["label","address_line1","city","state","postal_code"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipFrom"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/ship-from/{id}":{"patch":{"operationId":"updateSellerShipFrom","tags":["Seller"],"summary":"Edit, make default or archive a ship-from address","security":[{"bearerKey":[]}],"description":"The named fields only. is_default true makes this address the default (the products that name none ship from it). archived true archives it: refused with 409 ship_from_in_use (detail: the number of live products) while a live product names it, and with ship_from_is_default for the default; archived false restores it. Needs the business details activity (write). The MCP tool is commercebook_seller_products action ship_from_set with id.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The ship-from address.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","maxLength":60},"address_line1":{"type":"string","maxLength":200},"address_line2":{"oneOf":[{"type":"string","maxLength":200},{"type":"null"}]},"city":{"type":"string"},"state":{"type":"string","minLength":2,"maxLength":2},"postal_code":{"type":"string"},"country":{"type":"string"},"phone":{"oneOf":[{"type":"string","maxLength":30},{"type":"null"}]},"is_default":{"type":"boolean","enum":[true]},"archived":{"type":"boolean"},"operation_id":{"type":"string","description":"Idempotency key of the RPCs this call runs; the request id by default.","minLength":8,"maxLength":96}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShipFrom"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (the owner’s limits on Agent access hold this action; approval_id names the item waiting for the owner).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (lead_has_claims, status_invalid, delegation_state, thread_not_open, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/profile":{"get":{"operationId":"getProfile","tags":["Profile"],"summary":"The profile page as the owner sees it","security":[{"bearerKey":[]}],"description":"About and its source, services, people with their photos, certifications, the logo, the phone and who sees it, and the facility count. Stored paths come with their public addresses (logo_url, photo_url).","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/profile/services/catalog":{"get":{"operationId":"listServiceCatalog","tags":["Profile"],"summary":"The standard services a profile can list","security":[{"bearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"group":{"type":"string"}}}}}}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/profile/completeness":{"get":{"operationId":"getProfileCompleteness","tags":["Profile"],"summary":"The ten items of the Home meter, with the next call for each gap","security":[{"bearerKey":[]}],"description":"The same checklist as the meter on Home, in the same order: score of 10, the next missing item and, per item, the call that fills it (method, path, MCP tool). Verification has no call: CommerceBook reviews the evidence given at sign-up.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Completeness"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/profile/about":{"patch":{"operationId":"setProfileAbout","tags":["Profile"],"summary":"Write the About paragraph","security":[{"bearerKey":[]}],"description":"Up to 1,200 characters; null clears it. The source note of about is shown as the About source.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"about":{"oneOf":[{"type":"string","maxLength":1200},{"type":"null"}]},"sources":{"type":"object","properties":{"about":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): about. Kept with the write on the owner's ledger."}},"required":["about"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"about":{"oneOf":[{"type":"string"},{"type":"null"}]},"about_source":{"oneOf":[{"type":"string"},{"type":"null"}]},"sources":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"null"}]}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/profile/services":{"patch":{"operationId":"setProfileServices","tags":["Profile"],"summary":"Replace the services list","security":[{"bearerKey":[]}],"description":"The whole list in display order: {catalog_key} for a standard service (GET /profile/services/catalog), {id?, title, body} for a custom one, at most 6 custom. A service left out is removed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"services":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"catalog_key":{"type":"string"}},"required":["catalog_key"]},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string","maxLength":80},"body":{"oneOf":[{"type":"string","maxLength":240},{"type":"null"}]}},"required":["title"]}]}},"sources":{"type":"object","properties":{"services":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): services. Kept with the write on the owner's ledger."}},"required":["services"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"services":{"type":"array","items":{"$ref":"#/components/schemas/ProfileService"}}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/profile/people":{"patch":{"operationId":"setProfilePeople","tags":["Profile"],"summary":"Replace the people list","security":[{"bearerKey":[]}],"description":"At most three people in display order. Keep a person by id; a person left out is removed. A photo by photo_url is fetched and stored; photo_path keeps a stored one.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"people":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Keep an existing person (from GET /profile).","format":"uuid"},"name":{"type":"string","maxLength":80},"role":{"oneOf":[{"type":"string","maxLength":80},{"type":"null"}]},"line":{"oneOf":[{"type":"string","maxLength":160},{"type":"null"}]},"photo_path":{"oneOf":[{"type":"string","description":"A stored photo path to keep (from GET /profile)."},{"type":"null"}]},"photo_url":{"type":"string","description":"A public https address of a JPEG, PNG or WebP photo; it is fetched and stored.","format":"uri"}},"required":["name"]},"maxItems":3},"sources":{"type":"object","properties":{"people":{"type":"string","maxLength":500},"name":{"type":"string","maxLength":500},"role":{"type":"string","maxLength":500},"line":{"type":"string","maxLength":500},"photo":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): people, name, role, line, photo. Kept with the write on the owner's ledger."}},"required":["people"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"people":{"type":"array","items":{"$ref":"#/components/schemas/ProfilePerson"}}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"file_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addProfilePerson","tags":["Profile"],"summary":"Add one person, with a photo by URL or by file","security":[{"bearerKey":[]}],"description":"Adds a person after the others (three at most: 409 people_limit). The photo: photo_url, photo_base64 with photo_filename, or a multipart file part named file.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":80},"role":{"oneOf":[{"type":"string"},{"type":"null"}]},"line":{"oneOf":[{"type":"string"},{"type":"null"}]},"photo_url":{"type":"string","format":"uri"},"photo_base64":{"type":"string"},"photo_filename":{"type":"string"},"sources":{"type":"object","properties":{"name":{"type":"string","maxLength":500},"role":{"type":"string","maxLength":500},"line":{"type":"string","maxLength":500},"photo":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): name, role, line, photo. Kept with the write on the owner's ledger."}},"required":["name"]}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"The photo: JPEG, PNG or WebP, up to 10 MB.","format":"binary"},"data":{"type":"string","description":"The other fields as one JSON object."}},"required":["file"],"additionalProperties":true}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"people":{"type":"array","items":{"$ref":"#/components/schemas/ProfilePerson"}},"added":{"$ref":"#/components/schemas/ProfilePerson"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"file_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/profile/certifications":{"patch":{"operationId":"setProfileCertifications","tags":["Profile"],"summary":"Replace the certifications and systems","security":[{"bearerKey":[]}],"description":"At most 12 of up to 60 characters; duplicates are dropped.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"certifications":{"type":"array","items":{"type":"string","maxLength":60},"maxItems":12},"sources":{"type":"object","properties":{"certifications":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): certifications. Kept with the write on the owner's ledger."}},"required":["certifications"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"certifications":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/profile/contact":{"patch":{"operationId":"setProfileContact","tags":["Profile"],"summary":"Change the profile phone and who sees it","security":[{"bearerKey":[]}],"description":"The named fields only; phone null clears it. Message notifications stay as they are (PATCH /settings/contact changes them).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone":{"oneOf":[{"type":"string","maxLength":30},{"type":"null"}]},"phone_visibility":{"type":"string","enum":["members","public","hidden"]},"sources":{"type":"object","properties":{"phone":{"type":"string","maxLength":500},"phone_visibility":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): phone, phone_visibility. Kept with the write on the owner's ledger."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"phone":{"oneOf":[{"type":"string"},{"type":"null"}]},"phone_visibility":{"type":"string"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/profile/logo":{"post":{"operationId":"setProfileLogo","tags":["Profile"],"summary":"Add or replace the logo, by URL or by file","security":[{"bearerKey":[]}],"description":"JPEG, PNG or WebP up to 10 MB: url (fetched and stored), content_base64, or a multipart file part. The old file stays, so Undo on Agent activity can put it back.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"A public https address of the file; it is fetched and stored.","format":"uri"},"content_base64":{"type":"string","description":"The file itself, base64."},"filename":{"type":"string"},"content_type":{"type":"string"},"sources":{"type":"object","properties":{"logo":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): logo. Kept with the write on the owner's ledger."}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"The logo: JPEG, PNG or WebP, up to 10 MB.","format":"binary"},"data":{"type":"string","description":"The other fields as one JSON object."}},"required":["file"],"additionalProperties":true}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"logo_path":{"oneOf":[{"type":"string"},{"type":"null"}]},"logo_url":{"oneOf":[{"type":"string"},{"type":"null"}]},"previous_logo_path":{"oneOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"file_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"removeProfileLogo","tags":["Profile"],"summary":"Remove the logo","security":[{"bearerKey":[]}],"description":"The profile shows the initial mark again.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"logo_path":{"oneOf":[{"type":"string"},{"type":"null"}]},"previous_logo_path":{"oneOf":[{"type":"string"},{"type":"null"}]}}}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/profile/rate-card":{"get":{"operationId":"getRateCard","tags":["Profile"],"summary":"The rate card as published on your node","security":[{"bearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateCard"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"publishRateCard","tags":["Profile"],"summary":"Publish the rate card or change its prices","security":[{"bearerKey":[]}],"description":"The card has up to four published lines, each optional: storage per pallet per month, receiving per pallet, pick and pack per order, projects per hour. Members see them as from prices. A number sets a line, null clears it, a line left out is kept, and the card is published; every other key of the card is kept. The card must end with at least one of the four lines (400 rate_card_incomplete). With storage and receiving set, capacity requests to your node are quoted at once; the out handling is handling_out_per_pallet_cents when set, else the receiving price. Source notes are kept on the card as sources.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"storage_per_pallet_month_cents":{"oneOf":[{"type":"integer","description":"Storage, per pallet per month, in cents. Optional; null clears the line.","minimum":1},{"type":"null"}]},"handling_in_per_pallet_cents":{"oneOf":[{"type":"integer","description":"Receiving, per pallet, in cents. Optional; null clears the line.","minimum":1},{"type":"null"}]},"pick_pack_per_order_cents":{"oneOf":[{"type":"integer","description":"Pick and pack, per order, in cents. Optional; null clears the line.","minimum":1},{"type":"null"}]},"project_per_hour_cents":{"oneOf":[{"type":"integer","description":"Projects, per hour, in cents. Optional; null clears the line.","minimum":1},{"type":"null"}]},"handling_out_per_pallet_cents":{"oneOf":[{"type":"integer","description":"Pallet out, per pallet, in cents, when it differs from receiving. Used for instant quotes; not a published line. Optional; null clears it.","minimum":1},{"type":"null"}]},"terms":{"oneOf":[{"type":"string","maxLength":1000},{"type":"null"}]},"sources":{"type":"object","properties":{"storage_per_pallet_month_cents":{"type":"string","maxLength":500},"handling_in_per_pallet_cents":{"type":"string","maxLength":500},"pick_pack_per_order_cents":{"type":"string","maxLength":500},"project_per_hour_cents":{"type":"string","maxLength":500},"handling_out_per_pallet_cents":{"type":"string","maxLength":500},"terms":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): storage_per_pallet_month_cents, handling_in_per_pallet_cents, pick_pack_per_order_cents, project_per_hour_cents, handling_out_per_pallet_cents, terms. Kept with the write on the owner's ledger."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateCard"}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/facilities":{"get":{"operationId":"listFacilities","tags":["Facilities"],"summary":"Your facilities with their photos, video and pins","security":[{"bearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Facility"}}}}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createFacility","tags":["Facilities"],"summary":"Add a facility and place its pin","security":[{"bearerKey":[]}],"description":"The pin is placed from the street address; when the address does not resolve it sits at the city centre (geocode_source city) until POST /facilities/{id}/pin with retry. At most 25 facilities.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"address":{"type":"string","description":"The street address.","maxLength":200},"city":{"type":"string","maxLength":80},"state":{"type":"string","description":"Two letters.","pattern":"^[A-Za-z]{2}$"},"zip":{"oneOf":[{"type":"string","pattern":"^\\d{5}(-\\d{4})?$"},{"type":"null"}]},"sqft":{"oneOf":[{"type":"integer","minimum":0},{"type":"null"}]},"services":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":12},"sources":{"type":"object","properties":{"name":{"type":"string","maxLength":500},"address":{"type":"string","maxLength":500},"city":{"type":"string","maxLength":500},"state":{"type":"string","maxLength":500},"zip":{"type":"string","maxLength":500},"sqft":{"type":"string","maxLength":500},"services":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): name, address, city, state, zip, sqft, services. Kept with the write on the owner's ledger."}},"required":["name","address","city","state"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Facility"}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/facilities/{id}":{"patch":{"operationId":"updateFacility","tags":["Facilities"],"summary":"Change a facility","security":[{"bearerKey":[]}],"description":"The named fields change, the rest keep their values. A changed street, city, state or ZIP places the pin again.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The facility.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"address":{"type":"string","description":"The street address.","maxLength":200},"city":{"type":"string","maxLength":80},"state":{"type":"string","description":"Two letters.","pattern":"^[A-Za-z]{2}$"},"zip":{"oneOf":[{"type":"string","pattern":"^\\d{5}(-\\d{4})?$"},{"type":"null"}]},"sqft":{"oneOf":[{"type":"integer","minimum":0},{"type":"null"}]},"services":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":12},"sources":{"type":"object","properties":{"name":{"type":"string","maxLength":500},"address":{"type":"string","maxLength":500},"city":{"type":"string","maxLength":500},"state":{"type":"string","maxLength":500},"zip":{"type":"string","maxLength":500},"sqft":{"type":"string","maxLength":500},"services":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): name, address, city, state, zip, sqft, services. Kept with the write on the owner's ledger."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Facility"}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteFacility","tags":["Facilities"],"summary":"Remove a facility","security":[{"bearerKey":[]}],"description":"Cannot be undone. Refused for the only facility (409 last_facility) and for one a deal or a product listing refers to (409 facility_referenced). Its stored photos and video are removed.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The facility.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"},"reversible":{"type":"boolean"},"files_removed":{"type":"boolean"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/facilities/{id}/pin":{"post":{"operationId":"placeFacilityPin","tags":["Facilities"],"summary":"Place the pin again from the address","security":[{"bearerKey":[]}],"description":"The Retry of the Facilities tab. retry true asks the map service again even when the address was a cached miss.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The facility.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"retry":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"facility_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["already","cached","geocoded","city","not_found","no_city","lookup_failed"]},"source":{"type":"string","enum":["address","city"]},"lat":{"type":"number"},"lng":{"type":"number"}},"required":["facility_id","status"]}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/facilities/{id}/media":{"post":{"operationId":"addFacilityMedia","tags":["Facilities"],"summary":"Add a photo or the video, by URL or by file","security":[{"bearerKey":[]}],"description":"At most 10 photos and 1 video per facility. By link: url (a photo ending in jpg, jpeg, png, webp or gif; a video on YouTube, Vimeo or Loom). By file: a multipart file part, content_base64, or url with store true (fetched and stored). Pictures JPEG, PNG or WebP up to 10 MB; a video MP4, WebM or MOV.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The facility.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["image","video"]},"caption":{"oneOf":[{"type":"string","maxLength":120},{"type":"null"}]},"store":{"type":"boolean","description":"Fetch url and store the file instead of keeping the link."},"url":{"type":"string","description":"A public https address of the file; it is fetched and stored.","format":"uri"},"content_base64":{"type":"string","description":"The file itself, base64."},"filename":{"type":"string"},"content_type":{"type":"string"},"sources":{"type":"object","properties":{"media":{"type":"string","maxLength":500},"caption":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): media, caption. Kept with the write on the owner's ledger."}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"The photo or video.","format":"binary"},"data":{"type":"string","description":"The other fields as one JSON object."}},"required":["file"],"additionalProperties":true}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"type":"object","properties":{"facility_id":{"type":"string","format":"uuid"},"media":{"type":"array","items":{"$ref":"#/components/schemas/FacilityMedia"}},"added":{"$ref":"#/components/schemas/FacilityMedia"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"file_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"orderFacilityMedia","tags":["Facilities"],"summary":"Reorder the photos and video and change captions","security":[{"bearerKey":[]}],"description":"items lists every photo and video of the facility once, in the new order; a caption given replaces the old one (null clears it). Nothing is removed here.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The facility.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"caption":{"oneOf":[{"type":"string","maxLength":120},{"type":"null"}]}},"required":["id"]}},"sources":{"type":"object","properties":{"caption":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): caption. Kept with the write on the owner's ledger."}},"required":["items"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"facility_id":{"type":"string","format":"uuid"},"media":{"type":"array","items":{"$ref":"#/components/schemas/FacilityMedia"}}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/facilities/media/{id}":{"delete":{"operationId":"removeFacilityMedia","tags":["Facilities"],"summary":"Remove a photo or the video","security":[{"bearerKey":[]}],"description":"Cannot be undone: a stored file is removed.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The photo or video.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"facility_id":{"type":"string","format":"uuid"},"removed":{"type":"boolean"},"reversible":{"type":"boolean"},"files_removed":{"type":"boolean"},"media":{"type":"array","items":{"$ref":"#/components/schemas/FacilityMedia"}}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/costs/rank":{"get":{"operationId":"getCostRank","tags":["Costs"],"summary":"Where your prices rank in the network, and the top overspends","security":[{"bearerKey":[]}],"description":"Per category you have invoiced: the network median, the best price, your price and your rank among the members with that item (refused true under the minimum sample or with the comparison off). The comparison is over one canonical item: your newest item of the category (item_key, which carries the unit), the same commercial basis (basis: freight_billed or not_stated) and the last 365 days (window_days), with the newest and oldest observation dates; a price per case never ranks against a price per roll. above_median: the categories where you pay above the median, largest gap first. top_overspends: the five items with the largest gap to an exact or reviewed network quote, as Your Prices computes it.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"region":{"oneOf":[{"type":"string"},{"type":"null"}]},"categories":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"category, label, refused, sample_size, median_cents, best_cents, your_cents, your_rank, item_key, unit, basis, newest_at, oldest_at, window_days, match."}},"above_median":{"type":"array","items":{"type":"object","additionalProperties":true}},"top_overspends":{"type":"array","items":{"type":"object","additionalProperties":true}},"items_priced":{"type":"integer"}}}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/costs/summary":{"get":{"operationId":"getCostsSummary","tags":["Costs"],"summary":"The spend line of Purchases: this month and the biggest saving","security":[{"bearerKey":[]}],"description":"month (YYYY-MM, Central time), month_total_cents and month_invoice_count: the invoices read this month, by invoice date (the upload date when no date was read). invoice_count: every invoice read. biggest_saving: the item of Your Prices with the largest saving (your latest price minus an exact or reviewed network quote, times the quantity on your invoices; a possible match never counts), or null: item_key, label, category, unit, vendor, invoice_id, your_price_cents, network_price_cents, qty, saving_cents, match, basis (estimated: the network holds the quote; quoted: a supplier quoted you), next_step (request_network_price: POST /costs/quote-requests; confirm_with_supplier: ask your vendor to match, then POST /costs/prices/match) and quote_source (supplier, or network_member: the lowest price another member paid for the same item, never named). confirmed_quotes: confirmed prices nobody has bought at yet (quote status, not a saving). realized_year_cents: savings this year on purchases at a confirmed price, from the invoices (landed cost). needs_review: confirmed prices not tied to one item.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"region":{"oneOf":[{"type":"string"},{"type":"null"}]},"month":{"type":"string"},"month_total_cents":{"type":"integer"},"month_invoice_count":{"type":"integer"},"invoice_count":{"type":"integer"},"biggest_saving":{"oneOf":[{"type":"object","additionalProperties":true,"description":"item_key, label, category, unit, vendor, invoice_id, your_price_cents, network_price_cents, qty, saving_cents, match, basis, next_step, quote_source."},{"type":"null"}]},"confirmed_quotes":{"type":"integer"},"realized_year_cents":{"type":"integer"},"needs_review":{"type":"integer"}}}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/costs/prices/match":{"post":{"operationId":"recordPriceMatch","tags":["Costs"],"summary":"Record the price your vendor matched, or the refusal","security":[{"bearerKey":[]}],"description":"For one item of Your Prices (item_key from GET /costs/prices) with a network quote: matched with the new unit price in cents (lower than yours), or refused. The saving is recorded on your ledger.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item_key":{"type":"string"},"outcome":{"type":"string","enum":["matched","refused"]},"matched_unit_price_cents":{"type":"integer","minimum":1},"note":{"type":"string","maxLength":4000},"sources":{"type":"object","properties":{"matched_unit_price_cents":{"type":"string","maxLength":500},"outcome":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): matched_unit_price_cents, outcome. Kept with the write on the owner's ledger."}},"required":["item_key","outcome"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"The match note: id, category, status, your_unit_price_cents, quote_unit_price_cents, matched_unit_price_cents, item_key."}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/costs/invoices":{"get":{"operationId":"listInvoices","tags":["Costs"],"summary":"Your invoices and how each was read","security":[{"bearerKey":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}},"next_cursor":{"oneOf":[{"type":"string"},{"type":"null"}]},"total":{"type":"integer"}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"uploadInvoice","tags":["Costs"],"summary":"Upload an invoice and read it into Your Prices","security":[{"bearerKey":[]}],"description":"PDF, JPEG, PNG, WebP, HEIC, CSV or text up to 20 MB: a multipart file part, content_base64 with filename, or url (fetched). The invoice is read at once (parse false skips it): vendor, date, total and lines join Your Prices. Your own invoices and repeats are refused by the reader (parse.error own_invoice or duplicate).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"A public https address of the file; it is fetched and stored.","format":"uri"},"content_base64":{"type":"string","description":"The file itself, base64."},"filename":{"type":"string"},"content_type":{"type":"string"},"parse":{"type":"boolean","default":true},"sources":{"type":"object","properties":{"file":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): file. Kept with the write on the owner's ledger."}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"The invoice file.","format":"binary"},"data":{"type":"string","description":"The other fields as one JSON object."}},"required":["file"],"additionalProperties":true}}}},"responses":{"201":{"description":"Uploaded","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"vendor_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"total_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"line_count":{"type":"integer"},"parse":{"oneOf":[{"type":"object","additionalProperties":true,"description":"lines on success, or error."},{"type":"null"}]}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"file_too_large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/costs/invoices/{id}/parse":{"post":{"operationId":"parseInvoice","tags":["Costs"],"summary":"Read an invoice again","security":[{"bearerKey":[]}],"description":"The Retry of the Invoices tab; a re-read replaces the invoice’s lines.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The invoice.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"parse":{"type":"object","additionalProperties":true}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/costs/invoices/{id}":{"delete":{"operationId":"deleteInvoice","tags":["Costs"],"summary":"Delete an invoice and its lines","security":[{"bearerKey":[]}],"description":"Cannot be undone. Its lines leave Your Prices and the file is removed.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The invoice.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"},"reversible":{"type":"boolean"},"files_removed":{"type":"boolean"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/costs/quote-requests":{"get":{"operationId":"listQuoteRequests","tags":["Costs"],"summary":"Your network price requests","security":[{"bearerKey":[]}],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","additionalProperties":true,"description":"id, category, quote_id, qty, unit, ship_to_market, status (requested, confirmed, declined, expired, or needs_review: a confirmed price tied to no item), confirmed_unit_price_cents, item_key, spec_version, invoice_line_id."}},"next_cursor":{"oneOf":[{"type":"string"},{"type":"null"}]},"total":{"type":"integer"}},"required":["items","next_cursor"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"requestNetworkPrice","tags":["Costs"],"summary":"Ask for the network price on an item","security":[{"bearerKey":[]}],"description":"Request the network price: CommerceBook confirms a price for the quantity and market. Verified members only. Name the item (item_key from GET /costs/prices, and invoice_line_id) so the confirmed price confirms that item only; a request without an item confirms nothing until you say which item it is for.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"quote_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"qty":{"type":"number","exclusiveMinimum":0},"unit":{"type":"string"},"ship_to_market":{"type":"string","description":"City, ST; your home market by default."},"item_key":{"type":"string","description":"The item of Your Prices (key_v2) the request is for."},"invoice_line_id":{"type":"string","format":"uuid"},"sources":{"type":"object","properties":{"qty":{"type":"string","maxLength":500},"unit":{"type":"string","maxLength":500},"ship_to_market":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): qty, unit, ship_to_market. Kept with the write on the owner's ledger."}},"required":["category","qty","unit"]}}}},"responses":{"201":{"description":"Requested","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"The request row, status requested."}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/costs/dismissals":{"post":{"operationId":"setCostDismissal","tags":["Costs"],"summary":"Hide a category from your savings for now, or show it again","security":[{"bearerKey":[]}],"description":"Not now (dismissed true) and Show again (false) on Your Prices.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"dismissed":{"type":"boolean"}},"required":["category","dismissed"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"category":{"type":"string"},"dismissed":{"type":"boolean"},"dismissed_categories":{"type":"array","items":{"type":"string"}}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/costs/rate-shop":{"get":{"operationId":"getRateShop","tags":["Costs"],"summary":"What the network pays for one item, whether or not you buy it","security":[{"bearerKey":[]}],"description":"Rate shop an item key (item_key from GET /costs/prices, or one built the same way: v3|<category>|<unit>|<field>=<value>;... with the category key spec fields and, for a price per case, box or pack, the pack count; a key_v2 is read too; a key short of a field has no network price). rate_shop: best_cents (the lowest other member newest price), lowest_cents, highest_cents, members (the other members behind the range), best_vendor (the vendor on the invoice of the best price), newest_at, your_position (low, middle, high; null when you do not buy the item); null when the network has no price (below the sample floor, or the comparison is off). No member is ever named.","parameters":[{"name":"item_key","in":"query","required":true,"schema":{"type":"string","description":"The item key (key_v3; a key_v2 is read too)."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"item_key":{"type":"string"},"category":{"oneOf":[{"type":"string"},{"type":"null"}]},"unit":{"oneOf":[{"type":"string"},{"type":"null"}]},"your_price_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"rate_shop":{"oneOf":[{"$ref":"#/components/schemas/RateShop"},{"type":"null"}]}}}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/costs/share-requests":{"get":{"operationId":"listShareRequests","tags":["Costs"],"summary":"Your Ask the Buyer to Share requests, sent and received","security":[{"bearerKey":[]}],"description":"sent: the requests you sent, with the outcome (requested, shared with the contact, pooled with the thread and the other company, declined, expired after 7 days). received: the requests other members sent you, anonymous until you answer Add to My Order. The same rows Purchases and Messages show.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"sent":{"type":"array","items":{"$ref":"#/components/schemas/ShareRequest"}},"received":{"type":"array","items":{"$ref":"#/components/schemas/ShareRequest"}}}}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createShareRequest","tags":["Costs"],"summary":"Ask the member behind the best network price to share","security":[{"bearerKey":[]}],"description":"One anonymous request to the member behind the best price for an item of Your Prices (item_key). They can share their vendor contact, add your order to their next purchase (a Messages thread opens with both company names) or say no thanks. One open request per item; the same member is asked about the same item at most once in 30 days (409 asked_recently); 409 not_cheaper when the best network price is not below yours. Verified members only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"item_key":{"type":"string"},"qty":{"type":"number","exclusiveMinimum":0,"description":"Your quantity; the quantity of your newest line by default."}},"required":["item_key"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareRequest"}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/costs/share-requests/{id}/answer":{"post":{"operationId":"answerShareRequest","tags":["Costs"],"summary":"Answer a request another member sent you","security":[{"bearerKey":[]}],"description":"answer share: vendor_name (your vendor for the item by default), rep_name, and an email or phone; the requester sees those and your price, nothing about you; the contact is remembered for that vendor. answer pool: handling_fee_cents (0 by default); a Messages thread opens between the two companies and a pooled order is recorded (no payment runs). answer decline: the requester reads only \"Not this time\".","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The request.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"answer":{"type":"string","enum":["share","pool","decline"]},"vendor_name":{"type":"string","maxLength":160},"rep_name":{"type":"string","maxLength":120},"email":{"type":"string","format":"email"},"phone":{"type":"string","maxLength":40},"handling_fee_cents":{"type":"integer","minimum":0}},"required":["answer"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShareRequest"}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/settings/preferences":{"get":{"operationId":"getPreferences","tags":["Settings"],"summary":"Your markets, service chips, notification email and CRM preference","security":[{"bearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Preferences"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updatePreferences","tags":["Settings"],"summary":"Change your markets, service chips, notification email or CRM preference","security":[{"bearerKey":[]}],"description":"The Warehouse preferences form, the named fields only: markets as City, ST (at least one), service chips, notification_email (empty clears it), crm_connection, crm_sharing (what the network sees of your CRM), wms_system and crm_system (the WMS and CRM you run: an option value or label from member_system_options, or your own words; null clears; a CRM with a live connector also sets crm_connection), other_systems (the systems you sell from).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"markets":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z][A-Za-z .'-]*, [A-Z]{2}$"},"minItems":1,"maxItems":30},"services":{"type":"array","items":{"type":"string"},"maxItems":30},"notification_email":{"oneOf":[{"type":"string","format":"email"},{"type":"null"}]},"crm_connection":{"type":"string","enum":["none","warebook","gohighlevel","hubspot"]},"crm_sharing":{"type":"string","enum":["hidden","counts","named"]},"wms_system":{"oneOf":[{"type":"string","maxLength":80},{"type":"null"}]},"crm_system":{"oneOf":[{"type":"string","maxLength":80},{"type":"null"}]},"other_systems":{"oneOf":[{"type":"array","items":{"type":"string","maxLength":80},"maxItems":20},{"type":"null"}]},"sources":{"type":"object","properties":{"markets":{"type":"string","maxLength":500},"services":{"type":"string","maxLength":500},"notification_email":{"type":"string","maxLength":500},"crm_connection":{"type":"string","maxLength":500},"crm_sharing":{"type":"string","maxLength":500},"wms_system":{"type":"string","maxLength":500},"crm_system":{"type":"string","maxLength":500},"other_systems":{"type":"string","maxLength":500}},"additionalProperties":false,"description":"Where each fact came from, one note per field written (a URL, a document, \"the owner said\"): markets, services, notification_email, crm_connection, crm_sharing, wms_system, crm_system, other_systems. Kept with the write on the owner's ledger."}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Preferences"}}}},"400":{"description":"invalid_input: a field is missing or out of range, or a file is not an accepted type; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level) or needs_approval (an area the owner marked on Agent access; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call; error carries the code (last_facility, facility_referenced, people_limit, video_limit, photo_limit, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/table":{"get":{"operationId":"listLeadsTable","tags":["Leads"],"summary":"Your Leads table: every open deal, shared or not","security":[{"bearerKey":[]}],"description":"The rows of the Leads screen, newest received first: one row per deal that is not archived, with the company (the deal title), when it was received, what we know (service, location and volume), the missing facts, the estimated value, the sharing state of its lead (not_shared, draft, shared, claimed, sold, withdrawn or expired) with the price, buyer places, claims and buyer companies, the one action the screen offers (pass, finish_draft, view_listing or post_again; pass is the Share button) and the share decision. tab not_shared (the default) holds deals never posted and drafts, less the ones set aside (Not for the network, share_decision decline; set_aside=true lists them); tab shared holds the rest. counts gives both tabs, set_aside and deleted under the same filters. To share a row, POST /leads with its deal_id.","parameters":[{"name":"tab","in":"query","schema":{"type":"string","enum":["not_shared","shared"],"default":"not_shared"}},{"name":"q","in":"query","schema":{"type":"string","description":"Part of the company name."}},{"name":"missing","in":"query","schema":{"type":"boolean","description":"true: only rows missing a service or a location."}},{"name":"source","in":"query","schema":{"type":"string","description":"Where the deal came from.","enum":["ghl","csv","typed","agent"]}},{"name":"marked","in":"query","schema":{"type":"boolean","description":"true: only rows marked to share."}},{"name":"set_aside","in":"query","schema":{"type":"boolean","description":"true: only the Not shared rows set aside (Not for the network, share_decision decline). Without it the Not shared tab leaves them out."}},{"name":"deleted","in":"query","schema":{"type":"boolean","description":"true: only the GoHighLevel rows deleted from the list (hidden and archived), both tabs."}},{"name":"cursor","in":"query","schema":{"type":"string","description":"The next_cursor of the previous page."}},{"name":"limit","in":"query","schema":{"type":"integer","description":"Rows per page, 1 to 200.","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"deal_id":{"type":"string","format":"uuid"},"company":{"type":"string"},"company_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"received_at":{"type":"string"},"source":{"type":"string","enum":["ghl","csv","typed","agent"]},"stage":{"type":"string"},"estimated_value_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"what_we_know":{"type":"object","properties":{"service":{"oneOf":[{"type":"object","properties":{"value":{"type":"string"},"status":{"type":"string","description":"record (typed on the deal), confirmed or suggested (a fact read from the notes)."},"fact_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]}}},{"type":"null"}]},"location":{"oneOf":[{"type":"object","properties":{"value":{"type":"string"},"status":{"type":"string","description":"record (typed on the deal), confirmed or suggested (a fact read from the notes)."},"fact_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]}}},{"type":"null"}]},"volume":{"oneOf":[{"type":"object","properties":{"value":{"type":"string"},"status":{"type":"string","description":"record (typed on the deal), confirmed or suggested (a fact read from the notes)."},"fact_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]}}},{"type":"null"}]}}},"missing":{"type":"array","items":{"type":"string","enum":["service","location"]}},"tab":{"type":"string"},"state":{"type":"string","enum":["not_shared","draft","shared","claimed","sold","withdrawn","expired"]},"action":{"type":"string","enum":["pass","finish_draft","view_listing","post_again"]},"lead_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lead_status":{"oneOf":[{"type":"string"},{"type":"null"}]},"shared_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"price_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"price_pct":{"oneOf":[{"type":"number"},{"type":"null"}]},"terms":{"oneOf":[{"type":"string"},{"type":"null"}]},"max_buyers":{"oneOf":[{"type":"integer"},{"type":"null"}]},"claims_count":{"type":"integer"},"claimed_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"buyers":{"type":"array","items":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"claimed_at":{"type":"string"}}}},"share_decision":{"type":"string","enum":["none","share","hold","decline"]},"decided_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"decided_by":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"decided_by_name":{"oneOf":[{"type":"string","description":"Who decided, by display name."},{"type":"null"}]},"set_aside":{"type":"boolean","description":"Not for the network: under the Set aside filter."},"deleted":{"type":"boolean","description":"A GoHighLevel row deleted from the list."}},"required":["deal_id","company","received_at","state","action","share_decision"]}},"next_cursor":{"oneOf":[{"type":"string"},{"type":"null"}]},"counts":{"type":"object","properties":{"not_shared":{"type":"integer"},"shared":{"type":"integer"},"set_aside":{"type":"integer"},"deleted":{"type":"integer"}}}},"required":["items","next_cursor","counts"]}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/crm/deals/{id}/share-decision":{"patch":{"operationId":"setDealShareDecision","tags":["CRM"],"summary":"Mark a deal to share, hold or decline","security":[{"bearerKey":[]}],"description":"The decision on a Leads row: decline is Not for the network (the row moves under Set aside), none is Reconsider (back in Not shared); share is Marked to share and hold is On hold, both chips on the row. Kept with the time and who decided. share does not post the lead; the row stays in Not shared with Marked to share until it is posted (POST /leads with deal_id).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The deal.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["none","share","hold","decline"]}},"required":["decision"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deal_id":{"type":"string","format":"uuid"},"share_decision":{"type":"string"},"decided_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"decided_by":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/settings/lead-defaults":{"get":{"operationId":"getLeadDefaults","tags":["Settings"],"summary":"Your Lead defaults","security":[{"bearerKey":[]}],"description":"The price and buyer places a Pass to network sheet opens with, and whether it offers Pass for $1. POST /leads without a price uses them too. $20, open to 2 buyers, until you save your own.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"price_cents":{"type":"integer","description":"The price a Pass to network sheet opens with, in cents."},"max_buyers":{"type":"integer","description":"The buyer places it opens with, 1 to 5."},"dollar_preset":{"type":"boolean","description":"true: the sheet offers Pass for $1."},"saved":{"type":"boolean","description":"false until the member saves its own numbers."},"updated_at":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["price_cents","max_buyers","dollar_preset","saved"]}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"setLeadDefaults","tags":["Settings"],"summary":"Change your Lead defaults","security":[{"bearerKey":[]}],"description":"The named fields only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"price_cents":{"type":"integer","minimum":0,"maximum":100000000},"max_buyers":{"type":"integer","minimum":1,"maximum":5},"dollar_preset":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"price_cents":{"type":"integer","description":"The price a Pass to network sheet opens with, in cents."},"max_buyers":{"type":"integer","description":"The buyer places it opens with, 1 to 5."},"dollar_preset":{"type":"boolean","description":"true: the sheet offers Pass for $1."},"saved":{"type":"boolean","description":"false until the member saves its own numbers."},"updated_at":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["price_cents","max_buyers","dollar_preset","saved"]}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the permission; detail is domain:level).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/shipping/profiles":{"get":{"operationId":"sellerShippingProfiles","tags":["Shipping"],"summary":"Your shipping profiles, the default and the regions you serve","security":[{"bearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingProfiles"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example policies:write).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (profile_is_default, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"sellerShippingProfileCreate","tags":["Shipping"],"summary":"Create a shipping profile (rules not listed for standard are not served)","security":[{"bearerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingProfileInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingProfile"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example policies:write).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (profile_is_default, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/shipping/profiles/{id}":{"patch":{"operationId":"sellerShippingProfileUpdate","tags":["Shipping"],"summary":"Change a profile; rules replace its rules","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The profile.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingProfileInput"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingProfile"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example policies:write).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (profile_is_default, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"sellerShippingProfileDelete","tags":["Shipping"],"summary":"Delete a profile that is not the default; its offers use the default","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The profile.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"profile_id":{"type":"string","format":"uuid"},"offers_moved_to_default":{"type":"integer"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example policies:write).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (profile_is_default, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/shipping/profiles/{id}/delete":{"post":{"operationId":"sellerShippingProfileDeletePost","tags":["Shipping"],"summary":"The same delete for clients without DELETE","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The profile.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"profile_id":{"type":"string","format":"uuid"},"offers_moved_to_default":{"type":"integer"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example policies:write).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (profile_is_default, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/shipping/profiles/{id}/default":{"post":{"operationId":"sellerShippingProfileSetDefault","tags":["Shipping"],"summary":"Make this profile the default","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The profile.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingProfile"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example policies:write).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (profile_is_default, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/shipping/assign":{"post":{"operationId":"sellerShippingAssign","tags":["Shipping"],"summary":"Assign a profile to offers or to the open offers of products (lot_ids; profile_id null: back to the default)","security":[{"bearerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profile_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"offer_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"lot_ids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["profile_id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"profile_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"assigned":{"type":"integer"},"ships_to":{"type":"array","items":{"type":"string","enum":["continental_us","alaska_hawaii","us_territories","military","canada","international"]}}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example policies:write).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (profile_is_default, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/shipping/rate-card":{"post":{"operationId":"sellerShippingRateCard","tags":["Shipping"],"summary":"Upload a rate card for your origin (the rates.json shape: zones_by_zip3, services[].weight_lbs_to_rates)","security":[{"bearerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"origin_zip3":{"type":"string","pattern":"^[0-9]{3}$"},"card":{"type":"object","additionalProperties":true},"label":{"type":"string"},"facility_id":{"type":"string","format":"uuid"}},"required":["origin_zip3","card"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"rate_card_id":{"type":"string","format":"uuid"},"origin_zip3":{"type":"string"},"services":{"type":"integer"},"zip3_zones":{"type":"integer"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example policies:write).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (profile_is_default, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/orders/{id}/shipping-actual":{"post":{"operationId":"sellerOrderShippingActual","tags":["Shipping"],"summary":"Record the label cost of a shipped order (the statement shows shipping quote vs actual)","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The order.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shipping_actual_cents":{"type":"integer"},"source":{"type":"string","enum":["label","rocketfuel","carrier_invoice","manual"]}},"required":["shipping_actual_cents"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"shipping_cents":{"type":"integer"},"shipping_actual_cents":{"type":"integer"},"shipping_delta_cents":{"type":"integer"}},"additionalProperties":true}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example policies:write).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (profile_is_default, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shipping/quote":{"post":{"operationId":"shippingQuote","tags":["Shipping"],"summary":"Shipping for an offer to a destination: the seller profile answers, a calculated rule rates the parcel","security":[{"bearerKey":[]}],"description":"Any CommerceBook key or a signed-in member session token. destination is a state or territory code, US-TX, a ZIP, an address line, or an object {country, state, zip, residential}. service defaults to standard; expedited not offered falls back to standard. The answer also carries the goods at that quantity (unit_price_cents, goods_cents, total_cents), the processing line and the buyer total by payment method, and requested and available: ok is false with reason quantity (and code insufficient_quantity, error_code item_out_of_stock) when the quantity is more than the offer can sell.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"qty":{"type":"integer","minimum":1},"service":{"type":"string","enum":["standard","expedited"]},"destination":{"oneOf":[{"type":"string","description":"TX, US-TX, 77043, or an address line."},{"type":"object","properties":{"country":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"postal_code":{"type":"string"},"line1":{"type":"string"},"residential":{"type":"boolean"},"label":{"type":"string"}}}]}},"required":["offer_id","destination"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingQuote"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the permission; detail is domain:level (for example policies:write).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the app refused the call (profile_is_default, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/catalog/import":{"post":{"operationId":"sellerCatalogImport","tags":["Seller"],"summary":"Import a catalog file or a feed URL: Google Shopping XML or TSV, Shopify CSV, eBay Seller Hub CSV, products JSON","security":[{"bearerKey":[]}],"description":"One of url, content or content_base64 (JSON), or multipart/form-data with a file part. The kind is read from the content. Limits: 5,000 rows, 10 MB, 20 seconds; past a limit the import stops and stopped names it. The key of a seller or a signed-in seller session.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"A feed address (http or https) to fetch now."},"content":{"type":"string","description":"The file text (CSV, TSV, XML or JSON)."},"content_base64":{"type":"string","description":"The file bytes in base64."},"file_name":{"type":"string","description":"The file name the import is recorded under."},"kind":{"type":"string","enum":["google_rss","google_tsv","shopify_csv","ebay_csv","acp_json","template_csv","template_json"]},"dry_run":{"type":"boolean","description":"true: preview only, nothing written. Default false."},"default_quantity":{"oneOf":[{"type":"integer","description":"The quantity for rows that carry none.","minimum":0},{"type":"null"}]},"schedule":{"type":"string","enum":["none","hourly","daily"]},"operation_id":{"type":"string","description":"The idempotency key of the write."}}}},"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","description":"The file.","format":"binary"},"dry_run":{"type":"string"},"kind":{"type":"string","enum":["google_rss","google_tsv","shopify_csv","ebay_csv","acp_json","template_csv","template_json"]},"default_quantity":{"type":"string"}},"required":["file"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogImportResult"}}}},"400":{"description":"invalid_input, invalid_body, kind_unknown (not a format CommerceBook reads), no_rows, unreadable, url_not_allowed (a private address).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks catalog:read or catalog:write, or the member is not a seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the feed is not yours, or the key of a warehouse.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the writer refused the call (operation_conflict, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"too_large: the file or the feed is larger than 10 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"fetch_failed: the feed server could not be reached or answered with an error; detail says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"timeout: the feed took longer than 20 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/catalog/feeds":{"get":{"operationId":"sellerCatalogFeeds","tags":["Seller"],"summary":"Your saved feeds with the last fetch, status, counts and the last five runs","security":[{"bearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CatalogFeed"}},"next_cursor":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["items"]}}}},"400":{"description":"invalid_input, invalid_body, kind_unknown (not a format CommerceBook reads), no_rows, unreadable, url_not_allowed (a private address).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks catalog:read or catalog:write, or the member is not a seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the feed is not yours, or the key of a warehouse.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the writer refused the call (operation_conflict, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"sellerCatalogFeedAdd","tags":["Seller"],"summary":"Save a feed URL with its schedule (none, hourly, daily); the kind is read from the feed when not given","security":[{"bearerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"kind":{"type":"string","enum":["google_rss","google_tsv","shopify_csv","ebay_csv","acp_json","template_csv","template_json"]},"schedule":{"type":"string","enum":["none","hourly","daily"]},"default_quantity":{"oneOf":[{"type":"integer"},{"type":"null"}]}},"required":["url"]}}}},"responses":{"201":{"description":"Saved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogFeed"}}}},"400":{"description":"invalid_input, invalid_body, kind_unknown (not a format CommerceBook reads), no_rows, unreadable, url_not_allowed (a private address).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks catalog:read or catalog:write, or the member is not a seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the feed is not yours, or the key of a warehouse.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the writer refused the call (operation_conflict, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"fetch_failed: the feed server could not be reached or answered with an error; detail says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"timeout: the feed took longer than 20 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/catalog/feeds/{id}/fetch":{"post":{"operationId":"sellerCatalogFeedFetch","tags":["Seller"],"summary":"Fetch a saved feed now and import it (a run record when it writes)","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The feed.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"dry_run":{"type":"boolean"},"operation_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogImportResult"}}}},"400":{"description":"invalid_input, invalid_body, kind_unknown (not a format CommerceBook reads), no_rows, unreadable, url_not_allowed (a private address).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks catalog:read or catalog:write, or the member is not a seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the feed is not yours, or the key of a warehouse.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the writer refused the call (operation_conflict, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"too_large: the file or the feed is larger than 10 MB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"fetch_failed: the feed server could not be reached or answered with an error; detail says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"timeout: the feed took longer than 20 seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/catalog/feeds/{id}":{"delete":{"operationId":"sellerCatalogFeedRemove","tags":["Seller"],"summary":"Remove a saved feed and its runs (the products it loaded stay)","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The feed.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"},"feed_id":{"type":"string","format":"uuid"}},"required":["deleted","feed_id"]}}}},"400":{"description":"invalid_input, invalid_body, kind_unknown (not a format CommerceBook reads), no_rows, unreadable, url_not_allowed (a private address).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks catalog:read or catalog:write, or the member is not a seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the feed is not yours, or the key of a warehouse.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule of the writer refused the call (operation_conflict, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/crm/deals/{id}/facts":{"get":{"operationId":"listDealFacts","tags":["CRM"],"summary":"The facts read from a deal’s notes, with their source sentences","security":[{"bearerKey":[]}],"description":"Every fact of the deal: suggested (read by the rules, not yet decided), confirmed and rejected. Each carries the sentence it came from. ready is true when the five Post fields are confirmed; missing lists the Post fields with no suggested or confirmed fact.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The deal.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DealFacts"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks crm:read or crm:write) or needs_approval (the owner holds CRM writes for approval; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the deal or the fact is not yours, or the key of a seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/crm/deals/{id}/facts/{fact_id}/decide":{"post":{"operationId":"decideDealFact","tags":["CRM"],"summary":"Confirm or reject one fact","security":[{"bearerKey":[]}],"description":"confirmed writes the deal: service sets the deal’s service, location its target market (anywhere writes nothing), and volume, SKU count, product and timing fill the attribute key the deal does not hold yet (outbound.monthly_orders, receiving.pallets_inbound_month, outbound.monthly_pallets, business.total_skus, business.product_description, timing.start_date). wrote says what changed. rejected hides the fact and keeps it, so the same sentence is not suggested again.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The deal.","format":"uuid"}},{"name":"fact_id","in":"path","required":true,"schema":{"type":"string","description":"The fact.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["confirmed","rejected"]}},"required":["status"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"fact":{"$ref":"#/components/schemas/DealFact"},"already":{"type":"boolean","description":"The fact already had this status."},"wrote":{"type":"object","additionalProperties":true}},"required":["fact","already","wrote"]}}}},"400":{"description":"invalid_input or invalid_body: the status is not confirmed or rejected, or the body is not empty JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks crm:read or crm:write) or needs_approval (the owner holds CRM writes for approval; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the deal or the fact is not yours, or the key of a seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/crm/deals/{id}/facts/extract":{"post":{"operationId":"extractDealFacts","tags":["CRM"],"summary":"Read the deal’s notes again for facts","security":[{"bearerKey":[]}],"description":"Runs the hand rules (no model) over the deal’s notes, description, CRM notes and GoHighLevel fields and writes the suggestions. A suggestion whose sentence is gone is replaced; a confirmed or rejected fact is never changed. The answer has the counts and the deal’s facts.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The deal.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"deal_id":{"type":"string","format":"uuid"},"found":{"type":"object","properties":{"service":{"type":"integer"},"location":{"type":"integer"},"volume":{"type":"integer"},"product":{"type":"integer"},"timing":{"type":"integer"},"sku_count":{"type":"integer"}}},"written":{"type":"object","properties":{"inserted":{"type":"integer"},"updated":{"type":"integer"},"unchanged":{"type":"integer"},"decided_kept":{"type":"integer"},"superseded":{"type":"integer"},"refused":{"type":"integer"}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/DealFact"}},"ready":{"type":"boolean"},"missing":{"type":"array","items":{"type":"string","enum":["service","location","volume","product","timing"]}}},"required":["deal_id","found","written","items"]}}}},"400":{"description":"invalid_input or invalid_body: the status is not confirmed or rejected, or the body is not empty JSON.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks crm:read or crm:write) or needs_approval (the owner holds CRM writes for approval; approval_id names the item).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the deal or the fact is not yours, or the key of a seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads/intake":{"post":{"operationId":"leadIntake","tags":["Leads"],"summary":"Make a draft lead from an email or a note","description":"The reader behind leads@commercebook.ai, for an agent with the member’s key (leads write). Send the text of a forwarded email or a note. CommerceBook removes signatures, disclaimers and quoted history, reads the rest with Google’s Gemini service, checks the CRM (a do-not-solicit, won or lost deal refuses the lead) and the last 90 days (the same prospect is reported, not posted again), makes or links the row in Leads (source email) and, when the company, the need, the service, the location and a price are known, a draft lead. A price in the subject or first line (\"$500 flat, exclusive\", \"15%\") is used for this lead only; otherwise the saved Lead defaults; otherwise price is in needed. The draft is never listed by this call: list it with POST /leads (replace_draft: the lead_id) or on the Post page. A seller key is refused.","security":[{"bearerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","description":"The email or note, as plain text. Up to 50,000 characters."},"subject":{"type":"string","description":"The subject line, when there is one."},"from_name":{"type":"string","description":"The name of the person forwarding, when known."}},"required":["text"],"additionalProperties":false}}}},"responses":{"200":{"description":"The row in Leads and the draft, with what is still needed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LeadIntake"}}}},"400":{"description":"invalid_input or invalid_body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (a seller key, or a key without leads write) or needs_approval.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"too_little_text: fewer than 20 words of lead after cleaning.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"model_error, model_bad_response, model_empty or model_bad_json: the reader could not read the text. Nothing was made.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"model_timeout or model_unreachable. Nothing was made; try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys/{id}/limits":{"get":{"operationId":"getKeyLimits","tags":["Account"],"summary":"The limits on a key","security":[{"bearerKey":[]}],"description":"The spending cap per 30 days, the amount above which a payment waits for the owner, the actions the owner confirms, the calls per hour, what the key spent in 30 days and how many of its actions wait. Any key of the member may read any of the member’s keys.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The key (the key_id of GET /me or of a key listed at Agent access).","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyLimits"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (only an agent link key or the owner signed in changes limits or decides) or owner_in_person (raising a limit or approving needs the owner signed in at Agent access).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the key or the waiting action is not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setKeyLimits","tags":["Account"],"summary":"Change the limits on a key","security":[{"bearerKey":[]}],"description":"Fields left out keep their value. An agent link key may only lower limits (a smaller cap or confirm amount, more confirm actions, fewer calls per hour); raising a limit answers 403 owner_in_person and is done by the owner signed in at Agent access.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The key (the key_id of GET /me or of a key listed at Agent access).","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"spend_cap_cents":{"oneOf":[{"type":"integer","description":"null removes the cap.","minimum":0},{"type":"null"}]},"confirm_above_cents":{"oneOf":[{"type":"integer","description":"null removes the confirm amount.","minimum":0},{"type":"null"}]},"confirm_actions":{"type":"array","items":{"type":"string","enum":["lead_post","message_new_member","capacity_quote","order_accept"]}},"rate_per_hour":{"type":"integer","minimum":1,"maximum":600}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyLimits"}}}},"400":{"description":"invalid_input or invalid_body: a field is out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (only an agent link key or the owner signed in changes limits or decides) or owner_in_person (raising a limit or approving needs the owner signed in at Agent access).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the key or the waiting action is not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"pending_state: the action was already decided; key_revoked: the key was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys/{id}/pending":{"get":{"operationId":"listPendingActions","tags":["Account"],"summary":"The actions that wait for the owner","security":[{"bearerKey":[]}],"description":"A call over the key’s limits is not executed: it answers 202 pending_owner_confirmation and waits here until the owner approves or declines it. An approved action runs once with the arguments it was sent with; status and result show what happened.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The key (the key_id of GET /me or of a key listed at Agent access).","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","running","done","failed","declined","all"],"default":"pending"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PendingAction"}}},"required":["items"]}}}},"400":{"description":"invalid_input or invalid_body: a field is out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (only an agent link key or the owner signed in changes limits or decides) or owner_in_person (raising a limit or approving needs the owner signed in at Agent access).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the key or the waiting action is not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys/{id}/pending/{pending_id}/decide":{"post":{"operationId":"decidePendingAction","tags":["Account"],"summary":"Approve or decline a waiting action","security":[{"bearerKey":[]}],"description":"decline drops it and runs nothing; an agent link key may decline its own waiting actions. approve needs the owner signed in (403 owner_in_person for a key) and runs the action once through the endpoint it came in by; run is that endpoint’s answer.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The key (the key_id of GET /me or of a key listed at Agent access).","format":"uuid"}},{"name":"pending_id","in":"path","required":true,"schema":{"type":"string","description":"The waiting action.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["approve","decline"]}},"required":["decision"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"pending":{"$ref":"#/components/schemas/PendingAction"},"run":{"oneOf":[{"type":"object","properties":{"status":{"type":"integer"},"body":{"type":"object","additionalProperties":true}}},{"type":"null"}]}},"required":["pending","run"]}}}},"400":{"description":"invalid_input or invalid_body: a field is out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (only an agent link key or the owner signed in changes limits or decides) or owner_in_person (raising a limit or approving needs the owner signed in at Agent access).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the key or the waiting action is not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"pending_state: the action was already decided; key_revoked: the key was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keys/{id}/permissions":{"get":{"operationId":"getKeyPermissions","tags":["Account"],"summary":"What a key may do","security":[{"bearerKey":[]}],"description":"Every key starts read-only on every activity, payments off. The owner turns an activity on (Can act) at Agent access; until then a call that acts answers 403 not_permitted with activity and hint. After the owner turns an activity on, the next call succeeds without a new key. Any key of the member may read any of the member’s keys.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The key (the key_id of GET /me or of a key listed at Agent access).","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyPermissions"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (only an agent link key or the owner signed in changes limits or decides) or owner_in_person (raising a limit or approving needs the owner signed in at Agent access).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the key or the waiting action is not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setKeyPermissions","tags":["Account"],"summary":"Lower what a key may do","security":[{"bearerKey":[]}],"description":"activities names the activities to change (none, read or write); the others keep their level. A key may only lower its own: write to read, read to none, payments write to none. Turning an activity on answers 403 owner_in_person; the owner turns it on signed in.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The key (the key_id of GET /me or of a key listed at Agent access).","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"activities":{"type":"object","additionalProperties":{"type":"string","enum":["none","read","write"]},"description":"For example {\"payments\": \"none\", \"leads\": \"read\"}."}},"required":["activities"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyPermissions"}}}},"400":{"description":"invalid_input or invalid_body: a field is out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (only an agent link key or the owner signed in changes limits or decides) or owner_in_person (raising a limit or approving needs the owner signed in at Agent access).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the key or the waiting action is not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"pending_state: the action was already decided; key_revoked: the key was revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/network/now":{"get":{"operationId":"networkNow","tags":["Network"],"summary":"The network’s live numbers (no key)","security":[],"description":"Verified members, leads listed in the last 7 days, prices posted and savings confirmed this month: the line at the top of /for-agents and https://commercebook.ai/docs/agent-briefing.md. Cached 15 minutes.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NetworkNow"}}}},"503":{"description":"not_available: the numbers could not be read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/costs/savings":{"get":{"operationId":"costSavings","tags":["Costs"],"summary":"The member’s confirmed savings","security":[{"bearerKey":[]}],"description":"One row per confirmed saving: a supplier price confirmed on a network price request, or a vendor match recorded. saving_cents is (your price minus the confirmed price) times the annual quantity; year_cents and month_cents are the Central-time calendar year and month. Needs costs read.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CostSavings"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (only an agent link key or the owner signed in changes limits or decides) or owner_in_person (raising a limit or approving needs the owner signed in at Agent access).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/":{"get":{"operationId":"listEndpoints","tags":["Account"],"summary":"The endpoint list","description":"Without a key: the keyed endpoints, the endpoints that take no key and the MCP server address. With a key: the endpoints that key’s member kind reaches (the key of a seller reaches no warehouse endpoint, and the reverse), with kind.","security":[{},{"bearerKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"openapi":{"type":"string"},"mcp":{"type":"string"},"kind":{"type":"string","enum":["warehouse","seller","buyer"]},"endpoints":{"type":"array","items":{"type":"string"}},"keyless":{"type":"array","items":{"type":"string"}}},"required":["endpoints"]}}}},"401":{"description":"key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/signup/start":{"post":{"operationId":"signupStart","tags":["Account"],"summary":"Open an account (an agent asks; no key)","description":"An agent can open an account; the owner confirms by email code; selling and buying with money still need the owner’s Stripe steps. Sends the owner one email with an 8-digit code and no link. The code lives 30 minutes; three starts per email per day; a new start replaces an open one. The answer is the same whether or not the email has an account. A warehouse needs its company and street address (address, with city and state when known), a seller its company; a buyer (kind buyer, a Shop account) needs neither, and its company is optional. Every key starts read-only; the owner turns activities on at Agent access. Without a key, 60 calls a minute and 1,200 an hour per client address; with a key, 600 calls an hour.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","description":"The owner’s email; the code goes there.","format":"email"},"kind":{"type":"string","enum":["warehouse","seller","buyer"]},"company":{"type":"string","description":"The business name. Optional for a buyer.","maxLength":200},"contact_name":{"type":"string","description":"The owner’s name.","maxLength":120},"address":{"type":"string","description":"A warehouse: the street address of the first facility.","maxLength":400},"city":{"type":"string"},"state":{"type":"string","description":"Two letters."},"services":{"type":"array","items":{"type":"string"}},"sqft":{"type":"integer","minimum":0}},"required":["email","kind","contact_name"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupStarted"}}}},"400":{"description":"invalid_input: detail names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: three starts per email per day, or 60 calls a minute and 1,200 an hour per address (retry_after_seconds and window in the body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/signup/confirm":{"post":{"operationId":"signupConfirm","tags":["Account"],"summary":"Confirm the account with the owner’s code (no key)","description":"The email and the 8-digit code the owner read in the email. Makes the login when the email has none (an existing login is used as it is, and its password never changes), the member of the kind with the same rows the sign-up form makes (a seller gets its business details row with the questionnaire fields empty, filled afterwards with PATCH /seller/entity), and an agent link with the default limits ($500 per 30 days, confirm above $250). Answers the key once, the link and the member’s document. The owner later signs in with the email code and sees the link on Agent access, marked opened by an agent. Five wrong codes end the start.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"code":{"type":"string","description":"Eight digits.","pattern":"^\\d{8}$"}},"required":["email","code"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignupConfirmed"}}}},"400":{"description":"invalid_input, or code_wrong (detail says when the start has ended).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no sign-up waits for this email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"already_has_account: the email already has an account of this kind; its owner issues an agent link from Agent access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"code_expired: start again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 60 calls a minute and 1,200 an hour per address without a key (retry_after_seconds and window in the body).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/feedback":{"post":{"operationId":"sendFeedback","tags":["Account"],"summary":"Tell CommerceBook what would help (a key or none)","description":"A note on a tool or a page: what happened and what would have helped, with an optional rating from 1 to 5. A person at CommerceBook reads every note on the console screen Agent feedback, and the What is coming list of the briefings is shaped by them; nothing acts on a note by itself. With no key: 20 notes per client address per day, recorded as kind buyer. With a key: recorded against the key and its member, with a row on the owner’s ledger.","security":[{},{"bearerKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"about":{"type":"string","description":"A tool name (commercebook_buy action shipping_quote) or a page (/feeds).","maxLength":200},"what_happened":{"type":"string","maxLength":4000},"what_would_help":{"type":"string","maxLength":4000},"rating":{"type":"integer","description":"1 to 5.","minimum":1,"maximum":5}},"required":["about"],"additionalProperties":false,"description":"about, and what_happened or what_would_help."}}}},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackRecorded"}}}},"400":{"description":"invalid_input: detail names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_unknown, key_revoked or key_expired (a key was sent).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 20 notes per address per day without a key, or the key’s calls per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/payment-methods":{"get":{"operationId":"listPaymentMethods","tags":["Payments"],"summary":"The saved cards and the balance","security":[{"bearerKey":[]}],"description":"The cards the owner saved at Settings, Payment methods (brand, last four, expiry, which is the default) and the balance. Any key reads it; a key never adds or removes a card.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentMethods"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/payment-methods/{id}":{"delete":{"operationId":"removePaymentMethod","tags":["Payments"],"summary":"Remove a saved card (owner only)","security":[{"bearerKey":[]}],"description":"Always 403 owner_only for a key: the owner removes a card at Settings, Payment methods. A key without the payments activity answers 403 not_permitted first.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The saved card (GET /me/payment-methods).","format":"uuid"}}],"responses":{"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the activity; activity and hint name it) or owner_only (the owner does this at Settings).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/balance":{"get":{"operationId":"getBalance","tags":["Payments"],"summary":"The balance","security":[{"bearerKey":[]}],"description":"The member’s CommerceBook balance, held by Stripe as its customer cash balance: available now (read from Stripe), the recent balance events, an open return to the bank, and the funding instructions once asked for (POST /me/balance/funding-instructions). Funding is by the owner’s own ACH (1 to 3 business days) or wire (same day) to those instructions; a card cannot fund it. Unused balance returns to the sender’s bank after 75 days. Any key.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"stripe_error: Stripe could not be reached or refused; detail is Stripe’s code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/balance/funding-instructions":{"post":{"operationId":"balanceFundingInstructions","tags":["Payments"],"summary":"The funding instructions of the balance","security":[{"bearerKey":[]}],"description":"Routing number, account number, account holder and bank for the owner’s ACH or wire to the balance. Creates the Stripe Customer the first time; asking again answers the same instructions. Moves no money. Any key.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balance"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"stripe_error: Stripe could not be reached or refused; detail is Stripe’s code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"payments_not_configured: the deployment has no Stripe keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/balance/return":{"post":{"operationId":"balanceReturn","tags":["Payments"],"summary":"Return the balance to the bank","security":[{"bearerKey":[]}],"description":"Returns the balance (or amount_cents of it) to the owner’s bank: Stripe emails the notification email for the account details and the money goes once they are given (45 days). One return at a time. Needs the payments activity.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"amount_cents":{"type":"integer","description":"Default: everything available.","minimum":1}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceReturn"}}}},"400":{"description":"invalid_input: a field is out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted (the key lacks the activity; activity and hint name it) or owner_only (the owner does this at Settings).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"nothing_to_return, return_open (one return at a time).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"stripe_error: Stripe could not be reached or refused; detail is Stripe’s code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"payments_not_configured: the deployment has no Stripe keys.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/search":{"get":{"operationId":"marketSearch","tags":["Market"],"summary":"Search the market","security":[{},{"bearerKey":[]}],"description":"The products for sale on the market, sorted by relevance then price. Words match the title, the category (its key, its name and its synonyms), the item specifics, the brand and the part number; the description adds to the score and never makes a hit alone. Each item names its matched_fields and matched_terms (how many words of the query it matches), and a product sold in packs carries pack_size and price_text per pack; a query whose words match nothing answers no items, no_match true and nearest_categories with their counts. No key needed (60 calls a minute and 1,200 an hour per address); with a key the call is on the owner’s ledger.","parameters":[{"name":"q","in":"query","schema":{"type":"string","description":"Words; a product matches any meaningful word as a whole word of the title, the category, the specifics, the brand or the part number (a plural ending s or es matches too, so stretch matches stretch and stretches, never stretcher), and the products that match more words rank first."}},{"name":"query","in":"query","schema":{"type":"string","description":"The same as q."}},{"name":"category","in":"query","schema":{"type":"string","description":"A category key, exact (for example packaging, tools, home_garden, office_supplies). GET /market/book lists every category with its products and open requests."}},{"name":"min_price","in":"query","schema":{"type":"integer","description":"Cents per unit.","minimum":0}},{"name":"max_price","in":"query","schema":{"type":"integer","description":"Cents per unit.","minimum":0}},{"name":"state","in":"query","schema":{"type":"string","description":"Two-letter state the goods ship to.","pattern":"^[A-Za-z]{2}$"}},{"name":"condition","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","description":"20 by default, at most 100.","minimum":1,"maximum":100}},{"name":"goods_kind","in":"query","schema":{"type":"string","description":"new, used or surplus.","enum":["new","used","surplus"]}},{"name":"zip","in":"query","schema":{"type":"string","description":"The buyer’s five-digit ZIP: each item carries to_zip, its shipping to it.","pattern":"^\\d{5}(-\\d{4})?$"}},{"name":"sort","in":"query","schema":{"type":"string","description":"relevance (the default) or delivered: the unit price plus the shipping to zip, lowest first. Needs zip.","enum":["relevance","delivered"]}},{"name":"max_delivered","in":"query","schema":{"type":"integer","description":"Ships to zip for at most this many cents, price plus shipping. Needs zip.","minimum":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketSearch"}}}},"400":{"description":"invalid_input: a field is out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/lots/{id}":{"get":{"operationId":"marketLot","tags":["Market"],"summary":"One public product","security":[{},{"bearerKey":[]}],"description":"The product page JSON with every active offer of the product and the states it ships to. No key needed.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The product (lot_id of a search item).","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketLot"}}}},"404":{"description":"not_found: the product (lot_id), the seller (slug), the quote or the order is not there or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/sellers/{slug}":{"get":{"operationId":"marketSeller","tags":["Market"],"summary":"One seller record","security":[{},{"bearerKey":[]}],"description":"The record CommerceBook computes for a seller from its orders, deliveries, disputes and ratings: identity, the live products, the last 90 days and all time (each figure with n, of, rate and shown_as by the count rule), the ratings kept apart (confirmed at delivery, rated by shoppers), the tier, and the terms a buyer accepts. The seller writes none of it. The same record is the page https://commercebook.ai/sellers/{slug} and the markdown https://commercebook.ai/docs/seller/{slug}.md. No key needed.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","description":"The seller_slug of a search item or a product."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerRecord"}}}},"404":{"description":"not_found: the product (lot_id), the seller (slug), the quote or the order is not there or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/quotes":{"post":{"operationId":"marketQuote","tags":["Market"],"summary":"Quote an offer","security":[{"bearerKey":[]}],"description":"market_quote_create(): the price at the quantity with shipping from the seller’s profile (method ship with a destination: a state, a ZIP, an address line or {state, zip, residential, service, rate_id}) or pickup. The goods are held for 15 minutes. Needs orders write (the key of a buyer or a seller) or payments write (the key of a warehouse).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1},"method":{"type":"string","enum":["pickup","ship"]},"destination":{"oneOf":[{"type":"string"},{"type":"object","properties":{"state":{"type":"string"},"zip":{"type":"string"},"residential":{"type":"boolean"},"service":{"type":"string","enum":["standard","expedited"]},"rate_id":{"type":"string"}}}]},"operation_id":{"type":"string","description":"Idempotency key; the request id by default.","minLength":8,"maxLength":96}},"required":["offer_id","quantity"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketQuote"}}}},"400":{"description":"invalid_input: a field is out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders, or payments to place an order; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the product (lot_id), the seller (slug), the quote or the order is not there or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The state refuses it: offer_unavailable, insufficient_quantity, quote_state, quote_expired, order_state, dispute_open, seller_not_connected, no_payment_method (hint), balance_insufficient (shortfall_cents), payment_needs_owner, card_declined. error_code carries the shared buyer code where one applies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/orders":{"post":{"operationId":"marketOrderPlace","tags":["Market"],"summary":"Place and pay an order","security":[{"bearerKey":[]}],"description":"Turns an open quote of this member into an order and pays it without a client secret: method balance from the owner’s balance (no processing line), card or saved with the owner’s saved card off-session (the quote total plus 2.90 percent plus 30 cents; held until the seller releases the goods, then charged). Without method: the balance when it covers the total, else the saved card. method ach answers 409 no_payment_method: a bank payment is made by a person in the Shop. Needs the payments activity; the spending cap and the confirm amount see the buyer total. The seller’s payouts must be on (409 seller_not_connected). A refusal after the order exists cancels it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quote_id":{"type":"string","format":"uuid"},"method":{"type":"string","description":"balance, card (saved: the saved card), bank (the saved bank account and its mandate; ach is its older name).","enum":["balance","card","saved","ach","bank"]},"operation_id":{"type":"string","description":"Idempotency key; the request id by default.","minLength":8,"maxLength":96},"ship_to":{"$ref":"#/components/schemas/CarrierAddress","description":"The delivery address of a shipped order, checked once before payment (409 address_undeliverable)."}},"required":["quote_id"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketOrderPlaced"}}}},"202":{"description":"pending_owner_confirmation: the order is over the key’s confirm amount or spending cap, or the owner confirms orders (order_accept); it waits at Agent access, Waiting for you.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"pending_id":{"type":"string","format":"uuid"},"reason":{"type":"string"},"amount_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"detail":{"oneOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"invalid_input: a field is out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders, or payments to place an order; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the product (lot_id), the seller (slug), the quote or the order is not there or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The state refuses it: offer_unavailable, insufficient_quantity, quote_state, quote_expired, order_state, dispute_open, seller_not_connected, no_payment_method (hint), balance_insufficient (shortfall_cents), payment_needs_owner, card_declined. error_code carries the shared buyer code where one applies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"stripe_error: Stripe could not be reached or refused; the order is cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"payments_not_configured: the deployment has no Stripe keys, so no order can be paid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"marketOrders","tags":["Market"],"summary":"The orders this member placed","security":[{"bearerKey":[]}],"description":"Newest first, with the amounts, the payment line, the fulfillment, the latest dispute and the rating.","parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MarketOrder"}}},"required":["items"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders, or payments to place an order; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/orders/{id}":{"get":{"operationId":"marketOrder","tags":["Market"],"summary":"One order","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The order id.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketOrder"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders, or payments to place an order; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the product (lot_id), the seller (slug), the quote or the order is not there or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/sheets":{"post":{"operationId":"marketSheetCreate","tags":["Market"],"summary":"Make a result sheet","security":[{"bearerKey":[]}],"description":"One page with the agent’s ranked candidates for the owner: the agent gives the query, the ship-to, up to 12 offers with a quantity, a rank and a reason (and a trade-off), up to 6 spec names to compare, the notes, a title and the owner’s budget and deadline in the owner’s words; CommerceBook checks every offer (live, the quantity available and allowed), quotes the delivered shipping to the ship-to and computes the totals and the processing line by method. One failing offer refuses the sheet with 409 items_unavailable, naming each. The answer carries the link, the markdown and the JSON (with order_via_agent per item). A read in the activity map: any key may make one. Also the owner signed in (the session token).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"The owner’s request in the owner’s words.","maxLength":300},"title":{"type":"string","maxLength":120},"budget":{"type":"string","maxLength":80},"deadline":{"type":"string","maxLength":80},"ship_to":{"type":"object","properties":{"postal_code":{"type":"string","pattern":"^\\d{5}(-\\d{4})?$"},"state":{"type":"string","pattern":"^[A-Za-z]{2}$"}}},"items":{"type":"array","minItems":1,"maxItems":12,"items":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1},"rank":{"type":"integer","minimum":1,"maximum":12},"reason":{"type":"string","maxLength":400},"tradeoff":{"type":"string","maxLength":300}},"required":["offer_id","quantity","reason"]}},"compare":{"type":"array","maxItems":6,"items":{"type":"string","maxLength":60}},"notes":{"type":"string","maxLength":600},"public":{"type":"boolean","description":"true lets search engines index the page; false (the default) is noindex."}},"required":["query","ship_to","items"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketSheet"}}}},"400":{"description":"invalid_input: a field is out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders, or payments to place an order; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The state refuses it: offer_unavailable, insufficient_quantity, quote_state, quote_expired, order_state, dispute_open, seller_not_connected, no_payment_method (hint), balance_insufficient (shortfall_cents), payment_needs_owner, card_declined. error_code carries the shared buyer code where one applies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"marketSheets","tags":["Market"],"summary":"The result sheets of this member","security":[{"bearerKey":[]}],"description":"The sheets that have not expired, newest first: the query, the date, whether and how often the link was opened, and the top choice.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MarketSheetSummary"}}},"required":["items"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders, or payments to place an order; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/sheets/{id}":{"get":{"operationId":"marketSheet","tags":["Market"],"summary":"One result sheet, re-read live","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The sheet id.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketSheet"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders, or payments to place an order; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the product (lot_id), the seller (slug), the quote or the order is not there or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"marketSheetDelete","tags":["Market"],"summary":"Delete a result sheet","security":[{"bearerKey":[]}],"description":"By the member that made it; the link answers 404 after.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The sheet id.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"sheet_id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"}}}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders, or payments to place an order; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the product (lot_id), the seller (slug), the quote or the order is not there or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/orders/{id}/confirm-delivery":{"post":{"operationId":"marketOrderConfirmDelivery","tags":["Market"],"summary":"Confirm the goods arrived","security":[{"bearerKey":[]}],"description":"market_order_accept_goods(): a released order becomes accepted, which ends the time to file a dispute early; the seller is paid out within the hour.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The order id.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"operation_id":{"type":"string","description":"Idempotency key; the request id by default.","minLength":8,"maxLength":96}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"order_status":{"type":"string"}}}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders, or payments to place an order; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the product (lot_id), the seller (slug), the quote or the order is not there or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The state refuses it: offer_unavailable, insufficient_quantity, quote_state, quote_expired, order_state, dispute_open, seller_not_connected, no_payment_method (hint), balance_insufficient (shortfall_cents), payment_needs_owner, card_declined. error_code carries the shared buyer code where one applies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/orders/{id}/dispute":{"post":{"operationId":"marketOrderDispute","tags":["Market"],"summary":"Report a problem","security":[{"bearerKey":[]}],"description":"market_dispute_open() on a released, accepted or completed order. Shoppers have 30 days from delivery to file a dispute; after that the order is non-refundable (409 claim_window_closed). Each claim names a listing field; a field the listing did not state is refused (409 claim_field_not_stated:<field>). Shortage and condition need at least one photo in evidence.photos (409 receipt_evidence_required). The listing rules resolve shortage, condition, non-delivery and barcode claims; either side may ask for a person.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The order id.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","enum":["non_delivery","shortage","condition","other"]},"note":{"type":"string","maxLength":1000},"evidence":{"type":"object","properties":{"photos":{"type":"array","items":{"type":"string","description":"A photo link or a member-media path."},"maxItems":20},"received_count":{"type":"integer","minimum":0}},"additionalProperties":true},"claims":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["quantity","condition_grade","identity","known_defects","delivery","return_terms","other"]},"attribute":{"type":"string","enum":["title","brand","model","gtin"]},"stated":{"type":"string","maxLength":1000},"observed":{"type":"string","maxLength":1000},"evidence_ids":{"type":"array","items":{"type":"string"},"maxItems":20}},"required":["field"]},"maxItems":10},"operation_id":{"type":"string","description":"Idempotency key; the request id by default.","minLength":8,"maxLength":96}},"required":["reason"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"dispute_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"order_id":{"type":"string","format":"uuid"},"payment_status":{"oneOf":[{"type":"string"},{"type":"null"}]},"claims":{"type":"array","items":{"type":"object","properties":{}}},"post_payout":{"type":"boolean"},"claim_window_ends_at":{"oneOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"invalid_input: a field is out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders, or payments to place an order; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the product (lot_id), the seller (slug), the quote or the order is not there or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The state refuses it: offer_unavailable, insufficient_quantity, quote_state, quote_expired, order_state, dispute_open, seller_not_connected, no_payment_method (hint), balance_insufficient (shortfall_cents), payment_needs_owner, card_declined. error_code carries the shared buyer code where one applies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/orders/{id}/rate":{"post":{"operationId":"marketOrderRate","tags":["Market"],"summary":"Rate an order","security":[{"bearerKey":[]}],"description":"market_order_rate(): the goods and the seller from 1 to 5 on an accepted or completed order; a second call changes it.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The order id.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product_score":{"type":"integer","minimum":1,"maximum":5},"seller_score":{"type":"integer","minimum":1,"maximum":5},"note":{"type":"string","maxLength":1000}},"required":["product_score","seller_score"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"product_score":{"type":"integer"},"seller_score":{"type":"integer"},"note":{"oneOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"invalid_input: a field is out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders, or payments to place an order; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the product (lot_id), the seller (slug), the quote or the order is not there or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The state refuses it: offer_unavailable, insufficient_quantity, quote_state, quote_expired, order_state, dispute_open, seller_not_connected, no_payment_method (hint), balance_insufficient (shortfall_cents), payment_needs_owner, card_declined. error_code carries the shared buyer code where one applies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/orders/{id}/label/void":{"post":{"operationId":"sellerOrderLabelVoid","tags":["Seller"],"summary":"Void the order’s label before the first carrier scan; the balance is refunded","security":[{"bearerKey":[]}],"description":"A seller key with orders write, or the seller signed in. The label goes back to the carrier, the order returns to released (buy again or type a tracking number), and the label cost is refunded: to the balance in test mode, by Stripe on a balance payment.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The order.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"operation_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"label_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"order_id":{"type":"string","format":"uuid"},"fulfillment_status":{"type":"string"},"refund_status":{"type":"string"},"refunded_cents":{"type":"integer"},"refunded_to":{"oneOf":[{"type":"string"},{"type":"null"}]},"balance_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]}},"additionalProperties":true}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (detail orders:write or payments:write, with activity and hint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the order or the return is not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule refused the call: label_exists, fulfillment_state, ship_to_incomplete, package_unknown, origin_unknown, no_carrier_rate, balance_insufficient (with shortfall_cents and hint), label_in_use, no_label, void_refused, return_state, returns_not_available, carrier_refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"carrier_error or stripe_error: the carrier or Stripe did not answer; nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"carrier_not_configured: no carrier connection on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/orders/{id}/label":{"get":{"operationId":"sellerOrderLabel","tags":["Seller"],"summary":"The order’s labels to print, as links that last 10 minutes","security":[{"bearerKey":[]}],"description":"A seller key with orders read, or the seller signed in. Every purchased label of the order (the outbound label and any return label) with a signed URL to its PDF that lasts 10 minutes. The PDFs are kept in a private store, never at a public address; ask again for a new link.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The order.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"side":{"type":"string"},"labels":{"type":"array","items":{"type":"object","properties":{"label_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["outbound","return"]},"return_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"carrier":{"type":"string"},"service":{"type":"string"},"tracking":{"type":"string"},"status":{"type":"string"},"url":{"oneOf":[{"type":"string"},{"type":"null"}]},"expires_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"source":{"oneOf":[{"type":"string","enum":["stored","carrier"]},{"type":"null"}]}}}}},"required":["order_id","labels"]}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (detail orders:write or payments:write, with activity and hint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the order or the return is not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule refused the call: label_exists, fulfillment_state, ship_to_incomplete, package_unknown, origin_unknown, no_carrier_rate, balance_insufficient (with shortfall_cents and hint), label_in_use, no_label, void_refused, return_state, returns_not_available, carrier_refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"carrier_error or stripe_error: the carrier or Stripe did not answer; nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"carrier_not_configured: no carrier connection on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/orders/{id}/tracking":{"get":{"operationId":"sellerOrderTracking","tags":["Seller"],"summary":"The order’s label, carrier events and delivery as the seller sees them","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The order.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderTracking"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (detail orders:write or payments:write, with activity and hint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the order or the return is not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule refused the call: label_exists, fulfillment_state, ship_to_incomplete, package_unknown, origin_unknown, no_carrier_rate, balance_insufficient (with shortfall_cents and hint), label_in_use, no_label, void_refused, return_state, returns_not_available, carrier_refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"carrier_error or stripe_error: the carrier or Stripe did not answer; nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"carrier_not_configured: no carrier connection on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/returns/{id}/label":{"post":{"operationId":"sellerReturnLabel","tags":["Seller"],"summary":"Buy the return label of a return by mail","security":[{"bearerKey":[]}],"description":"A return by mail opened by a dispute. The label runs from the shopper’s delivery address to the return address and is charged to the side the return names (the seller when the return is at the seller’s cost). The shopper prints it from the order page; the carrier’s scans mark the return shipped and delivered. The cron buys it on its own within ten minutes when the balance covers it.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The return.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"operation_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarrierLabel"}}}},"202":{"description":"pending_owner_confirmation: a label bought with a key above the owner’s confirm amount or past the 30-day spending cap is not bought; it waits for the owner at Settings, Agent access (pending_id, reason, amount_cents). An approved item runs once.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"error":{"type":"string"},"detail":{"oneOf":[{"type":"string"},{"type":"null"}]},"pending_id":{"type":"string","format":"uuid"},"reason":{"type":"string"},"amount_cents":{"type":"integer"}}}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (detail orders:write or payments:write, with activity and hint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the order or the return is not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule refused the call: label_exists, fulfillment_state, ship_to_incomplete, package_unknown, origin_unknown, no_carrier_rate, balance_insufficient (with shortfall_cents and hint), label_in_use, no_label, void_refused, return_state, returns_not_available, carrier_refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"carrier_error or stripe_error: the carrier or Stripe did not answer; nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"carrier_not_configured: no carrier connection on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/orders/{id}/tracking":{"get":{"operationId":"marketOrderTracking","tags":["Market"],"summary":"The tracking of an order this member placed","security":[{"bearerKey":[]}],"description":"Any key of the buyer (orders read), or the buyer signed in. The carrier, the tracking number, the events newest first, delivered_at with delivered_by_scan, and attention when the carrier could not deliver.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The order.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderTracking"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (detail orders:write or payments:write, with activity and hint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the order or the return is not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule refused the call: label_exists, fulfillment_state, ship_to_incomplete, package_unknown, origin_unknown, no_carrier_rate, balance_insufficient (with shortfall_cents and hint), label_in_use, no_label, void_refused, return_state, returns_not_available, carrier_refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"carrier_error or stripe_error: the carrier or Stripe did not answer; nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"carrier_not_configured: no carrier connection on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/shipping/address-check":{"post":{"operationId":"shippingAddressCheck","tags":["Shipping"],"summary":"Check a delivery address once before an order","security":[{"bearerKey":[]}],"description":"Any key or a signed-in member. The carrier’s verification: deliverable, the residential flag and, when the carrier writes it differently, the corrected form as suggestion. POST /market/orders with ship_to runs the same check and refuses an undeliverable address with 409 address_undeliverable before payment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"$ref":"#/components/schemas/CarrierAddress"}},"required":["address"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressCheck"}}}},"400":{"description":"invalid_input: a field is missing or out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown or key_revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (detail orders:write or payments:write, with activity and hint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the order or the return is not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"A rule refused the call: label_exists, fulfillment_state, ship_to_incomplete, package_unknown, origin_unknown, no_carrier_rate, balance_insufficient (with shortfall_cents and hint), label_in_use, no_label, void_refused, return_state, returns_not_available, carrier_refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"carrier_error or stripe_error: the carrier or Stripe did not answer; nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"carrier_not_configured: no carrier connection on this deployment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/feedback/board":{"get":{"operationId":"feedbackBoard","tags":["Feedback"],"summary":"The feedback board: every post, the most wanted first","security":[{"bearerKey":[]}],"description":"Any key (reads: messages read for a warehouse key, orders read for a seller or a buyer key). Every member’s posts, a shipped post CommerceBook pinned first, then by votes and newest (sort=votes, the default) or newest alone (sort=newest); kind filters by the author’s kind. Each post carries its author, member, kind, votes, replies, status and whether the key’s person voted. A key acts as its member’s first person.","parameters":[{"name":"sort","in":"query","schema":{"type":"string","enum":["votes","newest"],"default":"votes"}},{"name":"kind","in":"query","schema":{"type":"string","enum":["warehouse","seller","buyer"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackBoard"}}}},"400":{"description":"invalid_input: detail names the field (title, title_too_long, body, body_too_long, sort, kind).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (messages for a warehouse key, orders for a seller or a buyer key; detail messages:write, with activity and hint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no such post.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"no_person: the account has no person yet, and a post, a reply and a vote carry a person’s name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/feedback/posts":{"post":{"operationId":"feedbackPostAdd","tags":["Feedback"],"summary":"Post to the feedback board","security":[{"bearerKey":[]}],"description":"Any key with the write level of its activity (messages for a warehouse key, orders for a seller or a buyer key). A title of 120 characters at most, an optional body of 4,000 and the page it is about. The post carries the name of the key’s person and is marked by_agent; CommerceBook hears of it the same hour. No anonymous posts, no down-votes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":120},"body":{"type":"string","maxLength":4000},"page":{"type":"string","maxLength":500}},"required":["title"],"additionalProperties":false}}}},"responses":{"201":{"description":"Posted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackPost"}}}},"400":{"description":"invalid_input: detail names the field (title, title_too_long, body, body_too_long, sort, kind).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (messages for a warehouse key, orders for a seller or a buyer key; detail messages:write, with activity and hint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no such post.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"no_person: the account has no person yet, and a post, a reply and a vote carry a person’s name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/feedback/posts/{id}":{"get":{"operationId":"feedbackPostRead","tags":["Feedback"],"summary":"One post with its full body and its replies in order","security":[{"bearerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The post.","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/FeedbackPost"},{"type":"object","properties":{"reply_list":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackReply"}}},"required":["reply_list"]}]}}}},"400":{"description":"invalid_input: detail names the field (title, title_too_long, body, body_too_long, sort, kind).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (messages for a warehouse key, orders for a seller or a buyer key; detail messages:write, with activity and hint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no such post.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"no_person: the account has no person yet, and a post, a reply and a vote carry a person’s name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/feedback/posts/{id}/replies":{"post":{"operationId":"feedbackReplyAdd","tags":["Feedback"],"summary":"Reply to a post","security":[{"bearerKey":[]}],"description":"Write level of the activity. The author and every earlier replier, except the sender, hear of it by email, one email each.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The post.","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","maxLength":4000}},"required":["body"],"additionalProperties":false}}}},"responses":{"201":{"description":"Replied","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"post_id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"body":{"type":"string"},"author_name":{"type":"string"},"replies":{"type":"integer"},"notified":{"type":"integer","description":"How many people were emailed."}},"required":["id","post_id","replies"]}}}},"400":{"description":"invalid_input: detail names the field (title, title_too_long, body, body_too_long, sort, kind).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (messages for a warehouse key, orders for a seller or a buyer key; detail messages:write, with activity and hint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no such post.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"no_person: the account has no person yet, and a post, a reply and a vote carry a person’s name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/feedback/posts/{id}/vote":{"post":{"operationId":"feedbackVoteToggle","tags":["Feedback"],"summary":"Vote for a post, or take the vote back","security":[{"bearerKey":[]}],"description":"Write level of the activity. One vote per person: a second call takes it back. There are no down-votes.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The post.","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"post_id":{"type":"string","format":"uuid"},"voted":{"type":"boolean"},"votes":{"type":"integer"}},"required":["post_id","voted","votes"]}}}},"400":{"description":"invalid_input: detail names the field (title, title_too_long, body, body_too_long, sort, kind).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (messages for a warehouse key, orders for a seller or a buyer key; detail messages:write, with activity and hint).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: no such post.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"no_person: the account has no person yet, and a post, a reply and a vote carry a person’s name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/intents":{"get":{"operationId":"marketIntents","tags":["Market"],"summary":"The open requests on the book","security":[{},{"bearerKey":[]}],"description":"The demand side of the book: every open public request (a request is an intent in the API), newest first, with the title, the category, the quantity, the most the buyer pays each (a band when the buyer hid it), the state, the expiry and the open quotes. No buyer is named. category narrows it; categories counts the open requests by category. No key needed (a cached read, not counted against the keyless limit); with a key the answer adds mine, the member’s own requests in every state.","parameters":[{"name":"category","in":"query","schema":{"type":"string","description":"A category key (for example packaging, office_supplies).","pattern":"^[a-z][a-z0-9_]{1,59}$"}},{"name":"q","in":"query","schema":{"type":"string","description":"Words; each must match a whole word of the title (stretch finds stretch wrap, never stretcher).","maxLength":200}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntents"}}}},"400":{"description":"invalid_input: detail names the field (title, category, qty, ceiling_unit_cents, visibility, expires_at, lot_id, unit_price_cents, qty_rules, whole_lot_only, note_too_long).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"marketIntentCreate","tags":["Market"],"summary":"Post a request","security":[{"bearerKey":[]}],"description":"market_intent_create(): what the owner wants (title), the category key, the quantity and the ceiling, the most the owner pays each (ceiling_visible false shows sellers a band instead); optional: where (a state or a ZIP; destination_zip, five digits, is shown on the public request), the unit of sale (unit: each, roll, case, pack, box, pallet or other, with unit_note), notes for sellers (1,000 characters), private (not on the book; only the matcher sees it), notify (email the owner when a quote lands or an offer at or under the ceiling appears; true by default) and expires_in_days (1 to 90, 30 by default). It costs nothing. Sellers with a live product in the category are told at once (sellers_told), and the answer lists the live offers already at or under the ceiling (matches_now). Needs orders write (a buyer or a seller key) or costs write (a warehouse key). At most 200 open requests per member.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","maxLength":120},"category":{"type":"string","description":"A category key, lower case with underscores.","pattern":"^[a-z][a-z0-9_]{1,59}$"},"qty":{"type":"integer","minimum":1},"ceiling_unit_cents":{"type":"integer","description":"The most the owner pays each, in cents.","minimum":1},"ceiling_visible":{"type":"boolean"},"destination":{"type":"string","description":"A state, a ZIP or an address line.","maxLength":200},"destination_zip":{"type":"string","description":"The five-digit ZIP the goods go to; shown on the public request.","pattern":"^[0-9]{5}$"},"unit":{"type":"string","description":"The unit of sale the quantity counts.","enum":["each","roll","case","pack","box","pallet","other"]},"unit_note":{"type":"string","description":"What the unit holds, for example 6 rolls a case.","maxLength":120},"notes":{"type":"string","maxLength":1000},"visibility":{"type":"string","enum":["public","private"]},"notify":{"type":"boolean"},"expires_in_days":{"type":"integer","minimum":1,"maximum":90},"operation_id":{"type":"string","description":"Idempotency key; the request id by default.","minLength":8,"maxLength":96}},"required":["title","category","qty","ceiling_unit_cents"],"additionalProperties":false}}}},"responses":{"201":{"description":"Posted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketIntentCreated"}}}},"400":{"description":"invalid_input: detail names the field (title, category, qty, ceiling_unit_cents, visibility, expires_at, lot_id, unit_price_cents, qty_rules, whole_lot_only, note_too_long).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders for a buyer or a seller key, costs for a warehouse key, payments to accept a quote, catalog for a seller key quoting; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The state refuses it: intent_state (the request is not open), quote_state, quote_expired, own_intent, quote_above_ceiling, quote_below_floor:<cents> (under the seller’s floor), offer_unavailable, insufficient_quantity, lot_evidence_stale, intent_limit (200 open requests), seller_not_connected, no_payment_method (hint), balance_insufficient (shortfall_cents).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/intents/{id}":{"delete":{"operationId":"marketIntentWithdraw","tags":["Market"],"summary":"Withdraw a request","security":[{"bearerKey":[]}],"description":"market_intent_withdraw(): an open request of this member leaves the book; its open quotes close with it and each seller is told.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The request (intent_id).","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"intent_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"quotes_closed":{"type":"integer"}}}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders for a buyer or a seller key, costs for a warehouse key, payments to accept a quote, catalog for a seller key quoting; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the request, the quote or the product is not there, not public or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The state refuses it: intent_state (the request is not open), quote_state, quote_expired, own_intent, quote_above_ceiling, quote_below_floor:<cents> (under the seller’s floor), offer_unavailable, insufficient_quantity, lot_evidence_stale, intent_limit (200 open requests), seller_not_connected, no_payment_method (hint), balance_insufficient (shortfall_cents).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/intents/{id}/quotes":{"get":{"operationId":"marketIntentQuotes","tags":["Market"],"summary":"The quotes on a request","security":[{"bearerKey":[]}],"description":"market_intent_quotes(): the request and every quote on it, open ones first by total: the quantity, the price each, the shipping, the total, the expiry (72 hours, or the request’s), the seller’s note, the product, its listed price at the quantity, and the seller’s tier and three numbers (delivered, on time, accurate).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The request (intent_id).","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"intent":{"$ref":"#/components/schemas/MarketIntentMine"},"items":{"type":"array","items":{"$ref":"#/components/schemas/MarketIntentQuote"}}},"required":["intent","items"]}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders for a buyer or a seller key, costs for a warehouse key, payments to accept a quote, catalog for a seller key quoting; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the request, the quote or the product is not there, not public or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/intents/{id}/quotes/{quote}/accept":{"post":{"operationId":"marketIntentQuoteAccept","tags":["Market"],"summary":"Accept a quote: the order at the quote’s price","security":[{"bearerKey":[]}],"description":"The existing order path at the seller’s price: a quote that holds the goods, then the order, paid as POST /market/orders is (method balance, or card / saved with the owner’s saved card; without method the balance when it covers, else the saved card). The fee is the market fee on the goods. The request is filled, the other open quotes are closed and their sellers told, and the seller hears of the order. Needs payments write; the spending cap and the confirm amount see the buyer total (202 when the owner confirms first). A refusal after the order exists cancels it and the request opens again.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The request (intent_id).","format":"uuid"}},{"name":"quote","in":"path","required":true,"schema":{"type":"string","description":"The quote (id of an item of GET /market/intents/{id}/quotes).","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"method":{"type":"string","enum":["balance","card","saved"]},"ship_to":{"type":"object","properties":{},"additionalProperties":true,"description":"The delivery address of a shipped quote (name, street1, city, state, zip), checked once before payment."},"operation_id":{"type":"string","description":"Idempotency key; the request id by default.","minLength":8,"maxLength":96}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/MarketOrderPlaced"},{"type":"object","properties":{"intent_id":{"type":"string","format":"uuid"},"intent_quote_id":{"type":"string","format":"uuid"}}}]}}}},"202":{"description":"pending_owner_confirmation: the order is over the key’s confirm amount or spending cap, or the owner confirms orders (order_accept); it waits at Agent access, Waiting for you.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"pending_id":{"type":"string","format":"uuid"},"reason":{"type":"string"},"amount_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"detail":{"oneOf":[{"type":"string"},{"type":"null"}]}}}}}},"400":{"description":"invalid_input: detail names the field (title, category, qty, ceiling_unit_cents, visibility, expires_at, lot_id, unit_price_cents, qty_rules, whole_lot_only, note_too_long).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders for a buyer or a seller key, costs for a warehouse key, payments to accept a quote, catalog for a seller key quoting; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the request, the quote or the product is not there, not public or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The state refuses it: intent_state (the request is not open), quote_state, quote_expired, own_intent, quote_above_ceiling, quote_below_floor:<cents> (under the seller’s floor), offer_unavailable, insufficient_quantity, lot_evidence_stale, intent_limit (200 open requests), seller_not_connected, no_payment_method (hint), balance_insufficient (shortfall_cents).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"stripe_error: Stripe could not be reached or refused; the order is cancelled and the request opens again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"payments_not_configured: the deployment has no Stripe keys, so no order can be paid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/intents/{id}/quotes/{quote}/decline":{"post":{"operationId":"marketIntentQuoteDecline","tags":["Market"],"summary":"Decline a quote","security":[{"bearerKey":[]}],"description":"market_intent_quote_decline(): the quote closes and the seller is told, with the reason when one is given (300 characters). The request stays open.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The request (intent_id).","format":"uuid"}},{"name":"quote","in":"path","required":true,"schema":{"type":"string","description":"The quote (id of an item of GET /market/intents/{id}/quotes).","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":300},"operation_id":{"type":"string","description":"Idempotency key; the request id by default.","minLength":8,"maxLength":96}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"quote_id":{"type":"string","format":"uuid"},"intent_id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders for a buyer or a seller key, costs for a warehouse key, payments to accept a quote, catalog for a seller key quoting; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the request, the quote or the product is not there, not public or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The state refuses it: intent_state (the request is not open), quote_state, quote_expired, own_intent, quote_above_ceiling, quote_below_floor:<cents> (under the seller’s floor), offer_unavailable, insufficient_quantity, lot_evidence_stale, intent_limit (200 open requests), seller_not_connected, no_payment_method (hint), balance_insufficient (shortfall_cents).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/intents":{"get":{"operationId":"sellerIntents","tags":["Seller"],"summary":"Open requests in your categories, and your quotes","security":[{"bearerKey":[]}],"description":"market_intents_for_seller(): the open public requests in the categories of your live products (or the category named), newest first, each with the buyer’s notes and your own quote on it; and your quotes in every state. No buyer is named. A seller key with catalog read.","parameters":[{"name":"category","in":"query","schema":{"type":"string","description":"A category key (for example packaging, office_supplies).","pattern":"^[a-z][a-z0-9_]{1,59}$"}},{"name":"q","in":"query","schema":{"type":"string","description":"Words; each must match a whole word of the title (stretch finds stretch wrap, never stretcher).","maxLength":200}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerIntents"}}}},"400":{"description":"invalid_input: detail names the field (title, category, qty, ceiling_unit_cents, visibility, expires_at, lot_id, unit_price_cents, qty_rules, whole_lot_only, note_too_long).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders for a buyer or a seller key, costs for a warehouse key, payments to accept a quote, catalog for a seller key quoting; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/intents/{id}/quote":{"post":{"operationId":"sellerIntentQuote","tags":["Seller"],"summary":"Quote a request with one of your products","security":[{"bearerKey":[]}],"description":"market_intent_quote_create(): your price each for the request, with one of your live products (lot_id): its live offer must cover the quantity (the minimum, the increment, a whole lot, what is available; qty defaults to the request’s and may be less), the price is at most the buyer’s ceiling (409 quote_above_ceiling) and, when your policies set offer_floor_pct, at least that share of the listed price at the quantity (409 quote_below_floor:<cents>). shipping_cents is your delivered shipping to the request’s state (0 for pickup). The quote holds 72 hours or until the request expires; one open quote per request, a new one replaces it. The buyer is told. A seller key with catalog write.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The request (intent_id).","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"lot_id":{"type":"string","format":"uuid"},"unit_price_cents":{"type":"integer","minimum":1},"qty":{"type":"integer","minimum":1},"shipping_cents":{"type":"integer","minimum":0},"note":{"type":"string","maxLength":500},"operation_id":{"type":"string","description":"Idempotency key; the request id by default.","minLength":8,"maxLength":96}},"required":["lot_id","unit_price_cents"],"additionalProperties":false}}}},"responses":{"201":{"description":"Quoted","content":{"application/json":{"schema":{"type":"object","properties":{"quote_id":{"type":"string","format":"uuid"},"intent_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"qty":{"type":"integer"},"unit_price_cents":{"type":"integer"},"shipping_cents":{"type":"integer"},"total_cents":{"type":"integer"},"fulfillment_method":{"type":"string"},"expires_at":{"type":"string","format":"date-time"},"list_unit_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"replaced":{"type":"boolean"},"fee_cents":{"type":"integer","description":"The market fee on the goods if it is accepted."}}}}}},"400":{"description":"invalid_input: detail names the field (title, category, qty, ceiling_unit_cents, visibility, expires_at, lot_id, unit_price_cents, qty_rules, whole_lot_only, note_too_long).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders for a buyer or a seller key, costs for a warehouse key, payments to accept a quote, catalog for a seller key quoting; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the request, the quote or the product is not there, not public or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The state refuses it: intent_state (the request is not open), quote_state, quote_expired, own_intent, quote_above_ceiling, quote_below_floor:<cents> (under the seller’s floor), offer_unavailable, insufficient_quantity, lot_evidence_stale, intent_limit (200 open requests), seller_not_connected, no_payment_method (hint), balance_insufficient (shortfall_cents).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/quotes/{id}":{"delete":{"operationId":"sellerQuoteWithdraw","tags":["Seller"],"summary":"Withdraw a quote","security":[{"bearerKey":[]}],"description":"market_intent_quote_withdraw(): an open quote of yours closes; the buyer can no longer accept it.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The quote (quote_id).","format":"uuid"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"quote_id":{"type":"string","format":"uuid"},"intent_id":{"type":"string","format":"uuid"},"status":{"type":"string"}}}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks the activity (orders for a buyer or a seller key, costs for a warehouse key, payments to accept a quote, catalog for a seller key quoting; activity and hint name it).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the request, the quote or the product is not there, not public or not this member’s.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The state refuses it: intent_state (the request is not open), quote_state, quote_expired, own_intent, quote_above_ceiling, quote_below_floor:<cents> (under the seller’s floor), offer_unavailable, insufficient_quantity, lot_evidence_stale, intent_limit (200 open requests), seller_not_connected, no_payment_method (hint), balance_insufficient (shortfall_cents).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour; without a key, 60 calls a minute and 1,200 an hour per address (body: error, retry_after_seconds, window; Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/book":{"get":{"operationId":"marketBook","tags":["Market"],"summary":"The book right now (no key)","security":[{},{"bearerKey":[]}],"description":"market_book() of the one snapshot every surface renders (the same as_of on the briefings, the MCP greeting, the first screens, the feeds and the sitemap): what is on the market and what buyers ask for, by category, with live numbers only. Supply: public products, the sellers behind them and the lowest price from 1 unit. Demand: open public requests, the quantity asked for and the ceilings as bands (no buyer is named). Fills in the last 30 days: orders, those that filled a request, the median hours from request to quote and from quote to order. Sellers: delivered and on time across every seller’s orders, a count until it is built on 10 orders, then a percent. Every category of the list is present and zero reads zero. Cached 15 minutes, like GET /network/now. The same answer is the MCP tool commercebook_market action book and the strip The book right now on https://commercebook.ai/the-book.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketBook"}}}},"503":{"description":"not_available: the book could not be read.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/checkout-mode":{"get":{"operationId":"sellerCheckoutModeGet","tags":["Seller"],"summary":"How your buyers pay: on CommerceBook or on your Shopify checkout","security":[{"bearerKey":[]}],"description":"The mode in force for the seller's products: commercebook (the buyer pays on CommerceBook through Stripe; the CommerceBook refund and dispute rules apply; the fee is taken from each sale) or shopify (the buyer pays on the store's own Shopify checkout; Shopify holds the money; the store's refund and dispute policies apply; the fee is billed once a month to the saved card). Shopify can be chosen with an installed Shopify store and a saved card. Needs payouts:read.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerCheckoutMode"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks payouts:read (GET) or payouts:write (POST), or the member is not a seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: a warehouse key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"sellerCheckoutModeSet","tags":["Seller"],"summary":"Choose how your buyers pay","security":[{"bearerKey":[]}],"description":"Switches the seller's products between commercebook and shopify. confirm true is required to change the mode (409 confirmation_required without it). shopify needs an installed Shopify store (409 shopify_store_required) and a card saved for the monthly fee invoice (409 fee_card_required); a store installed from the Shopify App Store stays on shopify (409 app_store_install). Orders already placed keep the rules they were placed under. One seller.checkout_mode row on the ledger per change. Needs payouts:write.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["commercebook","shopify"]},"confirm":{"type":"boolean","description":"true to make the change."}},"required":["mode"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerCheckoutMode"}}}},"400":{"description":"invalid_input: mode is commercebook or shopify; confirm is true or false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks payouts:read (GET) or payouts:write (POST), or the member is not a seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: a warehouse key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"confirmation_required, shopify_store_required, fee_card_required or app_store_install; detail says what to do.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/shopify":{"get":{"operationId":"sellerShopifyStatus","tags":["Seller"],"summary":"The CommerceBook channel in Shopify: status, or an install link","security":[{"bearerKey":[]}],"description":"The seller's CommerceBook sales channel in Shopify: whether a store is connected, the last sync with its counts and skipped rows, the products linked and live, the CommerceBook orders sent to the store as Shopify orders, Stripe, and the open requests in the store's categories. With ?shop=<x>.myshopify.com it also answers install_url: a single-use link, good for 15 minutes, that installs the app on that store for this seller (the owner opens it and approves the access in Shopify). Once installed, the catalog is on the book within the hour. Needs catalog:read.","parameters":[{"name":"shop","in":"query","required":false,"schema":{"type":"string","description":"A store address that ends in .myshopify.com."}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerShopifyStatus"}}}},"400":{"description":"invalid_input: shop is not a store address that ends in .myshopify.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks catalog:read (status) or catalog:write (sync), or the member is not a seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: a warehouse key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"not_configured: the Shopify app is not set up on this server yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/shopify/sync":{"post":{"operationId":"sellerShopifySync","tags":["Seller"],"summary":"Sync the Shopify catalog now","security":[{"bearerKey":[]}],"description":"Reads the connected store's products now (variants, prices, the available quantity at the first active location, pictures, SKU, barcode, the commercebook.price_schedule metafield) and writes them as lots with the catalog import's writer: a product not active in Shopify stays a draft, a quantity of 0 takes the lot off the book, a lot the app drafted goes back when the product is active again. The hourly sync and the product webhooks do the same on their own. Needs catalog:write.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerShopifySync"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the key lacks catalog:read (status) or catalog:write (sync), or the member is not a seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: a warehouse key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"not_connected: no Shopify store is connected to this seller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: 600 calls per key per hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"sync_failed: Shopify could not be read; detail says why (shopify_http_401 after the merchant removed the app, no_active_location, ...).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"not_configured: the Shopify app is not set up on this server yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/agent-rules":{"get":{"operationId":"getAgentRules","tags":["Account"],"summary":"The rules your agent cannot cross","security":[{"bearerKey":[]}],"description":"Read these first and plan within them. The owner sets them on Your agent; CommerceBook enforces them on every call. A write outside allowed_actions, allowed_hours, allowed_categories or counterparties answers 403 rule_blocked with the rule; a payment over a money rule answers 202 pending_owner_confirmation and waits for the owner. With a key: the rules that bind that key and text, a paragraph for the agent’s instructions. With the owner’s session token: the page (rules, who set each and when, keys, history).","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRulesView"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"setAgentRules","tags":["Account"],"summary":"Change the rules (the owner signed in)","security":[{"bearerKey":[]}],"description":"The owner’s session token only. Rules left out keep their value. A change that loosens a rule answers 409 confirm_loosen until it is sent with confirm true. Every change is kept in the history and emailed to the owner (rule_changed). A key answers 403 owner_in_person.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"spend_cap_cents_30d":{"oneOf":[{"type":"integer","description":"Most the agent spends in any 30 days across every key of the account, in cents; null: each key keeps its own cap.","minimum":0},{"type":"null"}]},"confirm_above_cents":{"oneOf":[{"type":"integer","description":"A payment above this waits for the owner; the lower of this and the key’s own amount applies.","minimum":0},{"type":"null"}]},"order_max_cents":{"oneOf":[{"type":"integer","description":"One order or purchase above this waits for the owner (over_order_max).","minimum":0},{"type":"null"}]},"allowed_categories":{"oneOf":[{"type":"array","items":{"type":"string"},"description":"Product categories the agent may buy in and post requests in; null is every category."},{"type":"null"}]},"counterparties":{"type":"string","enum":["any","verified","list"],"description":"Members the agent may deal with: any, verified only, or the list in counterparty_member_ids."},"counterparty_member_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"allowed_hours":{"oneOf":[{"type":"object","properties":{"tz":{"type":"string","description":"An IANA time zone, such as America/Chicago."},"start":{"type":"string","description":"HH:MM"},"end":{"type":"string","description":"HH:MM; earlier than start runs past midnight."},"days":{"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}}},"required":["tz","start","end","days"]},{"type":"null"}]},"allowed_actions":{"oneOf":[{"type":"array","items":{"type":"string","enum":["post","quote","accept","pay","withdraw","message","lead_post","lead_buy","capacity_quote"]},"description":"The actions the agent may take; null is every action its key allows. Reading is always allowed."},{"type":"null"}]},"auto_accept_under_ceiling":{"type":"boolean","description":"A seller’s quote at or under the request’s ceiling, inside every other rule, is accepted for the owner automatically."},"notify":{"type":"string","enum":["each","daily","none"],"description":"The owner’s email when a rule stops the agent: each time, once a day, or never."},"notify_channel":{"type":"string","enum":["email","telegram"]},"confirm":{"type":"boolean","description":"true to save a change that loosens a rule."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"The page after the change."}}}},"400":{"description":"invalid_input or invalid_body: a rule is out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"owner_in_person: \"Your agent cannot change its own rules; sign in to change them.\" A key never changes the account rules; it may lower its own limits with PUT /keys/{id}/limits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"confirm_loosen: the change loosens the rules named in detail; send it again with confirm true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/agent-activity":{"get":{"operationId":"getAgentActivity","tags":["Account"],"summary":"What the agent did","security":[{"bearerKey":[]}],"description":"Every call of the member’s keys in the last days (30 by default), newest first, with the result (allowed, parked, stopped) and the rule behind it, the amount and the counterparty; the quotes the auto-accept rule accepted or left waiting.","parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":90,"default":30}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/AgentActivityItem"}}},"required":["days","items"]}}}},"400":{"description":"invalid_input or invalid_body: a rule is out of range; detail names it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing, key_unknown, key_revoked or key_expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: the key’s calls per hour (600 at most).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/intents/reach":{"get":{"operationId":"requestReach","tags":["Market"],"summary":"How far a request reaches (no key)","security":[{},{"bearerKey":[]}],"description":"Before posting: how many sellers a public request in the category would be emailed to (each with a live product there, or watching it) and how many live products match the quantity and the state. Counts only; no seller is named. The same answer is the MCP tool commercebook_market action reach.","parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string","description":"A category key (GET /market/book lists them).","pattern":"^[a-z][a-z0-9_]{1,59}$"}},{"name":"qty","in":"query","schema":{"type":"integer","minimum":1}},{"name":"destination_state","in":"query","schema":{"type":"string","description":"Two letters.","pattern":"^[A-Za-z]{2}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestReach"}}}},"400":{"description":"invalid_input: category, qty or destination_state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: without a key, 60 calls a minute and 1,200 an hour per address (retry_after_seconds and window in the body, Retry-After in seconds); with a key, 600 calls an hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/lots/{id}/shipping":{"get":{"operationId":"marketLotShipping","tags":["Market"],"summary":"Shipping of one product to a state or ZIP (no key)","security":[{},{"bearerKey":[]}],"description":"The lowest and highest shipping of the lot’s rules to one state, or to a ZIP (destination_zip; the state is read from it), from the seller’s shipping profile (no carrier call). Every amount is the shipping of the whole order of qty units (rate_basis per_order). qty_available is the stock and short_by how far qty is over it. served false: the seller does not ship there. A calculated rule is priced at the quote. The MCP tool is commercebook_market action shipping_estimate.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","description":"The lot_id of a search item.","format":"uuid"}},{"name":"state","in":"query","schema":{"type":"string","description":"Two letters; send this or destination_zip.","pattern":"^[A-Za-z]{2}$"}},{"name":"destination_zip","in":"query","schema":{"type":"string","description":"A five-digit US ZIP; the state is read from it.","pattern":"^[0-9]{5}(-[0-9]{4})?$"}},{"name":"qty","in":"query","schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShippingEstimate"}}}},"400":{"description":"invalid_input: state, destination_zip or qty.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found: the lot is not public.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: without a key, 60 calls a minute and 1,200 an hour per address (retry_after_seconds and window in the body, Retry-After in seconds); with a key, 600 calls an hour.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/category-watch":{"get":{"operationId":"sellerCategoryWatch","tags":["Seller"],"summary":"The categories the seller watches","security":[{"bearerKey":[]}],"description":"The categories the seller is told of new public requests in, with or without a live product (the dealer’s path for goods it quotes and does not list). Needs the catalog activity (read). The MCP tool is commercebook_seller_requests action watched.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryWatch"}}}},"401":{"description":"key_missing or key_unknown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the catalog activity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"operationId":"sellerCategoryWatchSet","tags":["Seller"],"summary":"Set the categories the seller watches","security":[{"bearerKey":[]}],"description":"The whole list of watched categories (30 at most; an empty list watches none). From then on the seller is told of every new public request in them. Needs the catalog activity (write). The MCP tool is commercebook_seller_requests action watch.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,59}$"}},"operation_id":{"type":"string"}},"required":["categories"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryWatch"}}}},"400":{"description":"invalid_input: categories.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"key_missing or key_unknown.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"not_permitted: the catalog activity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/seller/capabilities":{"get":{"operationId":"sellerCapabilities","tags":["Seller"],"summary":"What a seller can do (no key)","security":[{},{"bearerKey":[]}],"description":"Every seller capability on CommerceBook in one read, grouped: ways_to_offer, ways_to_be_found, ways_to_be_paid, what_the_record_shows, rules and first_steps. Each capability carries available, since or planned_as_of, the tool and the endpoint that does it, and one sentence. The same list renders /sell and /capabilities on https://seller.commercebook.ai, the seller briefing’s first screen and llms.txt. The MCP tool is commercebook_capabilities action seller.","parameters":[{"name":"group","in":"query","schema":{"type":"string","description":"One group only.","enum":["ways_to_offer","ways_to_be_found","ways_to_be_paid","what_the_record_shows","rules","first_steps"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerCapabilities"}}}},"400":{"description":"invalid_input: group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited: without a key, 60 calls a minute and 1,200 an hour per address (retry_after_seconds and window in the body, Retry-After in seconds).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerKey":{"type":"http","scheme":"bearer","description":"An agent link key or a named key, from Agent access (cb_agent_...)."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"The code."},"detail":{"oneOf":[{"type":"string","description":"The field, the rule or the permission the code is about."},{"type":"null"}]},"activity":{"type":"string","description":"not_permitted: the activity the call needs."},"hint":{"type":"string","description":"not_permitted: where the owner turns the activity on."}},"required":["error"]},"Me":{"type":"object","properties":{"member":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string","enum":["provisional","verified","suspended","declined","banned"]},"home_market":{"oneOf":[{"type":"string"},{"type":"null"}]},"services":{"type":"array","items":{"type":"string"}},"markets":{"type":"array","items":{"type":"string"}},"sqft":{"oneOf":[{"type":"integer"},{"type":"null"}]},"notification_email":{"oneOf":[{"type":"string"},{"type":"null"}]},"phone":{"oneOf":[{"type":"string"},{"type":"null"}]},"crm_connection":{"type":"string"},"wms_system":{"oneOf":[{"type":"string"},{"type":"null"}]},"crm_system":{"oneOf":[{"type":"string"},{"type":"null"}]},"other_systems":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"systems_answered_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}}},"organisation":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"domain":{"oneOf":[{"type":"string","description":"The mail domain whose sign-ups join this organisation."},{"type":"null"}]}},"required":["id","name","domain"],"description":"The organisation (your company) this member belongs to."},{"type":"null"}]},"verified":{"type":"boolean"},"counts":{"type":"object","properties":{"deals":{"type":"integer"},"leads_posted":{"type":"integer"},"leads_drafts":{"type":"integer"},"leads_claimed":{"type":"integer"},"threads":{"type":"integer"},"capacity_sent":{"type":"integer"},"capacity_received":{"type":"integer"},"invoices":{"type":"integer"}}}},"required":["member","verified","counts"]},"Lead":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"listed_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"source_member_id":{"type":"string","format":"uuid"},"deal_id":{"oneOf":[{"type":"string","description":"Your CRM deal; null on a lead you did not post.","format":"uuid"},{"type":"null"}]},"status":{"type":"string","enum":["draft","open","claimed","sold","expired","disputed","withdrawn","pending_review"],"description":"pending_review: a lead partner’s first leads wait for a CommerceBook review before they open."},"summary":{"oneOf":[{"type":"string","description":"What the prospect needs, in the seller’s words."},{"type":"null"}]},"description":{"oneOf":[{"type":"string"},{"type":"null"}]},"service":{"type":"string"},"origin_market":{"oneOf":[{"type":"string"},{"type":"null"}]},"target_markets":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"location_any":{"type":"boolean","description":"Anywhere: the prospect has no preferred place; target_markets is empty."},"title":{"oneOf":[{"type":"string","description":"The title buyers see first (80 characters)."},{"type":"null"}]},"summary_short":{"oneOf":[{"type":"string","description":"The one-line summary (140 characters)."},{"type":"null"}]},"lead_source":{"type":"string","enum":["own","referral"]},"referral_source":{"oneOf":[{"type":"string","description":"The lead company that referred it."},{"type":"null"}]},"volume_band":{"oneOf":[{"type":"string"},{"type":"null"}]},"window_start":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"window_end":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"last_contact_at":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"price_flat_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"price_pct":{"oneOf":[{"type":"number"},{"type":"null"}]},"terms":{"type":"string","enum":["flat","pct","both"]},"exclusivity":{"type":"string","enum":["exclusive","open"]},"max_buyers":{"type":"integer"},"claimed_count":{"type":"integer"},"hold_expires_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"pallets_on_hand":{"oneOf":[{"type":"integer"},{"type":"null"}]},"pallets_inbound_month":{"oneOf":[{"type":"integer"},{"type":"null"}]},"orders_month":{"oneOf":[{"type":"integer"},{"type":"null"}]},"skus":{"oneOf":[{"type":"integer"},{"type":"null"}]},"containers_month":{"oneOf":[{"type":"integer"},{"type":"null"}]},"sqft":{"oneOf":[{"type":"integer"},{"type":"null"}]},"units_month":{"oneOf":[{"type":"integer"},{"type":"null"}]},"success_fee_pct":{"oneOf":[{"type":"number"},{"type":"null"}]},"views_count":{"type":"integer"},"times_listed":{"type":"integer"},"times_sold":{"type":"integer"},"badges":{"type":"integer","description":"A bit mask of the facts-on-file badges."},"own":{"type":"boolean","description":"Your own lead (GET /leads/open with include_own, and every item of GET /leads/mine)."},"quality":{"$ref":"#/components/schemas/LeadQuality"},"poster_type":{"type":"string","enum":["warehouse","lead_partner"],"description":"Who posted the lead: a warehouse or a lead partner."},"poster_role":{"oneOf":[{"type":"string","description":"The lead partner’s role (sales_rep, broker, consultant, ...); null for a warehouse."},{"type":"null"}]},"poster_sold_count":{"type":"integer","description":"How many of the poster’s leads sold."},"poster_rating_avg":{"oneOf":[{"type":"number","description":"The average stars buyers gave a lead partner, shown from 3 ratings; null otherwise."},{"type":"null"}]},"poster_rating_count":{"oneOf":[{"type":"integer","description":"How many ratings stand behind poster_rating_avg; null below 3."},{"type":"null"}]},"acquired_at":{"oneOf":[{"type":"string","description":"The day the poster received the lead (Received on the exchange).","format":"date"},{"type":"null"}]},"held_days":{"oneOf":[{"type":"integer","description":"Days between received (acquired_at) and listed (listed_at, America/Chicago); the exchange marks the lead held above 7. Null when either date is missing."},{"type":"null"}]},"saved":{"type":"boolean","description":"You saved this lead (POST /leads/{id}/mark with save)."},"passed":{"type":"boolean","description":"You passed on this lead (POST /leads/{id}/mark with pass); the exchange lists it last."},"poster_logo_path":{"oneOf":[{"type":"string","description":"The poster’s logo in the member-media bucket (the profile logo); null for a lead partner or without a logo."},{"type":"null"}]},"poster_logo_url":{"oneOf":[{"type":"string","description":"The public address of poster_logo_path.","format":"uri"},{"type":"null"}]}},"required":["id","status","service"],"additionalProperties":true},"LeadQuality":{"type":"object","properties":{"score":{"type":"integer","description":"0 to 9: one point each for service, location, volume, timing, product, current provider, inbound mode, order profile and budget.","minimum":0,"maximum":9},"of":{"type":"integer","minimum":9,"maximum":9},"present":{"type":"array","items":{"type":"string","enum":["service","location","volume","timing","product","provider","inbound","orders","budget"]}},"missing":{"oneOf":[{"type":"array","items":{"type":"string","enum":["service","location","volume","timing","product","provider","inbound","orders","budget"]},"description":"Your own lead only; null for a buyer, who never reads what is missing."},{"type":"null"}]}},"required":["score","of","present"],"description":"The lead quality meter."},"Standing":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["provisional","verified","suspended","declined","banned"]},"strikes":{"type":"integer","description":"Every strike, all time."},"strikes_90d":{"type":"integer","description":"Strikes in the last 90 days."},"strikes_365d":{"type":"integer","description":"Strikes in the last 365 days."},"fabricated":{"type":"integer","description":"Fabricated-contact strikes, all time."},"posting_suspended_until":{"oneOf":[{"type":"string","description":"Posting is suspended until then; existing listings stay up and buying still works.","format":"date-time"},{"type":"null"}]},"posting_allowed":{"type":"boolean"},"suspended_at":{"oneOf":[{"type":"string","description":"When the member was removed from the exchange or banned.","format":"date-time"},{"type":"null"}]},"suspended_reason":{"oneOf":[{"type":"string"},{"type":"null"}]},"rules":{"type":"object","properties":{"suspend_strikes":{"type":"integer"},"suspend_window_days":{"type":"integer"},"suspend_days":{"type":"integer"},"remove_strikes":{"type":"integer"},"remove_window_days":{"type":"integer"},"remove_fabricated":{"type":"integer"}}}},"required":["status","strikes_90d","strikes_365d","posting_allowed"]},"PostOutcome":{"type":"object","properties":{"outcome":{"type":"string","enum":["posted","draft","blocked","duplicate"]},"lead_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"draft_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"summary_source":{"oneOf":[{"type":"string"},{"type":"null"}]},"markets":{"type":"array","items":{"type":"string","description":"City, ST"}},"location_any":{"type":"boolean"},"title":{"oneOf":[{"type":"string"},{"type":"null"}]},"summary_short":{"oneOf":[{"type":"string"},{"type":"null"}]},"lead_source":{"type":"string"},"referral_source":{"oneOf":[{"type":"string"},{"type":"null"}]},"quality":{"$ref":"#/components/schemas/LeadQuality"}},"required":["outcome"]},"ClaimOutcome":{"type":"object","properties":{"payment":{"type":"string","enum":["demo","card"]},"lead_id":{"type":"string","format":"uuid"},"claim_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"deal_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"amount_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"fee_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"payout_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"status":{"oneOf":[{"type":"string"},{"type":"null"}]},"client_secret":{"oneOf":[{"type":"string","description":"Card path: confirm the PaymentIntent with Stripe to complete the claim."},{"type":"null"}]},"payment_intent_id":{"oneOf":[{"type":"string"},{"type":"null"}]},"mode":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["payment","lead_id"],"additionalProperties":true},"Deal":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"name":{"type":"string"},"stage":{"type":"string","enum":["new","qualified","discovery","site_visit","quoted","negotiating","won","onboarding","live","lost","offered"],"description":"quoted is Quote sent. Won, onboarding and live count as won. offered is accepted and keeps the deal’s stage (a listing is the exchange link)."},"service":{"oneOf":[{"type":"string"},{"type":"null"}]},"target_market":{"oneOf":[{"type":"string"},{"type":"null"}]},"value_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"monthly_revenue_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"description":{"oneOf":[{"type":"string"},{"type":"null"}]},"expected_closing_date":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"source":{"type":"string"},"is_private":{"type":"boolean"},"attributes":{"type":"object","additionalProperties":true},"facility_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"company_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"company_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"contact_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"contact_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"checklist":{"type":"object","properties":{"qualified":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"meeting_held":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"site_visited":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"quote_sent":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"contract_sent":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"contract_signed":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"onboarding_started":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]}},"additionalProperties":false,"description":"Each item a date, or null when not done."},"follow_up_due":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"won_at":{"oneOf":[{"type":"string","description":"When the deal entered won, onboarding or live.","format":"date-time"},{"type":"null"}]},"sales_id":{"oneOf":[{"type":"string","description":"The rep (a sales row of one of your logins).","format":"uuid"},{"type":"null"}]},"exchange":{"oneOf":[{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"listed_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"price_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]}},"required":["lead_id"]},{"type":"null"}]}},"required":["id","name","stage"]},"CapacityRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["requested","quoted","accepted","declined","withdrawn"]},"positions":{"type":"integer"},"start_date":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"end_date":{"oneOf":[{"type":"string","format":"date"},{"type":"null"}]},"requirements":{"oneOf":[{"type":"string"},{"type":"null"}]},"quote_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"quote_breakdown":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"node_id":{"type":"string","format":"uuid"},"requester_member_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"requester_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"direction":{"type":"string","enum":["sent","received"]},"node_member_id":{"type":"string","format":"uuid"},"node_member_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"withdrawn_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","status","positions","node_id"],"additionalProperties":true},"MemberCard":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string"},"home_market":{"oneOf":[{"type":"string"},{"type":"null"}]},"phone":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"],"additionalProperties":true},"Thread":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string"},"subject":{"oneOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string","enum":["requested","open","ignored","blocked"]},"created_by_member_id":{"type":"string","format":"uuid"},"requested_to_member_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"last_message_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"preview":{"oneOf":[{"type":"string"},{"type":"null"}]},"muted":{"type":"boolean"},"last_read_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"unread":{"type":"integer"},"others":{"type":"array","items":{"$ref":"#/components/schemas/MemberCard"}}},"required":["id","status"]},"Attachment":{"type":"object","properties":{"type":{"type":"string","enum":["lead","exchange_post","deal","facility","capacity_request"]},"id":{"type":"string","format":"uuid"},"label":{"type":"string"}},"required":["type","id"]},"Message":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"sender_member_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"kind":{"type":"string"},"body":{"oneOf":[{"type":"string"},{"type":"null"}]},"attachment":{"oneOf":[{"$ref":"#/components/schemas/Attachment"},{"type":"null"}]}},"required":["id"]},"ThreadDetail":{"type":"object","properties":{"thread":{"type":"object","additionalProperties":true},"members":{"type":"array","items":{"$ref":"#/components/schemas/MemberCard"}},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"blocked":{"type":"boolean"}},"required":["thread","messages"]},"PriceRow":{"type":"object","properties":{"item_key":{"type":"string","description":"key_v3: category, unit and the key spec, each field read by its own parser, with the pack count (rolls per case, count per case, labels per roll) when the unit is a pack."},"legacy_item_key":{"type":"string","description":"The older key, for callers that stored it; POST /costs/prices/match takes either."},"category":{"oneOf":[{"type":"string"},{"type":"null"}]},"category_label":{"type":"string"},"label":{"type":"string"},"spec":{"type":"string"},"unit":{"type":"string"},"your_price_cents":{"type":"integer"},"qty":{"type":"number"},"annual_qty":{"oneOf":[{"type":"integer","description":"The yearly quantity; null when it is not known (one purchase, and no stated yearly use)."},{"type":"null"}]},"annual_basis":{"type":"string","enum":["stated","extrapolated","unknown"]},"months_covered":{"type":"integer"},"line_count":{"type":"integer"},"vendors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"invoiceId":{"type":"string","format":"uuid"},"date":{"type":"string"}}}},"network_quote":{"oneOf":[{"type":"object","properties":{"vendor":{"type":"string"},"unit_price_cents":{"type":"integer"},"terms":{"oneOf":[{"type":"string"},{"type":"null"}]},"region":{"oneOf":[{"type":"string"},{"type":"null"}]},"illustrative":{"type":"boolean"},"match":{"type":"string","enum":["exact","reviewed_equivalent","possible"],"description":"possible: a key spec or pack count is missing on one side, the delivery basis differs, or the price is stale; it carries no saving."},"basis":{"type":"string","enum":["delivered","not_stated"]},"quoted_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"stale":{"type":"boolean"},"source":{"type":"string","enum":["supplier","network_member"],"description":"supplier: a supplier quote. network_member: the lowest price another member paid for the same item in the last 365 days (vendor reads Network member price; the member is never named)."},"missing_specs":{"type":"array","items":{"type":"string"},"description":"The key fields not stated on one side (a possible match needs them before it can carry a saving)."}}},{"type":"null"}]},"rate_shop":{"oneOf":[{"$ref":"#/components/schemas/RateShop","description":"The Rate Shop column: the network range for the item, the other members behind it and the vendor of the best price; null without one."},{"type":"null"}]},"opportunity_cents":{"oneOf":[{"type":"integer","description":"Positive (your price minus an exact or reviewed quote, or a lower network member price) times quantity; null for a possible match."},{"type":"null"}]}},"required":["item_key","label","unit","your_price_cents"]},"SellerMe":{"type":"object","properties":{"member":{"type":"object","additionalProperties":true},"organisation":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"domain":{"oneOf":[{"type":"string","description":"The mail domain whose sign-ups join this organisation."},{"type":"null"}]}},"required":["id","name","domain"],"description":"The organisation (your company) this member belongs to."},{"type":"null"}]},"verified":{"type":"boolean"},"ready":{"type":"object","additionalProperties":true,"description":"seller_ready(): entity_complete, stripe_onboarded, stripe_payouts_enabled, policies_accepted, fulfillment_mode, delegation_accepted, live."},"blockers":{"type":"array","items":{"type":"string"}},"entity":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"counts":{"type":"object","additionalProperties":true}},"required":["member","ready","counts"]},"SellerLot":{"type":"object","properties":{"lot_id":{"type":"string","format":"uuid"},"lot_code":{"type":"string"},"product_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"sku":{"oneOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"brand":{"oneOf":[{"type":"string"},{"type":"null"}]},"category":{"oneOf":[{"type":"string"},{"type":"null"}]},"condition":{"oneOf":[{"type":"string"},{"type":"null"}]},"state":{"type":"string","enum":["live","held","draft","stale","sold_out","withdrawn"]},"lot_status":{"type":"string","enum":["draft","active","paused","sold_out","withdrawn"]},"qty_on_hand":{"type":"integer"},"qty_reserved":{"type":"integer"},"qty_committed":{"type":"integer"},"qty_available":{"type":"integer"},"offer_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"offer_status":{"oneOf":[{"type":"string"},{"type":"null"}]},"unit_price_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"photo":{"oneOf":[{"type":"string"},{"type":"null"}]},"photo_count":{"type":"integer"},"missing":{"type":"array","items":{"type":"string","description":"A Tier 1 field the product still lacks."}},"price_mode":{"type":"string","enum":["fixed","schedule"],"description":"schedule: the price falls with the quantity; a quote at a quantity returns that price."},"schedule_kind":{"oneOf":[{"type":"string","enum":["volume","graduated"],"description":"How the tiers apply (default volume). volume: every unit is priced at the price of the highest tier the quantity reaches. graduated: the units within each tier are priced at that tier’s price."},{"type":"null"}]},"price_schedule":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"min_qty":{"type":"integer","minimum":1},"unit_price_cents":{"type":"integer","minimum":1}},"required":["min_qty","unit_price_cents"]},"minItems":2,"maxItems":10,"description":"The tiers, ascending by min_qty: {min_qty, unit_price_cents}; the first tier starts at min_qty 1 (or at the offer minimum) and its price is the unit price; each later tier has a larger min_qty and a lower price; 2 to 10 tiers. unit_price_cents is the first tier."},{"type":"null"}]},"completeness":{"type":"integer","description":"Percent of the eight Tier 1 fields filled."},"evidence_count":{"oneOf":[{"type":"integer"},{"type":"null"}]},"evidence_as_of":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"evidence_method":{"oneOf":[{"type":"string"},{"type":"null"}]},"title_status":{"type":"string","enum":["owned","custodial"]},"delegation_record_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["lot_id","lot_code","state"],"additionalProperties":true,"description":"A product listing, a lot in the API (seller_catalog_rows, 056); evidence_as_of is the count date."},"SellerOrder":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","enum":["created","authorised","released","accepted","completed","cancelled","failed"]},"qty":{"type":"integer"},"goods_cents":{"type":"integer"},"total_cents":{"type":"integer"},"fee_cents":{"type":"integer"},"lot_id":{"type":"string","format":"uuid"},"title":{"oneOf":[{"type":"string"},{"type":"null"}]},"buyer_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"fulfillment_status":{"oneOf":[{"type":"string"},{"type":"null"}]},"carrier":{"oneOf":[{"type":"string"},{"type":"null"}]},"tracking":{"oneOf":[{"type":"string"},{"type":"null"}]},"payment_status":{"oneOf":[{"type":"string"},{"type":"null"}]},"refundable_cents":{"type":"integer"},"dispute":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"null"}]}},"required":["order_id","order_number","status"],"additionalProperties":true,"description":"An order row (seller_orders_rows, 056)."},"CatalogUpsertResult":{"type":"object","properties":{"dry_run":{"type":"boolean"},"live":{"type":"boolean"},"counts":{"type":"object","properties":{"created":{"type":"integer"},"changed":{"type":"integer"},"skipped":{"type":"integer"}}},"created":{"type":"array","items":{"type":"object","properties":{"item_id":{"type":"string"},"title":{"oneOf":[{"type":"string"},{"type":"null"}]}}}},"changed":{"type":"array","items":{"type":"object","properties":{"item_id":{"type":"string"},"title":{"oneOf":[{"type":"string"},{"type":"null"}]},"lot_id":{"type":"string","format":"uuid"},"fields":{"type":"array","items":{"type":"string"}}}}},"skipped":{"type":"array","items":{"type":"object","properties":{"item_id":{"oneOf":[{"type":"string"},{"type":"null"}]},"title":{"oneOf":[{"type":"string"},{"type":"null"}]},"reason":{"type":"string","description":"unchanged, price_invalid, below_reserved, ... or the normaliser’s reasons."}}}},"warnings":{"type":"array","items":{"type":"object","properties":{"item_id":{"type":"string"},"missing":{"type":"array","items":{"type":"string"}}}}}},"required":["dry_run","counts","created","changed","skipped"]},"ReconcileResult":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"as_of":{"type":"string","format":"date-time"},"lots_checked":{"type":"integer"},"exceptions":{"type":"array","items":{"type":"object","properties":{"lot_id":{"type":"string","format":"uuid"},"lot_code":{"type":"string"},"title":{"type":"string"},"code":{"type":"string","enum":["count_mismatch","stale_count","oversold","offer_exceeds_stock","delegation_missing"]},"detail":{"type":"object","additionalProperties":true}},"required":["lot_id","code"]}}},"required":["exceptions"]},"SellerPolicyFields":{"type":"object","properties":{"acceptance_days":{"type":"integer","minimum":0,"maximum":14},"return_window_days":{"type":"integer","minimum":0,"maximum":365},"return_method":{"type":"string","enum":["by_mail","same_warehouse","no_returns"]},"restocking_fee_pct":{"type":"number","minimum":0,"maximum":100},"offer_floor_pct":{"oneOf":[{"type":"number","minimum":0,"maximum":100},{"type":"null"}]},"auctions_allowed":{"type":"boolean"},"return_terms_by_category":{"type":"object","properties":{},"description":"Return terms by product category key (the whole map is replaced): window_days, method, restocking_fee_pct each.","additionalProperties":{"type":"object","properties":{"window_days":{"type":"integer","minimum":0,"maximum":365},"method":{"type":"string","enum":["by_mail","same_warehouse","no_returns"]},"restocking_fee_pct":{"type":"number","minimum":0,"maximum":100}}}},"claim_window_days":{"oneOf":[{"type":"integer","description":"Days a shopper has to file a dispute after delivery; null uses the platform 30.","minimum":30,"maximum":365},{"type":"null"}]}},"additionalProperties":false},"SellerPolicies":{"type":"object","properties":{"policies":{"type":"object","additionalProperties":true},"exists":{"type":"boolean"},"accepted":{"type":"boolean"}},"required":["policies","accepted"]},"SellerSheet":{"type":"object","additionalProperties":true,"description":"seller_id, name, verification, fulfilled_by, tier, catalog, fulfillment, performance_90d, lifetime, ratings, policies; every rate is {value, count, n}."},"ShipFrom":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string"},"address_line1":{"type":"string"},"address_line2":{"oneOf":[{"type":"string"},{"type":"null"}]},"city":{"type":"string"},"state":{"type":"string"},"postal_code":{"oneOf":[{"type":"string"},{"type":"null"}]},"country":{"type":"string"},"phone":{"oneOf":[{"type":"string"},{"type":"null"}]},"is_default":{"type":"boolean"},"public_area":{"type":"string","description":"City, ST: the only part a buyer, a feed or another member sees."},"archived":{"type":"boolean"},"archived_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"updated_at":{"type":"string"},"products":{"type":"integer","description":"Products that name this address."},"live_products":{"type":"integer","description":"Live products that name this address (archive is refused while this is above 0)."},"products_following_default":{"type":"integer","description":"On the default: the seller-held products that name no address."}},"required":["id","label","address_line1","city","state","is_default","public_area","archived"]},"ContactSettings":{"type":"object","properties":{"phone":{"oneOf":[{"type":"string"},{"type":"null"}]},"phone_visibility":{"type":"string"},"message_notify":{"type":"string"},"notification_email":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["phone_visibility","message_notify"]},"AgentLimits":{"type":"object","properties":{"spend_cap_cents":{"oneOf":[{"type":"integer","description":"Most the key may spend on lead purchases in any 30 days, in cents; null is no cap. A new key starts at 50000 ($500).","minimum":0},{"type":"null"}]},"confirm_above_cents":{"oneOf":[{"type":"integer","description":"A payment above this, in cents, waits for the owner; null is none. A new key starts at 25000 ($250).","minimum":0},{"type":"null"}]},"confirm_actions":{"type":"array","items":{"type":"string","enum":["lead_post","message_new_member","capacity_quote","order_accept"]},"description":"Actions that wait for the owner before they run: lead_post (posting a lead), message_new_member (a first message to a new member), capacity_quote (quoting a capacity request), order_accept (accepting a capacity quote)."},"rate_per_hour":{"type":"integer","description":"Calls per hour, 1 to 600.","minimum":1,"maximum":600}},"required":["spend_cap_cents","confirm_above_cents","confirm_actions","rate_per_hour"]},"RateShop":{"type":"object","properties":{"best_cents":{"type":"integer","description":"The lowest newest price another member paid (one observation per member, 365 days)."},"lowest_cents":{"type":"integer"},"highest_cents":{"type":"integer"},"members":{"type":"integer","description":"The other members behind the range."},"best_vendor":{"oneOf":[{"type":"string","description":"The vendor on the invoice of the best price. The member is never named."},{"type":"null"}]},"newest_at":{"oneOf":[{"type":"string","description":"The newest invoice date in the range."},{"type":"null"}]},"your_position":{"oneOf":[{"type":"string","enum":["low","middle","high"],"description":"Where your price sits: low at or below the lowest, high at or above the highest."},{"type":"null"}]}},"required":["best_cents","lowest_cents","highest_cents","members"]},"ShareRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"side":{"type":"string","enum":["sent","received"]},"item_key":{"type":"string"},"item":{"oneOf":[{"type":"string","description":"The item in words."},{"type":"null"}]},"category":{"oneOf":[{"type":"string"},{"type":"null"}]},"unit":{"oneOf":[{"type":"string"},{"type":"null"}]},"requester_cents":{"type":"integer","description":"The price the member who asked pays."},"recipient_cents":{"type":"integer","description":"The best price, paid by the member asked."},"qty":{"oneOf":[{"type":"number"},{"type":"null"}]},"status":{"type":"string","enum":["requested","shared","pooled","declined","expired"]},"created_at":{"type":"string"},"answered_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"expires_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"contact":{"oneOf":[{"type":"object","properties":{"vendor_name":{"type":"string"},"rep_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"email":{"oneOf":[{"type":"string"},{"type":"null"}]},"phone":{"oneOf":[{"type":"string"},{"type":"null"}]},"price_cents":{"type":"integer"}}},{"type":"null"}]},"outcome_seen":{"oneOf":[{"type":"boolean"},{"type":"null"}]},"thread_id":{"oneOf":[{"type":"string","description":"Set once pooled: the Messages thread between the two companies.","format":"uuid"},{"type":"null"}]},"other_member":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"}},"description":"Set only once pooled; before that neither side is named."},{"type":"null"}]},"pooled_order":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["open","agreed","done","cancelled"]},"qty_requested":{"oneOf":[{"type":"number"},{"type":"null"}]},"unit_price_cents":{"type":"integer"},"handling_fee_cents":{"type":"integer"}}},{"type":"null"}]},"your_vendor":{"oneOf":[{"type":"string","description":"Received only: your vendor for the item, for the Share Contact answer."},{"type":"null"}]},"saved_contact":{"oneOf":[{"type":"object","additionalProperties":true,"description":"Received only: the contact you saved for that vendor."},{"type":"null"}]}},"required":["id","side","item_key","status"]},"ProfileService":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"catalog_key":{"oneOf":[{"type":"string"},{"type":"null"}]},"title":{"type":"string"},"body":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["id","title"]},"ProfilePerson":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"role":{"oneOf":[{"type":"string"},{"type":"null"}]},"line":{"oneOf":[{"type":"string"},{"type":"null"}]},"photo_path":{"oneOf":[{"type":"string"},{"type":"null"}]},"photo_url":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"]},"Profile":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string"},"home_market":{"oneOf":[{"type":"string"},{"type":"null"}]},"about":{"oneOf":[{"type":"string"},{"type":"null"}]},"about_source":{"oneOf":[{"type":"string"},{"type":"null"}]},"certifications":{"type":"array","items":{"type":"string"}},"logo_path":{"oneOf":[{"type":"string"},{"type":"null"}]},"logo_url":{"oneOf":[{"type":"string"},{"type":"null"}]},"services":{"type":"array","items":{"$ref":"#/components/schemas/ProfileService"}},"people":{"type":"array","items":{"$ref":"#/components/schemas/ProfilePerson"}},"contact":{"type":"object","properties":{"phone":{"oneOf":[{"type":"string"},{"type":"null"}]},"phone_visibility":{"type":"string"}}},"facilities":{"type":"integer"},"profile_url":{"type":"string"}},"required":["member_id","services","people"]},"Completeness":{"type":"object","properties":{"score":{"type":"integer"},"total":{"type":"integer"},"percent":{"type":"integer"},"next":{"oneOf":[{"type":"string"},{"type":"null"}]},"next_call":{"oneOf":[{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"},"tool":{"type":"string"}}},{"type":"null"}]},"items":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"done":{"type":"boolean"},"next_call":{"oneOf":[{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"},"tool":{"type":"string"}}},{"type":"null"}]},"note":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["key","label","done"]}}},"required":["score","total","items"]},"RateCard":{"type":"object","properties":{"node_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"verified":{"type":"boolean"},"published":{"type":"boolean"},"rate_card":{"oneOf":[{"type":"object","additionalProperties":true,"description":"status, storage_per_pallet_month_cents, handling_in_per_pallet_cents, pick_pack_per_order_cents, project_per_hour_cents, handling_out_per_pallet_cents (each optional), terms, published_at, sources."},{"type":"null"}]}},"required":["node_id","published"]},"FacilityMedia":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["image","video"]},"source":{"type":"string","enum":["upload","link"]},"path":{"oneOf":[{"type":"string"},{"type":"null"}]},"url":{"oneOf":[{"type":"string"},{"type":"null"}]},"caption":{"oneOf":[{"type":"string"},{"type":"null"}]},"public_url":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["id","kind","source"]},"Facility":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"address":{"oneOf":[{"type":"string"},{"type":"null"}]},"city":{"oneOf":[{"type":"string"},{"type":"null"}]},"state":{"oneOf":[{"type":"string"},{"type":"null"}]},"zip":{"oneOf":[{"type":"string"},{"type":"null"}]},"sqft":{"oneOf":[{"type":"integer"},{"type":"null"}]},"services":{"type":"array","items":{"type":"string"}},"lat":{"oneOf":[{"type":"number"},{"type":"null"}]},"lng":{"oneOf":[{"type":"number"},{"type":"null"}]},"geocode_source":{"oneOf":[{"type":"string"},{"type":"null"}]},"media":{"type":"array","items":{"$ref":"#/components/schemas/FacilityMedia"}},"references":{"type":"object","properties":{"deals":{"type":"integer"},"lots":{"type":"integer"}}},"pin":{"oneOf":[{"type":"object","additionalProperties":true,"description":"The pin placed by this call: status, source, lat, lng."},{"type":"null"}]}},"required":["id","name"]},"Invoice":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string"},"vendor_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"invoice_date":{"oneOf":[{"type":"string"},{"type":"null"}]},"total_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"status":{"type":"string"},"is_private":{"type":"boolean"},"failure_reason":{"oneOf":[{"type":"string"},{"type":"null"}]},"line_count":{"type":"integer"}},"required":["id","status"]},"Preferences":{"type":"object","properties":{"markets":{"type":"array","items":{"type":"string"}},"services":{"type":"array","items":{"type":"string"}},"notification_email":{"oneOf":[{"type":"string"},{"type":"null"}]},"crm_connection":{"type":"string"},"crm_sharing":{"type":"string"},"home_market":{"oneOf":[{"type":"string"},{"type":"null"}]},"wms_system":{"oneOf":[{"type":"string"},{"type":"null"}]},"crm_system":{"oneOf":[{"type":"string"},{"type":"null"}]},"other_systems":{"oneOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"systems_answered_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["markets","services"]},"MemberPublic":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string"},"home_market":{"oneOf":[{"type":"string"},{"type":"null"}]},"facilities":{"type":"integer"},"node_id":{"oneOf":[{"type":"string","description":"The node to send a capacity request to.","format":"uuid"},{"type":"null"}]}},"required":["id","name","slug"]},"ShippingRule":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"region":{"type":"string","enum":["continental_us","alaska_hawaii","us_territories","military","canada","international"]},"service":{"type":"string","enum":["standard","expedited"]},"served":{"type":"boolean","description":"false: the seller does not ship there."},"rate_kind":{"type":"string","enum":["free","flat_per_order","per_item","by_weight_band","calculated"]},"amount_cents":{"type":"integer","description":"flat_per_order and per_item: per order. by_weight_band without a product weight and calculated without a package: the amount used."},"per_item_cents":{"type":"integer","description":"per_item: added for each unit."},"bands":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"max_lb":{"type":"number"},"cents":{"type":"integer"}},"required":["max_lb","cents"]}},{"type":"null"}]},"transit_days_min":{"type":"integer"},"transit_days_max":{"type":"integer"}},"required":["region","service","served","rate_kind"]},"ShippingRuleInput":{"type":"object","properties":{"region":{"type":"string","enum":["continental_us","alaska_hawaii","us_territories","military","canada","international"]},"service":{"type":"string","enum":["standard","expedited"]},"served":{"type":"boolean"},"rate_kind":{"type":"string","enum":["free","flat_per_order","per_item","by_weight_band","calculated"]},"amount_cents":{"type":"integer"},"per_item_cents":{"type":"integer"},"bands":{"type":"array","items":{"type":"object","properties":{"max_lb":{"type":"number"},"cents":{"type":"integer"}},"required":["max_lb","cents"]}},"transit_days_min":{"type":"integer"},"transit_days_max":{"type":"integer"}},"required":["region"]},"ShippingProfile":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"is_default":{"type":"boolean"},"handling_days":{"type":"integer","description":"Days before the parcel leaves."},"handling_cents":{"type":"integer","description":"Added to a calculated rate (default 0)."},"regions_served":{"type":"array","items":{"type":"string","enum":["continental_us","alaska_hawaii","us_territories","military","canada","international"]}},"offer_count":{"type":"integer","description":"Open offers that use this profile (the default counts offers with none assigned)."},"rules":{"type":"array","items":{"$ref":"#/components/schemas/ShippingRule"}}},"required":["id","name","is_default","rules"]},"ShippingProfileInput":{"type":"object","properties":{"name":{"type":"string"},"handling_days":{"type":"integer"},"handling_cents":{"type":"integer"},"is_default":{"type":"boolean"},"rules":{"type":"array","items":{"$ref":"#/components/schemas/ShippingRuleInput"}}}},"ShippingProfiles":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ShippingProfile"}},"default_profile_id":{"type":"string","format":"uuid"},"regions_served":{"type":"array","items":{"type":"string","enum":["continental_us","alaska_hawaii","us_territories","military","canada","international"]}},"regions":{"type":"array","items":{"type":"string","enum":["continental_us","alaska_hawaii","us_territories","military","canada","international"]}}},"required":["items","default_profile_id"]},"ShippingQuote":{"type":"object","properties":{"ok":{"type":"boolean","description":"false with code destination_not_served (or weight_not_served): the seller does not ship there; served_regions lists where it does."},"refused":{"type":"boolean"},"code":{"oneOf":[{"type":"string"},{"type":"null"}]},"error_code":{"type":"string","enum":["item_not_found","item_out_of_stock","discontinued_product","invalid_shipping_address","payment_declined","merchant_error"],"description":"The shared buyer-facing code beside code or error (docs/API-PARITY.md, Machine error codes); absent when none matches."},"region":{"type":"string","enum":["continental_us","alaska_hawaii","us_territories","military","canada","international"]},"service":{"type":"string","enum":["standard","expedited"]},"requested_service":{"type":"string","enum":["standard","expedited"]},"service_fallback":{"type":"boolean","description":"Expedited was asked and is not offered: the standard rule answered."},"note":{"oneOf":[{"type":"string"},{"type":"null"}]},"rate_kind":{"type":"string","enum":["free","flat_per_order","per_item","by_weight_band","calculated"]},"shipping_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"days_min":{"oneOf":[{"type":"integer","description":"Handling plus transit."},{"type":"null"}]},"days_max":{"oneOf":[{"type":"integer"},{"type":"null"}]},"handling_days":{"type":"integer"},"transit_days_min":{"type":"integer"},"transit_days_max":{"type":"integer"},"served_regions":{"type":"array","items":{"type":"string","enum":["continental_us","alaska_hawaii","us_territories","military","canada","international"]}},"profile_id":{"type":"string","format":"uuid"},"profile_name":{"type":"string"},"needs_rating":{"type":"boolean"},"rate_id":{"oneOf":[{"type":"string","description":"Calculated: pass it as destination.rate_id to market_quote_create within 15 minutes.","format":"uuid"},{"type":"null"}]},"rating":{"oneOf":[{"type":"object","properties":{"source":{"type":"string"},"carrier":{"oneOf":[{"type":"string"},{"type":"null"}]},"carrier_service":{"oneOf":[{"type":"string"},{"type":"null"}]},"zone":{"oneOf":[{"type":"integer"},{"type":"null"}]},"cost_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"handling_cents":{"type":"integer"},"residential":{"type":"boolean"}},"additionalProperties":true},{"type":"null"}]},"requested":{"type":"integer","description":"The quantity asked for."},"available":{"type":"integer","description":"The quantity the offer can sell now."},"reason":{"oneOf":[{"type":"string","enum":["quantity","whole_lot_only","qty_rules","unavailable","destination_not_served","weight_not_served","shipping"],"description":"Why ok is false: quantity (more than available), the quantity rules, the offer is not on sale, or the shipping code."},{"type":"null"}]},"unit_price_cents":{"type":"integer"},"goods_cents":{"type":"integer","description":"The goods at this quantity, as the quote prices them."},"total_cents":{"oneOf":[{"type":"integer","description":"Goods plus shipping; null while the shipping is not known."},{"type":"null"}]},"processing_cents":{"oneOf":[{"type":"object","properties":{"card":{"type":"integer"},"ach":{"type":"integer"},"balance":{"type":"integer"}},"description":"The processing line on the total by payment method: card 2.90 percent plus 30 cents, a bank account 0.80 percent capped at $5, the balance none."},{"type":"null"}]},"buyer_total_cents":{"oneOf":[{"type":"object","properties":{"card":{"type":"integer"},"ach":{"type":"integer"},"balance":{"type":"integer"}},"description":"The total plus the processing line, by payment method."},{"type":"null"}]}},"required":["ok"],"additionalProperties":true},"CatalogImportResult":{"type":"object","properties":{"kind":{"type":"string","enum":["google_rss","google_tsv","shopify_csv","ebay_csv","acp_json","template_csv","template_json"]},"source":{"type":"string","enum":["file","url"]},"url":{"oneOf":[{"type":"string"},{"type":"null"}]},"file_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"as_of":{"type":"string","description":"The count date given to every product: the fetch or upload time.","format":"date-time"},"dry_run":{"type":"boolean"},"live":{"type":"boolean","description":"false: the seller is not live yet, so new products load as drafts."},"rows":{"type":"integer","description":"Rows read from the file."},"rows_over_limit":{"type":"integer","description":"Rows past the 5,000-row limit, not read."},"preview":{"type":"array","items":{"type":"object","properties":{"item_id":{"type":"string"},"title":{"type":"string"},"price_cents":{"type":"integer"},"quantity":{"type":"integer"},"condition":{"oneOf":[{"type":"string"},{"type":"null"}]},"brand":{"oneOf":[{"type":"string"},{"type":"null"}]},"category":{"type":"string"},"gtin":{"oneOf":[{"type":"string"},{"type":"null"}]},"photos":{"type":"integer"},"problems":{"type":"array","items":{"type":"string"}}}}},"counts":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"unchanged":{"type":"integer"},"skipped":{"type":"integer"},"not_written":{"type":"integer","description":"Rows not written because the 20 seconds ran out."}},"required":["created","updated","skipped"]},"created":{"type":"array","items":{"type":"object","properties":{"item_id":{"type":"string"},"title":{"type":"string"}}}},"changed":{"type":"array","items":{"type":"object","properties":{"item_id":{"type":"string"},"title":{"oneOf":[{"type":"string"},{"type":"null"}]},"lot_id":{"type":"string","format":"uuid"},"fields":{"type":"array","items":{"type":"string"}}}}},"skipped":{"type":"array","items":{"type":"object","properties":{"item_id":{"oneOf":[{"type":"string"},{"type":"null"}]},"title":{"oneOf":[{"type":"string"},{"type":"null"}]},"reason":{"type":"string","description":"A writer code (quantity_zero, below_reserved, ...) or the normaliser problems."}}}},"stopped":{"oneOf":[{"type":"string","enum":["row_limit","size_limit","time_limit"]},{"type":"null"}]},"limits":{"type":"object","properties":{"rows":{"type":"integer"},"bytes":{"type":"integer"},"seconds":{"type":"integer"}}},"feed_id":{"oneOf":[{"type":"string","description":"The saved feed (a URL) or file record the write was recorded under.","format":"uuid"},{"type":"null"}]},"run":{"oneOf":[{"type":"object","properties":{"run_id":{"type":"string","format":"uuid"},"feed_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"feed_status":{"oneOf":[{"type":"string"},{"type":"null"}]},"consecutive_errors":{"type":"integer"},"mailed":{"type":"boolean"}}},{"type":"null"}]}},"required":["kind","dry_run","counts","skipped"],"additionalProperties":true},"CatalogFeed":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["google_rss","google_tsv","shopify_csv","ebay_csv","acp_json","template_csv","template_json"]},"source":{"type":"string","enum":["file","url"]},"url":{"oneOf":[{"type":"string"},{"type":"null"}]},"file_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"mapping":{"type":"object","properties":{"default_quantity":{"oneOf":[{"type":"integer","description":"The quantity for rows that carry none (Google feeds)."},{"type":"null"}]}}},"schedule":{"type":"string","enum":["none","hourly","daily"]},"last_fetch_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_status":{"oneOf":[{"type":"string","enum":["ok","error"]},{"type":"null"}]},"last_error":{"oneOf":[{"type":"string"},{"type":"null"}]},"consecutive_errors":{"type":"integer","description":"Three in a row: the feed is set to error, the hourly fetch stops and the seller gets one email."},"counts":{"type":"object","additionalProperties":true},"next_fetch_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"runs":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"started_at":{"type":"string"},"finished_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"status":{"type":"string"},"trigger":{"type":"string"},"created":{"type":"integer"},"updated":{"type":"integer"},"skipped":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","additionalProperties":true}},"counts":{"type":"object","additionalProperties":true}}}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["id","kind","schedule"],"additionalProperties":true},"DealFact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deal_id":{"type":"string","format":"uuid"},"field":{"type":"string","enum":["service","location","volume","product","timing","sku_count"]},"value":{"type":"string","description":"The value as the member reads it: \"Pick and pack\", \"Houston, TX or Dallas, TX\", \"2,000 orders a month\"."},"value_norm":{"description":"service: a catalog key (storage_ambient, pick_pack, fulfillment, cross_dock, transload, kitting, returns, cold_storage, hazmat) or an array of them; location: \"City, ST\", an array of them, or \"anywhere\"; volume: {per_month, unit orders|units|pallets|skus, direction inbound|outbound for pallets}; product: the text; timing: {start_date (when known), text}; sku_count: {count}."},"source_kind":{"type":"string","enum":["notes","ghl_field","typed"]},"source_text":{"type":"string","description":"The whole sentence the fact came from, under 300 characters."},"source_ref":{"oneOf":[{"type":"string","description":"The note date (YYYY-MM-DD), the GoHighLevel field name, or description."},{"type":"null"}]},"confidence":{"type":"string","enum":["low","medium","high"]},"status":{"type":"string","enum":["suggested","confirmed","rejected"]},"decided_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","deal_id","field","value","value_norm","source_kind","source_text","confidence","status"]},"DealFacts":{"type":"object","properties":{"deal_id":{"type":"string","format":"uuid"},"items":{"type":"array","items":{"$ref":"#/components/schemas/DealFact"}},"ready":{"type":"boolean","description":"True when service, location, volume, product and timing are each confirmed."},"missing":{"type":"array","items":{"type":"string","enum":["service","location","volume","product","timing"]}}},"required":["deal_id","items","ready","missing"]},"LeadIntake":{"type":"object","properties":{"ref":{"type":"integer","description":"The reference of the intake, as in \"Lead CB-1042\"."},"outcome":{"type":"string","enum":["drafted","parsed","duplicate","refused","updated","deal","failed"],"description":"drafted: a draft lead was made (not listed). parsed: the row in Leads was made or found, and items are still needed before a draft. duplicate: the same prospect was posted in the last 90 days (nothing new was made). refused: the CRM marks the prospect do-not-solicit, won or lost. deal: the row in Leads is there and the draft was refused (error says why)."},"deal_id":{"oneOf":[{"type":"string","description":"The row in Leads (a CRM deal, source email).","format":"uuid"},{"type":"null"}]},"lead_id":{"oneOf":[{"type":"string","description":"The draft lead, when the five posting items are known.","format":"uuid"},{"type":"null"}]},"needed":{"type":"array","items":{"type":"string","enum":["company","need","service","location","price"]}},"questions":{"type":"array","items":{"type":"string"}},"quality":{"oneOf":[{"type":"object","properties":{"score":{"type":"integer"},"of":{"type":"integer"}}},{"type":"null"}]},"price_from":{"oneOf":[{"type":"string","enum":["subject","notes","defaults"],"description":"Where the price came from: the subject or first line of the text (for this lead only), the text, or the saved Lead defaults."},{"type":"null"}]},"duplicate":{"oneOf":[{"type":"object","additionalProperties":true},{"type":"null"}]},"refusal":{"oneOf":[{"type":"string"},{"type":"null"}]},"edit_url":{"oneOf":[{"type":"string","description":"The draft on the Post page."},{"type":"null"}]},"card":{"type":"object","additionalProperties":true,"description":"The card as a buyer will see it."},"posting":{"type":"object","additionalProperties":true,"description":"The posting fields read from the text."},"attributes":{"type":"object","additionalProperties":true,"description":"The lead attributes read from the text (src/lib/leadAttributes.ts groups)."},"field_sources":{"type":"object","additionalProperties":true,"description":"Every field the text supplied, marked email."}},"required":["ref","outcome","needed","questions"]},"KeyLimits":{"type":"object","properties":{"key_id":{"type":"string","format":"uuid"},"key_prefix":{"type":"string"},"label":{"type":"string"},"scope":{"type":"string","enum":["warehouse","seller","owner"]},"limits":{"$ref":"#/components/schemas/AgentLimits"},"limits_set":{"type":"boolean","description":"False for a key issued before the limits existed and never changed: no cap and no confirm list."},"spent_30d_cents":{"type":"integer","description":"What the key spent on lead purchases in the last 30 days."},"spend_ceiling_action_cents":{"oneOf":[{"type":"integer","description":"The per-purchase ceiling of the approval card (063)."},{"type":"null"}]},"spend_ceiling_day_cents":{"oneOf":[{"type":"integer","description":"The per-day ceiling of the approval card (063)."},{"type":"null"}]},"approval_areas":{"type":"array","items":{"type":"string"}},"limits_updated_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"pending":{"type":"integer","description":"Actions of this key waiting for the owner."}},"required":["key_id","limits","limits_set","spent_30d_cents","pending"]},"PendingAction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"key_id":{"type":"string","format":"uuid"},"key_label":{"type":"string"},"key_prefix":{"type":"string"},"action":{"type":"string","description":"The API action that waits: lead_claim, lead_buy, lead_claim_quote, lead_post, message_request, capacity_quote or capacity_accept."},"args":{"type":"object","additionalProperties":true,"description":"The arguments it was sent with; an approved action runs with these."},"amount_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"reason":{"type":"string","enum":["over_spend_cap","over_confirm_above","confirm_action","over_order_max"]},"limit_cents":{"oneOf":[{"type":"integer","description":"The cap or the confirm amount it passed."},{"type":"null"}]},"confirm_action":{"oneOf":[{"type":"string","enum":["lead_post","message_new_member","capacity_quote","order_accept"]},{"type":"null"}]},"status":{"type":"string","enum":["pending","approved","running","done","failed","declined"]},"decision":{"oneOf":[{"type":"string","enum":["approved","declined"]},{"type":"null"}]},"decided_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"ran_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"result":{"oneOf":[{"type":"object","additionalProperties":true,"description":"What the action returned when it ran, or its error."},{"type":"null"}]}},"required":["id","action","reason","status"]},"PendingOwnerConfirmation":{"type":"object","properties":{"status":{"type":"string","enum":["pending_owner_confirmation"]},"pending_id":{"type":"string","description":"The waiting action; GET /keys/{id}/pending lists it.","format":"uuid"},"reason":{"type":"string","enum":["over_spend_cap","over_confirm_above","confirm_action","over_order_max"]},"amount_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"detail":{"type":"string"}},"required":["status","pending_id","reason"]},"NetworkNow":{"type":"object","properties":{"members_verified":{"type":"integer","description":"Verified members."},"open_leads_week":{"type":"integer","description":"Leads listed on the exchange in the last 7 days."},"prices_posted_total":{"type":"integer","description":"Prices read from verified members’ parsed invoices."},"confirmed_savings_month_cents":{"type":"integer","description":"Savings members confirmed this calendar month, Central time."},"as_of":{"type":"string","format":"date-time"}},"required":["members_verified","open_leads_week","prices_posted_total","confirmed_savings_month_cents"]},"KeyActivity":{"type":"object","properties":{"activity":{"type":"string","description":"leads, crm, capacity, messages, costs, network, settings, profile, payments (warehouse); catalog, orders, policies, payouts, performance, delegations, entity, payments (seller)."},"label":{"type":"string","description":"The name the screens use."},"level":{"type":"string","enum":["none","read","write"],"description":"read is Read only; write is Can act. For payments, read is the same as none (Off)."},"on":{"type":"boolean","description":"True when the key can act in this activity (payments: can pay)."},"can_act":{"type":"boolean","description":"False for an activity with nothing to act on (seller payouts and performance)."}},"required":["activity","label","level","on","can_act"]},"KeyPermissions":{"type":"object","properties":{"key_id":{"type":"string","format":"uuid"},"key_prefix":{"type":"string"},"label":{"type":"string"},"scope":{"type":"string","enum":["warehouse","seller","owner"]},"kind":{"type":"string","enum":["warehouse","seller"]},"permissions":{"type":"object","additionalProperties":{"type":"string","enum":["none","read","write"]},"description":"Every activity of the kind with its level."},"activities":{"type":"array","items":{"$ref":"#/components/schemas/KeyActivity"}},"can_raise":{"type":"boolean","description":"True only for the owner signed in; a key may only lower its own activities."},"permissions_updated_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"hint":{"type":"string","description":"The sentence an agent can relay to its owner: where an activity is turned on."}},"required":["key_id","kind","permissions","activities","can_raise","hint"]},"CostSavings":{"type":"object","properties":{"basis":{"type":"string","enum":["confirmed_quote_projection"],"description":"Every figure here is a projection from a confirmed price over the yearly use; savings realized on purchases are GET /costs/summary realized_year_cents."},"note":{"type":"string"},"year":{"type":"integer"},"year_cents":{"type":"integer","description":"Projected yearly savings of the prices confirmed this calendar year (Central time)."},"month_cents":{"type":"integer","description":"The same for the prices confirmed this month."},"count_year":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"source":{"type":"string","enum":["request","match"]},"source_request_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"match_note_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"category":{"oneOf":[{"type":"string"},{"type":"null"}]},"item":{"type":"string"},"vendor":{"oneOf":[{"type":"string"},{"type":"null"}]},"unit":{"oneOf":[{"type":"string"},{"type":"null"}]},"your_price_cents":{"type":"integer"},"confirmed_price_cents":{"type":"integer"},"annual_qty":{"type":"number"},"annual_basis":{"oneOf":[{"type":"string","enum":["stated","given","extrapolated"]},{"type":"null"}]},"saving_cents":{"type":"integer","description":"(your price minus the confirmed price) times the yearly quantity: a projection."},"confirmed_at":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["confirmed_quote"]}}}}},"required":["year_cents","month_cents","items"]},"SignupStarted":{"type":"object","properties":{"signup_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["warehouse","seller","buyer"]},"email":{"type":"string","format":"email"},"code_expires_at":{"type":"string","description":"The code lives 30 minutes.","format":"date-time"},"sent":{"type":"string"},"next":{"type":"string"}},"required":["signup_id","kind","email","code_expires_at"]},"SignupConfirmed":{"type":"object","properties":{"member":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"kind":{"type":"string","enum":["warehouse","seller","buyer"]},"status":{"type":"string","description":"provisional until verification (a warehouse) or until selling is live (a seller); a buyer (the Shop) is verified at once."}},"required":["id","name","kind","status"]},"key":{"type":"string","description":"The agent link key: send it as Authorization: Bearer. Shown once."},"key_id":{"type":"string","format":"uuid"},"key_prefix":{"type":"string"},"expires_at":{"type":"string","description":"90 days from now; the owner renews or revokes it at Agent access.","format":"date-time"},"created_login":{"type":"boolean","description":"True when this email had no login; the owner signs in later with the email code."},"agent_link":{"type":"string","description":"https://commercebook.ai/agent/<token>"},"mcp":{"type":"object","properties":{"url":{"type":"string"},"transport":{"type":"string"},"header":{"type":"string"}}},"document":{"oneOf":[{"type":"string","description":"The member’s agent document, Markdown, as the agent link serves it."},{"type":"null"}]},"next":{"type":"string"}},"required":["member","key","key_id","agent_link"]},"FeedbackRecorded":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","description":"buyer for a note with no key; otherwise the key member’s kind.","enum":["buyer","warehouse","seller"]},"recorded_against_key":{"type":"boolean"},"next":{"type":"string"}},"required":["id","kind","recorded_against_key"]},"PaymentMethods":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","description":"card","enum":["card"]},"brand":{"oneOf":[{"type":"string"},{"type":"null"}]},"last4":{"oneOf":[{"type":"string"},{"type":"null"}]},"exp_month":{"oneOf":[{"type":"integer"},{"type":"null"}]},"exp_year":{"oneOf":[{"type":"integer"},{"type":"null"}]},"is_default":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}},"required":["id","type","is_default"]}},"balance_cents":{"type":"integer","description":"The balance held by Stripe, as last reported."},"hint":{"type":"string","description":"Where the owner saves a card and funds the balance."}},"required":["items"]},"FundingInstructions":{"type":"object","properties":{"routing_number":{"oneOf":[{"type":"string"},{"type":"null"}]},"account_number":{"oneOf":[{"type":"string"},{"type":"null"}]},"account_holder":{"oneOf":[{"type":"string"},{"type":"null"}]},"bank_name":{"oneOf":[{"type":"string"},{"type":"null"}]},"networks":{"type":"array","items":{"type":"string","description":"ach, domestic_wire_us."}},"swift":{"oneOf":[{"type":"object","properties":{"bic":{"oneOf":[{"type":"string"},{"type":"null"}]},"account_number":{"oneOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]}}},"Balance":{"type":"object","properties":{"balance_cents":{"type":"integer","description":"Available now, held by Stripe as the member’s customer cash balance."},"balance_updated_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"has_customer":{"type":"boolean","description":"False until funding instructions were asked for once."},"events":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"funded, applied_to_payment, refunded_from_payment, return_initiated, funding_reversed and the other Stripe cash balance types."},"net_amount_cents":{"type":"integer"},"ending_balance_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"occurred_at":{"type":"string"}}}},"open_return":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount_cents":{"type":"integer"},"status":{"type":"string"},"created_at":{"type":"string"}}},{"type":"null"}]},"funding_instructions":{"oneOf":[{"$ref":"#/components/schemas/FundingInstructions"},{"type":"null"}]},"aging_days":{"type":"integer","description":"Stripe returns an unused balance to the sender’s bank after this many days (75)."},"configured":{"type":"boolean","description":"False when the deployment has no Stripe keys (the mirror only)."}},"required":["balance_cents","configured"]},"BalanceReturn":{"type":"object","properties":{"return":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount_cents":{"type":"integer"},"status":{"type":"string"},"created_at":{"type":"string"}}},"refund_status":{"oneOf":[{"type":"string","description":"requires_action until the owner gives Stripe the bank details."},{"type":"null"}]},"origin":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"PaidClaim":{"type":"object","properties":{"status":{"type":"string","description":"paid","enum":["paid"]},"method":{"type":"string","enum":["card","balance"]},"payment":{"type":"string","enum":["card","balance"]},"claim_id":{"type":"string","format":"uuid"},"deal_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"lead_id":{"type":"string","format":"uuid"},"amount_cents":{"type":"integer","description":"What the buyer paid: the price plus the processing line (card) or the price (balance)."},"price_cents":{"type":"integer"},"processing_cents":{"type":"integer","description":"2.90 percent plus 30 cents on a card; 0 from the balance."},"payment_intent_id":{"type":"string"},"mode":{"type":"string"}},"required":["status","claim_id","amount_cents","processing_cents","method"]},"MarketLotSummary":{"type":"object","properties":{"lot_id":{"type":"string","format":"uuid"},"offer_id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"title":{"type":"string"},"brand":{"oneOf":[{"type":"string"},{"type":"null"}]},"category":{"oneOf":[{"type":"string"},{"type":"null"}]},"mpn":{"oneOf":[{"type":"string"},{"type":"null"}]},"condition":{"oneOf":[{"type":"string"},{"type":"null"}]},"unit_price_cents":{"type":"integer"},"currency":{"type":"string"},"qty_available":{"type":"integer"},"min_qty":{"type":"integer"},"fulfillment_options":{"type":"array","items":{"type":"string","enum":["pickup","ship"]}},"ships_to":{"type":"array","items":{"type":"string","description":"Two-letter state; empty means no limit."}},"photo":{"oneOf":[{"type":"string"},{"type":"null"}]},"seller_name":{"type":"string"},"seller_slug":{"type":"string"},"seller_verified":{"type":"boolean"},"lot_path":{"type":"string"},"url":{"type":"string"},"description_short":{"type":"string"},"score":{"type":"integer","description":"Relevance to q."},"seller_tier":{"type":"string","description":"new, standard or trusted, computed by CommerceBook.","enum":["new","standard","trusted"]},"seller_founding":{"type":"boolean","description":"Verified before the founding period ended."},"seller_numbers":{"$ref":"#/components/schemas/SellerNumbers"},"seller_url":{"type":"string","description":"The seller record page."},"matched_terms":{"type":"integer","description":"How many words of the query the product matches (search only)."},"pack_size":{"oneOf":[{"type":"integer","description":"Units in one pack when the product is sold in packs (above 1); price_text then reads the price per pack."},{"type":"null"}]},"ship_from_state":{"oneOf":[{"type":"string","description":"The state the goods leave from."},{"type":"null"}]},"ships_from":{"oneOf":[{"type":"object","properties":{"city":{"oneOf":[{"type":"string"},{"type":"null"}]},"state":{"oneOf":[{"type":"string","description":"Two letters."},{"type":"null"}]},"area":{"oneOf":[{"type":"string","description":"City, ST (the state alone when no city is known)."},{"type":"null"}]},"held_by":{"type":"string","description":"seller: the seller ships it from its own address; warehouse: a member warehouse stores and ships it.","enum":["seller","warehouse"]}},"required":["state","area","held_by"]},{"type":"null"}]},"goods_kind":{"type":"string","description":"new, used, or surplus (new goods in unopened packaging sold below list). A used or surplus product always carries condition, at least two photos, weight, size and its own return terms.","enum":["new","used","surplus"]},"pickup":{"oneOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"city":{"oneOf":[{"type":"string"},{"type":"null"}]},"state":{"oneOf":[{"type":"string"},{"type":"null"}]},"zip3":{"oneOf":[{"type":"string","description":"The first three digits of the pickup ZIP: a buyer in the same ZIP area can pick up."},{"type":"null"}]},"line":{"type":"string","description":"Pickup free in <city>."},"near":{"oneOf":[{"type":"boolean","description":"With a ZIP: true when the buyer is in the same 3-digit ZIP area as the pickup address."},{"type":"null"}]}},"required":["enabled","line"]},{"type":"null"}]},"to_zip":{"type":"object","properties":{"zip":{"type":"string"},"status":{"type":"string","description":"quoted, not_served, pickup (no shipping, pickup near the ZIP) or unknown (quoted at checkout).","enum":["quoted","not_served","pickup","unknown"]},"shipping_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"delivered_cents":{"oneOf":[{"type":"integer","description":"The unit price plus the shipping to the ZIP (at the minimum quantity)."},{"type":"null"}]},"pickup_near":{"oneOf":[{"type":"boolean"},{"type":"null"}]},"line":{"type":"string","description":"For example \"$5.00 + $8.40 shipping to 77008\", \"Pickup free in Houston\" or \"Shipping quoted at checkout\"."}},"required":["zip","status","line"],"description":"With zip: the shipping of the item to that ZIP (the first 40 items are priced)."},"price_mode":{"type":"string","enum":["fixed","schedule"],"description":"schedule: the price falls with the quantity; a quote at a quantity returns that price."},"schedule_kind":{"oneOf":[{"type":"string","enum":["volume","graduated"],"description":"How the tiers apply (default volume). volume: every unit is priced at the price of the highest tier the quantity reaches. graduated: the units within each tier are priced at that tier’s price."},{"type":"null"}]},"price_schedule":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"min_qty":{"type":"integer","minimum":1},"unit_price_cents":{"type":"integer","minimum":1}},"required":["min_qty","unit_price_cents"]},"minItems":2,"maxItems":10,"description":"The tiers, ascending by min_qty: {min_qty, unit_price_cents}; the first tier starts at min_qty 1 (or at the offer minimum) and its price is the unit price; each later tier has a larger min_qty and a lower price; 2 to 10 tiers. unit_price_cents is the first tier."},{"type":"null"}]},"price_text":{"type":"string","description":"With a schedule only: the schedule in words, for example \"from $2.40 each, 50 or more at $1.90 each\"."}},"required":["lot_id","offer_id","title","unit_price_cents","qty_available"]},"MarketSearch":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MarketLotSummary"}},"count":{"type":"integer","description":"Every match, before the limit."},"filters":{"type":"object","properties":{},"additionalProperties":true},"category_matches":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"terms":{"type":"array","items":{"type":"string"}},"products":{"type":"integer"},"open_requests":{"type":"integer"},"sellers_told":{"type":"integer","description":"Sellers a public request in the category reaches today."},"line":{"oneOf":[{"type":"string","description":"no products in <category>; <n> open requests; post one, when the category has no product."},{"type":"null"}]},"post":{"type":"string"}}}},"nearest_categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"products":{"type":"integer"},"open_requests":{"type":"integer"},"url":{"type":"string"},"search":{"type":"string"}}}},"no_match":{"type":"boolean","description":"true when the words of the query match no product: items is empty and nearest_categories names the nearest categories."},"next":{"type":"string","description":"When nothing matched: the request to post instead."},"warnings":{"type":"array","items":{"type":"string","description":"An unknown query parameter, named; it was not applied."}}},"required":["items","count"]},"MarketLot":{"type":"object","properties":{"lot_id":{"type":"string","format":"uuid"},"offer_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"description":{"oneOf":[{"type":"string"},{"type":"null"}]},"condition":{"oneOf":[{"type":"string"},{"type":"null"}]},"qty_available":{"type":"integer"},"unit_price_cents":{"type":"integer"},"min_qty":{"type":"integer"},"qty_increment":{"type":"integer"},"ships_to":{"type":"array","items":{"type":"string"}},"shipping":{"type":"object","properties":{},"additionalProperties":true},"photos":{"type":"array","items":{"type":"string"}},"seller_name":{"type":"string"},"seller_verified":{"type":"boolean"},"evidence_as_of":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"url":{"type":"string"},"ship_from_state":{"oneOf":[{"type":"string","description":"The state the goods leave from."},{"type":"null"}]},"ships_from":{"oneOf":[{"type":"object","properties":{"city":{"oneOf":[{"type":"string"},{"type":"null"}]},"state":{"oneOf":[{"type":"string","description":"Two letters."},{"type":"null"}]},"area":{"oneOf":[{"type":"string","description":"City, ST (the state alone when no city is known)."},{"type":"null"}]},"held_by":{"type":"string","description":"seller: the seller ships it from its own address; warehouse: a member warehouse stores and ships it.","enum":["seller","warehouse"]}},"required":["state","area","held_by"]},{"type":"null"}]},"goods_kind":{"type":"string","description":"new, used, or surplus (new goods in unopened packaging sold below list). A used or surplus product always carries condition, at least two photos, weight, size and its own return terms.","enum":["new","used","surplus"]},"pickup":{"oneOf":[{"type":"object","properties":{"enabled":{"type":"boolean"},"city":{"oneOf":[{"type":"string"},{"type":"null"}]},"state":{"oneOf":[{"type":"string"},{"type":"null"}]},"zip3":{"oneOf":[{"type":"string","description":"The first three digits of the pickup ZIP: a buyer in the same ZIP area can pick up."},{"type":"null"}]},"line":{"type":"string","description":"Pickup free in <city>."},"near":{"oneOf":[{"type":"boolean","description":"With a ZIP: true when the buyer is in the same 3-digit ZIP area as the pickup address."},{"type":"null"}]}},"required":["enabled","line"]},{"type":"null"}]},"return_terms":{"type":"object","properties":{"method":{"type":"string"},"window_days":{"type":"integer"},"restocking_fee_pct":{"type":"number"}},"additionalProperties":true},"price_mode":{"type":"string","enum":["fixed","schedule"],"description":"schedule: the price falls with the quantity; a quote at a quantity returns that price."},"schedule_kind":{"oneOf":[{"type":"string","enum":["volume","graduated"],"description":"How the tiers apply (default volume). volume: every unit is priced at the price of the highest tier the quantity reaches. graduated: the units within each tier are priced at that tier’s price."},{"type":"null"}]},"price_schedule":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"min_qty":{"type":"integer","minimum":1},"unit_price_cents":{"type":"integer","minimum":1}},"required":["min_qty","unit_price_cents"]},"minItems":2,"maxItems":10,"description":"The tiers, ascending by min_qty: {min_qty, unit_price_cents}; the first tier starts at min_qty 1 (or at the offer minimum) and its price is the unit price; each later tier has a larger min_qty and a lower price; 2 to 10 tiers. unit_price_cents is the first tier."},{"type":"null"}]},"price_text":{"type":"string","description":"With a schedule only: the schedule in words, for example \"from $2.40 each, 50 or more at $1.90 each\"."},"offers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":true}}},"required":["lot_id","title","offers"],"additionalProperties":true},"SellerMetric":{"type":"object","properties":{"n":{"type":"integer"},"of":{"type":"integer","description":"The orders the metric is built on."},"rate":{"oneOf":[{"type":"number","description":"n / of, 0 to 1; null at 0 orders."},{"type":"null"}]},"shown_as":{"type":"string","enum":["count","percent"]}},"required":["n","of","rate","shown_as"],"additionalProperties":true},"SellerNumbers":{"type":"object","properties":{"orders":{"type":"integer","description":"Lifetime orders accepted."},"delivered":{"$ref":"#/components/schemas/SellerMetric"},"on_time":{"$ref":"#/components/schemas/SellerMetric"},"accuracy":{"$ref":"#/components/schemas/SellerMetric"},"min_orders":{"type":"integer"}},"required":["delivered","on_time","accuracy"]},"SellerWindow":{"type":"object","properties":{"since":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"orders":{"type":"integer"},"delivered":{"$ref":"#/components/schemas/SellerMetric"},"on_time":{"$ref":"#/components/schemas/SellerMetric"},"accuracy":{"$ref":"#/components/schemas/SellerMetric"},"cancel":{"$ref":"#/components/schemas/SellerMetric"},"dispute":{"$ref":"#/components/schemas/SellerMetric"},"refund":{"$ref":"#/components/schemas/SellerMetric"}},"required":["orders","delivered","on_time","accuracy"],"additionalProperties":true},"SellerRecord":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"identity":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"verified":{"type":"boolean"},"member_since":{"type":"string","description":"YYYY-MM."},"fulfilled_by":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"verified":{"type":"boolean"}}}}}},"catalog":{"type":"object","properties":{"live_products":{"type":"integer"},"categories":{"type":"array","items":{"type":"string"}}}},"performance_90d":{"$ref":"#/components/schemas/SellerWindow"},"performance_lifetime":{"$ref":"#/components/schemas/SellerWindow"},"ratings":{"type":"object","properties":{"bot_confirmed":{"type":"object","properties":{"n":{"type":"integer","description":"Accepted orders with no condition or shortage dispute."},"of":{"type":"integer","description":"Accepted orders."},"ok_rate":{"oneOf":[{"type":"number"},{"type":"null"}]},"shown_as":{"type":"string","enum":["count","percent"]}},"additionalProperties":true},"human":{"type":"object","properties":{"n":{"type":"integer"},"product_avg":{"oneOf":[{"type":"number"},{"type":"null"}]},"seller_avg":{"oneOf":[{"type":"number"},{"type":"null"}]}}}}},"tier":{"type":"string","description":"Computed, never written by the seller: new until rules.new_orders accepted orders and rules.new_days days; trusted at rules.trusted_orders orders with on time and accuracy at or above rules.trusted_rate, disputes at or below rules.trusted_dispute_rate and the Verified badge; standard otherwise.","enum":["new","standard","trusted"]},"founding":{"type":"boolean","description":"Verified before rules.founding_until; shown beside the tier."},"policies":{"type":"object","properties":{"return_terms":{"type":"object","properties":{},"additionalProperties":true},"claim_window_days":{"type":"integer","description":"Days from delivery a shopper has to file a dispute."},"payout_days":{"type":"integer","description":"Business days after delivery the seller is paid unless a dispute is open."},"offers_below_list":{"type":"boolean"},"floor_pct":{"oneOf":[{"type":"number"},{"type":"null"}]},"auctions_allowed":{"type":"boolean"}}},"rules":{"type":"object","properties":{"min_orders":{"type":"integer"},"new_orders":{"type":"integer"},"new_days":{"type":"integer"},"trusted_orders":{"type":"integer"},"trusted_rate":{"type":"number"},"trusted_dispute_rate":{"type":"number"},"founding_until":{"type":"string","format":"date"}}},"window":{"type":"object","properties":{"performance_90d_since":{"type":"string","format":"date-time"},"performance_lifetime_since":{"type":"null"}}},"computed_at":{"type":"string","format":"date-time"},"url":{"type":"string"},"markdown_url":{"type":"string"},"api_url":{"type":"string"}},"required":["slug","name","tier","performance_90d","performance_lifetime","computed_at"]},"MarketQuote":{"type":"object","properties":{"quote_id":{"type":"string","format":"uuid"},"status":{"type":"string","description":"open, or draft when needs_information names what is missing (the destination)."},"qty":{"type":"integer"},"unit_price_cents":{"type":"integer"},"goods_cents":{"type":"integer"},"shipping_cents":{"type":"integer"},"tax_cents":{"type":"integer"},"total_cents":{"type":"integer"},"fee_cents":{"type":"integer"},"expires_at":{"type":"string","format":"date-time"},"needs_information":{"oneOf":[{"type":"string"},{"type":"null"}]},"shipping":{"oneOf":[{"type":"object","properties":{},"additionalProperties":true},{"type":"null"}]}},"required":["quote_id","status","total_cents","expires_at"],"additionalProperties":true},"MarketOrderPlaced":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","description":"accepted: the order is placed and authorised (the card is held, not charged, or the balance paid) and the seller is told; the order itself reads authorised.","enum":["accepted","processing"]},"method":{"type":"string","enum":["balance","card"]},"payment":{"type":"string","description":"paid (balance) or card_held."},"buyer_total_cents":{"type":"integer","description":"The quote total plus the card fee (processing)."},"processing_cents":{"type":"integer","description":"2.90 percent plus 30 cents on a card; 0 from the balance."},"payment_intent_id":{"type":"string"},"replayed":{"type":"boolean"}},"required":["order_id","status","buyer_total_cents","processing_cents"]},"MarketOrder":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string","enum":["created","authorised","released","accepted","completed","cancelled","failed"]},"created_at":{"type":"string","format":"date-time"},"qty":{"type":"integer"},"goods_cents":{"type":"integer"},"shipping_cents":{"type":"integer"},"tax_cents":{"type":"integer"},"total_cents":{"type":"integer"},"processing_cents":{"type":"integer"},"buyer_total_cents":{"type":"integer"},"payment_method":{"type":"string"},"acceptance_window_ends_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"cancel_reason":{"oneOf":[{"type":"string"},{"type":"null"}]},"by_agent":{"type":"boolean"},"offer_id":{"type":"string","format":"uuid"},"lot_id":{"type":"string","format":"uuid"},"title":{"oneOf":[{"type":"string"},{"type":"null"}]},"lot_path":{"oneOf":[{"type":"string"},{"type":"null"}]},"seller":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"}}},"payment":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","description":"pending, authorised, captured, refunded, voided, failed or disputed."},"method":{"type":"string","enum":["stripe_card","stripe_ach","stripe_balance","payment_stub"]},"line":{"type":"string","description":"card_held (held, not charged, until the seller releases the goods), bank_settling (about 4 business days), paid, failed, refunded, voided or pending."},"provider_status":{"oneOf":[{"type":"string"},{"type":"null"}]},"authorised_until":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"captured_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"refunded_cents":{"type":"integer"}}},{"type":"null"}]},"fulfillment":{"oneOf":[{"type":"object","properties":{"status":{"type":"string"},"method":{"type":"string"},"carrier":{"oneOf":[{"type":"string"},{"type":"null"}]},"tracking":{"oneOf":[{"type":"string"},{"type":"null"}]},"released_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"delivered_at":{"oneOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"dispute":{"oneOf":[{"type":"object","properties":{"dispute_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"reason":{"type":"string"},"created_at":{"type":"string"}}},{"type":"null"}]},"rating":{"oneOf":[{"type":"object","properties":{"product_score":{"type":"integer"},"seller_score":{"type":"integer"},"note":{"oneOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]}},"required":["order_id","order_number","status","total_cents"]},"MarketSheet":{"type":"object","properties":{"sheet_id":{"type":"string","format":"uuid"},"url":{"type":"string","description":"https://commercebook.ai/sheet/<token>: the page, readable by anyone with the link; noindex unless public."},"expires_at":{"type":"string","description":"30 days after creation; the link answers 404 after.","format":"date-time"},"markdown":{"type":"string","description":"The whole sheet as plain text, for an agent that cannot show a page."},"json":{"type":"object","properties":{"sheet_id":{"type":"string","format":"uuid"},"url":{"type":"string"},"title":{"oneOf":[{"type":"string"},{"type":"null"}]},"query":{"type":"string"},"brief":{"type":"object","properties":{"budget":{"oneOf":[{"type":"string"},{"type":"null"}]},"deadline":{"oneOf":[{"type":"string"},{"type":"null"}]}}},"ship_to":{"type":"object","properties":{"postal_code":{"type":"string"},"state":{"type":"string"}}},"prepared_by":{"oneOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"expires_at":{"type":"string"},"public":{"type":"boolean"},"opened_count":{"type":"integer"},"compare":{"type":"array","items":{"type":"string"}},"notes":{"oneOf":[{"type":"string"},{"type":"null"}]},"items":{"type":"array","items":{"type":"object","properties":{"rank":{"type":"integer"},"offer_id":{"type":"string","format":"uuid"},"lot_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"quantity":{"type":"integer"},"state":{"type":"string","description":"available, short (fewer available than the sheet asks) or sold_out; re-read on every read.","enum":["available","short","sold_out"]},"reason":{"type":"string","description":"The agent’s words."},"tradeoff":{"oneOf":[{"type":"string"},{"type":"null"}]},"unit_price_cents":{"type":"integer","description":"Live."},"price_changed_from_cents":{"oneOf":[{"type":"integer","description":"The price when the sheet was made, when it has changed since."},{"type":"null"}]},"qty_available":{"type":"integer"},"condition":{"oneOf":[{"type":"string"},{"type":"null"}]},"ships_from":{"oneOf":[{"type":"object","properties":{"city":{"oneOf":[{"type":"string"},{"type":"null"}]},"state":{"oneOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"seller":{"type":"object","properties":{"name":{"oneOf":[{"type":"string"},{"type":"null"}]},"slug":{"oneOf":[{"type":"string"},{"type":"null"}]},"verified":{"type":"boolean"}}},"shipping":{"type":"object","properties":{"method":{"type":"string","enum":["ship","pickup"]},"status":{"type":"string","enum":["quoted","pickup_only","not_served","needs_zip","freight"]},"shipping_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"quoted_at":{"type":"string"}},"additionalProperties":true},"total_cents":{"oneOf":[{"type":"integer","description":"Goods at the live price plus the shipping as quoted."},{"type":"null"}]},"buyer_total_cents":{"oneOf":[{"type":"object","properties":{"card":{"type":"integer"},"ach":{"type":"integer"},"balance":{"type":"integer"}}},{"type":"null"}]},"specs":{"type":"object","properties":{},"additionalProperties":{"oneOf":[{"type":"string"},{"type":"null"}]},"description":"The seller’s value for each compare name; null is not stated by the seller."},"lot_url":{"oneOf":[{"type":"string"},{"type":"null"}]},"buy_url":{"type":"string","description":"/cart/<offer_id>:<qty>?sheet=<token>: the payment step after sign-in."},"ask_url":{"type":"string"},"order_via_agent":{"type":"object","properties":{"tool":{"type":"string"},"args":{"type":"object","properties":{},"additionalProperties":true},"then":{"type":"object","properties":{"tool":{"type":"string"},"args":{"type":"object","properties":{},"additionalProperties":true}}},"needs":{"type":"string"}},"additionalProperties":true}},"additionalProperties":true}}},"additionalProperties":true}},"required":["sheet_id","url","markdown","json"]},"MarketSheetSummary":{"type":"object","properties":{"sheet_id":{"type":"string","format":"uuid"},"url":{"type":"string"},"title":{"oneOf":[{"type":"string"},{"type":"null"}]},"query":{"type":"string"},"created_at":{"type":"string"},"expires_at":{"type":"string"},"opened_at":{"oneOf":[{"type":"string"},{"type":"null"}]},"opened_count":{"type":"integer"},"by_agent":{"type":"boolean"},"item_count":{"type":"integer"},"top_choice":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"title":{"oneOf":[{"type":"string"},{"type":"null"}]},"unit_price_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"quantity":{"type":"integer"}}}},"required":["sheet_id","url","query"]},"CarrierAddress":{"type":"object","properties":{"name":{"type":"string"},"company":{"type":"string"},"street1":{"type":"string","description":"Or line1."},"street2":{"type":"string","description":"Or line2."},"city":{"type":"string"},"state":{"type":"string","description":"Two letters."},"zip":{"type":"string","description":"Or postal_code."},"phone":{"type":"string"},"residential":{"type":"boolean"}},"required":["street1","city","state","zip"],"additionalProperties":false},"CarrierLabel":{"type":"object","properties":{"label_id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["outbound","return"]},"carrier":{"type":"string","description":"USPS, UPS, FedEx, ..."},"service":{"type":"string"},"tracking":{"type":"string"},"amount_cents":{"type":"integer","description":"What the label cost, charged to the balance."},"status":{"type":"string","enum":["purchased","voided"]},"has_pdf":{"type":"boolean","description":"A PDF is stored for it; GET /seller/orders/{id}/label gives a 10-minute link."},"label_url":{"oneOf":[{"type":"string","description":"Where a link is given (after a purchase, or a return label for the shopper): a signed URL that lasts 10 minutes."},{"type":"null"}]},"label_url_expires_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"},"voided_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"refund_status":{"oneOf":[{"type":"string"},{"type":"null"}]},"can_void":{"type":"boolean","description":"True until the first carrier scan."}},"required":["label_id","carrier","tracking","amount_cents","status"],"additionalProperties":true},"TrackingEvent":{"type":"object","properties":{"status":{"type":"string","enum":["pre_transit","in_transit","out_for_delivery","delivered","available_for_pickup","return_to_sender","failure","cancelled","error","unknown"]},"status_detail":{"oneOf":[{"type":"string"},{"type":"null"}]},"message":{"oneOf":[{"type":"string"},{"type":"null"}]},"at":{"type":"string","format":"date-time"},"location":{"oneOf":[{"type":"object","properties":{"city":{"type":"string"},"state":{"type":"string"},"zip":{"type":"string"},"country":{"type":"string"}}},{"type":"null"}]},"tracking":{"type":"string"},"carrier":{"oneOf":[{"type":"string"},{"type":"null"}]},"return":{"type":"boolean","description":"An event of a return label."}},"required":["status","at"]},"OrderTracking":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"side":{"type":"string","enum":["buyer","seller","operator"]},"method":{"type":"string"},"fulfillment_status":{"oneOf":[{"type":"string"},{"type":"null"}]},"carrier":{"oneOf":[{"type":"string"},{"type":"null"}]},"tracking":{"oneOf":[{"type":"string"},{"type":"null"}]},"tracking_status":{"oneOf":[{"type":"string","description":"The last carrier status: in_transit, out_for_delivery, delivered, ..."},{"type":"null"}]},"delivered_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"delivered_by_scan":{"type":"boolean","description":"true: delivered_at is the carrier’s delivered scan."},"attention":{"oneOf":[{"type":"string","description":"return_to_sender or failure: the carrier could not deliver; both sides see it."},{"type":"null"}]},"ship_to":{"oneOf":[{"$ref":"#/components/schemas/CarrierAddress"},{"type":"null"}]},"label":{"oneOf":[{"$ref":"#/components/schemas/CarrierLabel"},{"type":"null"}]},"return_labels":{"type":"array","items":{"$ref":"#/components/schemas/CarrierLabel"}},"events":{"type":"array","items":{"$ref":"#/components/schemas/TrackingEvent"}}},"required":["order_id","events"],"additionalProperties":true},"AddressCheck":{"type":"object","properties":{"configured":{"type":"boolean","description":"false: no carrier connection; the address is taken as written."},"deliverable":{"type":"boolean"},"residential":{"oneOf":[{"type":"boolean"},{"type":"null"}]},"corrected":{"type":"boolean","description":"true: the carrier’s form of the address differs; suggestion holds it."},"address":{"$ref":"#/components/schemas/CarrierAddress"},"suggestion":{"oneOf":[{"$ref":"#/components/schemas/CarrierAddress"},{"type":"null"}]},"messages":{"type":"array","items":{"type":"string"}},"code":{"type":"string","description":"address_undeliverable when deliverable is false."},"error_code":{"type":"string","description":"invalid_shipping_address when deliverable is false."}},"required":["deliverable","address"],"additionalProperties":true},"FeedbackPost":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"title":{"type":"string","maxLength":120},"body":{"type":"string","description":"The board gives the first 240 characters (body_truncated true when there is more); GET /feedback/posts/{id} gives all of it."},"body_truncated":{"type":"boolean"},"kind":{"type":"string","description":"The kind of the author’s member.","enum":["warehouse","seller","buyer"]},"page":{"oneOf":[{"type":"string","description":"The page the author was on."},{"type":"null"}]},"status":{"type":"string","description":"open until CommerceBook sets planned, building, shipped or not_now.","enum":["open","planned","building","shipped","not_now"]},"status_note":{"oneOf":[{"type":"string","description":"CommerceBook’s note with the status, 300 characters at most."},{"type":"null"}]},"status_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"pinned":{"type":"boolean"},"featured":{"type":"boolean","description":"A shipped post CommerceBook pinned: it sits first, under Shipped from this board."},"votes":{"type":"integer"},"replies":{"type":"integer"},"voted":{"type":"boolean","description":"The key’s person (or the signed-in person) voted for it."},"author_name":{"type":"string"},"member_id":{"type":"string","format":"uuid"},"member_name":{"type":"string"},"mine":{"type":"boolean"},"editable_until":{"oneOf":[{"type":"string","description":"The author edits or deletes it until then (15 minutes).","format":"date-time"},{"type":"null"}]},"by_agent":{"type":"boolean","description":"Written through a key."},"edited_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","title","kind","status","votes","replies","voted","author_name","member_name"],"additionalProperties":true},"FeedbackReply":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"body":{"type":"string"},"member_id":{"type":"string","format":"uuid"},"member_name":{"type":"string"},"kind":{"type":"string","enum":["warehouse","seller","buyer"]},"author_name":{"type":"string"},"mine":{"type":"boolean"},"deletable":{"type":"boolean"},"by_agent":{"type":"boolean"}},"required":["id","created_at","body","author_name"]},"FeedbackBoard":{"type":"object","properties":{"sort":{"type":"string","enum":["votes","newest"]},"kind":{"oneOf":[{"type":"string","enum":["warehouse","seller","buyer"]},{"type":"null"}]},"count":{"type":"integer"},"posts":{"type":"array","items":{"$ref":"#/components/schemas/FeedbackPost"}}},"required":["sort","posts"]},"MarketIntentPublic":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string","maxLength":120},"category":{"type":"string"},"qty":{"type":"integer"},"ceiling_visible":{"type":"boolean","description":"false: the buyer shows a band, not the ceiling."},"ceiling_unit_cents":{"oneOf":[{"type":"integer","description":"The most the buyer pays each, in cents; null when hidden."},{"type":"null"}]},"ceiling_band":{"oneOf":[{"type":"object","properties":{"min_cents":{"type":"integer"},"max_cents":{"oneOf":[{"type":"integer","description":"Null above $10,000."},{"type":"null"}]}}},{"type":"null"}]},"destination_state":{"oneOf":[{"type":"string","description":"Two-letter state the goods go to, when given."},{"type":"null"}]},"expires_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"},"status":{"type":"string"},"destination_zip":{"oneOf":[{"type":"string","description":"The five-digit ZIP the goods go to, when given."},{"type":"null"}]},"unit":{"oneOf":[{"type":"string","description":"The unit of sale the quantity counts: each, roll, case, pack, box, pallet or other.","enum":["each","roll","case","pack","box","pallet","other"]},{"type":"null"}]},"unit_note":{"oneOf":[{"type":"string","description":"What the unit holds, for example 6 rolls a case.","maxLength":120},{"type":"null"}]},"buyer_checks":{"type":"object","properties":{"account":{"type":"string","description":"business or person"},"verified":{"type":"boolean"},"account_age_days":{"type":"integer"},"dispute_band":{"type":"string","description":"none, 1-2 or 3 or more"},"orders":{"type":"integer","description":"Orders the buyer placed."}}},"quotes":{"type":"integer","description":"Open quotes on it."},"url":{"type":"string","description":"The request on https://commercebook.ai/requests."}},"required":["id","title","category","qty","expires_at","quotes"]},"MarketIntentMine":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"title":{"oneOf":[{"type":"string"},{"type":"null"}]},"notes":{"oneOf":[{"type":"string"},{"type":"null"}]},"category":{"oneOf":[{"type":"string"},{"type":"null"}]},"qty":{"type":"integer"},"ceiling_unit_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"ceiling_visible":{"type":"boolean"},"destination":{"oneOf":[{"type":"string"},{"type":"null"}]},"destination_state":{"oneOf":[{"type":"string"},{"type":"null"}]},"visibility":{"type":"string","enum":["public","private"]},"notify":{"type":"boolean"},"status":{"type":"string","enum":["open","filled","withdrawn","expired"]},"expires_at":{"type":"string","format":"date-time"},"last_quote_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"closed_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"by_agent":{"type":"boolean"},"quotes_open":{"type":"integer"},"quotes_total":{"type":"integer"},"best_unit_cents":{"oneOf":[{"type":"integer","description":"The lowest open quote, each."},{"type":"null"}]},"filled_order":{"oneOf":[{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"status":{"type":"string"}}},{"type":"null"}]},"url":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["id","qty","status","expires_at"]},"MarketIntents":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/MarketIntentPublic"}},"count":{"type":"integer","description":"Every open public request in the category, before the limit."},"category":{"oneOf":[{"type":"string"},{"type":"null"}]},"categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string"},"open":{"type":"integer"}}}},"as_of":{"type":"string","format":"date-time"},"mine":{"type":"array","items":{"$ref":"#/components/schemas/MarketIntentMine"}}},"required":["items","count","categories","as_of"],"description":"mine is present with a key: the member’s own requests in every state, private ones too."},"MarketIntentCreated":{"type":"object","properties":{"intent_id":{"type":"string","format":"uuid"},"status":{"type":"string"},"visibility":{"type":"string"},"title":{"oneOf":[{"type":"string"},{"type":"null"}]},"category":{"oneOf":[{"type":"string"},{"type":"null"}]},"qty":{"type":"integer"},"ceiling_unit_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"expires_at":{"type":"string","format":"date-time"},"notify":{"type":"boolean"},"sellers_told":{"type":"integer","description":"Sellers with a live product in the category that were told, one email each."},"matches_now":{"type":"array","items":{"type":"object","properties":{"offer_id":{"type":"string","format":"uuid"},"lot_id":{"type":"string","format":"uuid"},"title":{"type":"string"},"unit_price_cents":{"type":"integer","description":"The price each at the request’s quantity."},"qty_available":{"type":"integer"},"seller_name":{"type":"string"},"url":{"type":"string"}}}},"url":{"oneOf":[{"type":"string"},{"type":"null"}]}},"required":["intent_id","status","sellers_told","matches_now"]},"MarketIntentQuote":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"intent_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["open","accepted","declined","expired","withdrawn"]},"closed_reason":{"oneOf":[{"type":"string"},{"type":"null"}]},"qty":{"type":"integer"},"unit_price_cents":{"type":"integer"},"shipping_cents":{"type":"integer"},"total_cents":{"type":"integer"},"fulfillment_method":{"type":"string","enum":["pickup","ship"]},"expires_at":{"type":"string","format":"date-time"},"note":{"oneOf":[{"type":"string"},{"type":"null"}]},"by_agent":{"type":"boolean"},"list_unit_cents":{"oneOf":[{"type":"integer","description":"The product’s listed price each at this quantity."},{"type":"null"}]},"product":{"type":"object","properties":{"lot_id":{"type":"string","format":"uuid"},"offer_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"title":{"type":"string"},"condition":{"oneOf":[{"type":"string"},{"type":"null"}]},"photo":{"oneOf":[{"type":"string"},{"type":"null"}]},"url":{"type":"string"}}},"seller":{"type":"object","properties":{"member_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"slug":{"type":"string"},"verified":{"type":"boolean"},"seller_tier":{"type":"string"},"seller_numbers":{"type":"object","properties":{},"additionalProperties":true},"seller_url":{"type":"string"}},"additionalProperties":true}},"required":["id","status","qty","unit_price_cents","total_cents","expires_at"]},"SellerIntents":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"string"}},"category":{"oneOf":[{"type":"string"},{"type":"null"}]},"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/MarketIntentPublic"},{"type":"object","properties":{"notes":{"oneOf":[{"type":"string"},{"type":"null"}]},"my_quote":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"unit_price_cents":{"type":"integer"},"total_cents":{"type":"integer"},"qty":{"type":"integer"},"expires_at":{"type":"string","format":"date-time"}}},{"type":"null"}]}}}]}},"quotes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"intent_id":{"type":"string","format":"uuid"},"intent_title":{"oneOf":[{"type":"string"},{"type":"null"}]},"intent_status":{"type":"string"},"status":{"type":"string"},"closed_reason":{"oneOf":[{"type":"string"},{"type":"null"}]},"qty":{"type":"integer"},"unit_price_cents":{"type":"integer"},"shipping_cents":{"type":"integer"},"total_cents":{"type":"integer"},"expires_at":{"type":"string","format":"date-time"},"lot_id":{"type":"string","format":"uuid"},"product_title":{"oneOf":[{"type":"string"},{"type":"null"}]},"order_number":{"oneOf":[{"type":"string"},{"type":"null"}]}}}}},"required":["categories","items","quotes"]},"MarketBook":{"type":"object","properties":{"as_of":{"type":"string","format":"date-time"},"supply":{"type":"object","properties":{"products":{"type":"integer","description":"Public products on sale."},"sellers":{"type":"integer","description":"Sellers with a public product."},"sellers_unaffiliated":{"type":"integer","description":"Sellers with a public product, leaving out the members affiliated with the operator."},"products_unaffiliated":{"type":"integer"},"categories":{"type":"integer","description":"Categories with at least one product."}},"required":["products","sellers","categories"]},"demand":{"type":"object","properties":{"open_requests":{"type":"integer","description":"Open public requests."},"request_qty":{"type":"integer","description":"The quantity they ask for, added up."},"buyers":{"type":"integer","description":"Members behind the open requests."},"categories":{"type":"integer","description":"Categories with at least one open request."}},"required":["open_requests","request_qty","buyers","categories"]},"accounts":{"type":"object","properties":{"members_verified":{"type":"integer","description":"Warehouses and sellers that are claimed (a login) and verified, the figure network now reads too."},"warehouses_verified":{"type":"integer"},"sellers_verified":{"type":"integer"},"sellers_live":{"type":"integer"},"buyers_verified":{"type":"integer"},"line":{"type":"string","description":"The one members line every surface shows: \"4 verified members: 3 warehouses and 1 seller; 3 buyer accounts\"."}}},"by_category":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","description":"A category key; every key of the category list is present, zero when zero."},"products":{"type":"integer"},"sellers":{"type":"integer"},"from_unit_cents":{"oneOf":[{"type":"integer","description":"The lowest price from 1 unit; null when no product."},{"type":"null"}]},"open_requests":{"type":"integer"},"request_qty":{"type":"integer"},"ceiling_bands":{"type":"array","items":{"type":"object","properties":{"min_cents":{"type":"integer"},"max_cents":{"oneOf":[{"type":"integer","description":"Null above $10,000."},{"type":"null"}]},"requests":{"type":"integer"}}}},"requests_url":{"type":"string","description":"The category on https://commercebook.ai/requests."}},"required":["category","products","sellers","open_requests","request_qty","ceiling_bands"]}},"fills_30d":{"type":"object","properties":{"days":{"type":"integer"},"orders":{"type":"integer","description":"Orders in the last 30 days that reached the seller (authorised, released, accepted or completed)."},"from_requests":{"type":"integer","description":"Of those, orders that filled a request from a seller quote."},"median_hours_request_to_quote":{"oneOf":[{"type":"number","description":"From the request to the quote that filled it; null when none."},{"type":"null"}]},"median_hours_quote_to_order":{"oneOf":[{"type":"number","description":"From that quote to the order; null when none."},{"type":"null"}]}},"required":["days","orders","from_requests"]},"sellers":{"type":"object","properties":{"with_orders":{"type":"integer"},"orders":{"type":"integer"},"delivered":{"type":"object","properties":{"n":{"type":"integer"},"of":{"type":"integer"},"rate":{"oneOf":[{"type":"number","description":"n of, from 0 to 1; null when of is 0."},{"type":"null"}]},"shown_as":{"type":"string","description":"count until it is built on min_orders orders, then percent.","enum":["count","percent"]}},"required":["n","of","shown_as"]},"on_time":{"type":"object","properties":{"n":{"type":"integer"},"of":{"type":"integer"},"rate":{"oneOf":[{"type":"number","description":"n of, from 0 to 1; null when of is 0."},{"type":"null"}]},"shown_as":{"type":"string","description":"count until it is built on min_orders orders, then percent.","enum":["count","percent"]}},"required":["n","of","shown_as"]},"min_orders":{"type":"integer"}},"required":["orders","delivered","on_time","min_orders"]},"links":{"type":"object","properties":{"requests":{"type":"string"},"products":{"type":"string"},"api":{"type":"string"},"page":{"type":"string"}}},"definitions":{"type":"object","additionalProperties":{"type":"string"},"description":"What each count is (sellers.orders: orders placed and accepted by the seller, lifetime; fills_30d.orders: orders paid and passed to the seller in 30 days; delivered of the same orders)."},"disclosure":{"type":"object","properties":{"name":{"type":"string","description":"The operator: Lonestar Fulfillment LLC."},"note":{"type":"string"},"affiliated":{"type":"array","items":{"type":"string"}},"policies":{"type":"string"}}}},"required":["as_of","supply","demand","by_category","fills_30d","sellers"]},"SellerCheckoutMode":{"type":"object","properties":{"mode":{"type":"string","description":"The mode in force: commercebook (Stripe on CommerceBook, the default) or shopify (the store's own Shopify checkout).","enum":["commercebook","shopify"]},"chosen":{"type":"string","description":"The seller's choice (the mode in force differs only for a store installed from the App Store, which is always shopify).","enum":["commercebook","shopify"]},"changed_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"modes":{"type":"array","items":{"type":"string"}},"shopify_available":{"type":"boolean","description":"An installed Shopify store is connected, so shopify can be chosen."},"forced":{"oneOf":[{"type":"string","description":"app_store when the store installed the app from the Shopify App Store."},{"type":"null"}]},"shop":{"oneOf":[{"type":"object","properties":{"domain":{"type":"string"},"name":{"oneOf":[{"type":"string"},{"type":"null"}]},"primary_domain":{"type":"string"},"app_store":{"type":"boolean"},"refund_policy_url":{"oneOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"fee_card":{"oneOf":[{"type":"object","properties":{"brand":{"oneOf":[{"type":"string"},{"type":"null"}]},"last4":{"oneOf":[{"type":"string"},{"type":"null"}]}},"description":"The card the monthly fee invoice is charged to."},{"type":"null"}]},"fee_billing":{"type":"string","description":"stripe_invoice_monthly: the fee on Shopify-checkout orders (8 percent, at most $500 an order) is billed once a month by a Stripe invoice to the saved card."},"needs":{"type":"array","items":{"type":"string","description":"What a switch to shopify still needs: shopify_store, fee_card."}},"changed":{"type":"boolean","description":"POST only: whether this call changed the mode."},"from":{"type":"string","description":"POST only, when changed: the mode before."},"prepared":{"type":"object","properties":{},"description":"POST only, on a switch to shopify: the store facts read and the storefront token and webhooks set up.","additionalProperties":true}},"required":["mode","chosen","shopify_available","needs"],"additionalProperties":true},"SellerShopifyStatus":{"type":"object","properties":{"configured":{"type":"boolean","description":"false: the app is not set up on this server yet, so no store can install it."},"connected":{"type":"boolean","description":"A store has the app installed and its access is held."},"shop":{"oneOf":[{"type":"object","properties":{"domain":{"type":"string","description":"The store, <x>.myshopify.com."},"name":{"oneOf":[{"type":"string"},{"type":"null"}]},"installed_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"uninstalled_at":{"oneOf":[{"type":"string","description":"Set when the merchant removed the app; the store's products are then drafts.","format":"date-time"},{"type":"null"}]},"scopes":{"oneOf":[{"type":"string"},{"type":"null"}]},"last_sync_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"last_error":{"oneOf":[{"type":"string"},{"type":"null"}]},"sync":{"type":"object","properties":{},"description":"The last sync: products, variants, created, updated, unchanged, skipped, drafted, published, linked, skipped_rows (up to 20, with the reason), trigger, at.","additionalProperties":true}}},{"type":"null"}]},"member":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"verified":{"type":"boolean"}}},"live":{"type":"boolean","description":"The seller checklist is done (business details, payouts, shipping), so products can go live."},"stripe":{"type":"object","properties":{"onboarded":{"type":"boolean"},"payouts_enabled":{"type":"boolean"},"connected":{"type":"boolean"}}},"products_linked":{"type":"integer","description":"Lots linked to a Shopify variant of this store."},"products_live":{"type":"integer","description":"Of those, lots live on the book."},"orders_sent":{"type":"integer","description":"CommerceBook orders this store received as Shopify orders."},"requests":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"category":{"oneOf":[{"type":"string"},{"type":"null"}]},"qty":{"type":"integer"},"url":{"type":"string"}},"additionalProperties":true}},"portal_url":{"type":"string","description":"The seller portal's Shopify page."},"install_url":{"type":"string","description":"With ?shop= only: the install link for the owner to open, single use, 15 minutes, bound to this seller."},"install_expires_at":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["configured","connected","member","products_linked"],"additionalProperties":true},"SellerShopifySync":{"type":"object","properties":{"shop":{"type":"string"},"ok":{"type":"boolean"},"products":{"type":"integer","description":"Products read from Shopify."},"variants":{"type":"integer","description":"Variants read (one lot each)."},"created":{"type":"integer"},"updated":{"type":"integer"},"unchanged":{"type":"integer"},"skipped":{"type":"integer"},"drafted":{"type":"integer","description":"Lots drafted: product not active in Shopify, or gone from it."},"published":{"type":"integer","description":"Lots the app had drafted, back on the book."},"linked":{"type":"integer","description":"Variants linked to a lot."},"skipped_rows":{"type":"array","items":{"type":"object","properties":{"item_id":{"oneOf":[{"type":"string"},{"type":"null"}]},"reason":{"type":"string"}}}}},"required":["shop","ok","created","updated","skipped"]},"AgentRules":{"type":"object","properties":{"spend_cap_cents_30d":{"oneOf":[{"type":"integer","description":"Most the agent spends in any 30 days across every key of the account, in cents; null: each key keeps its own cap.","minimum":0},{"type":"null"}]},"confirm_above_cents":{"oneOf":[{"type":"integer","description":"A payment above this waits for the owner; the lower of this and the key’s own amount applies.","minimum":0},{"type":"null"}]},"order_max_cents":{"oneOf":[{"type":"integer","description":"One order or purchase above this waits for the owner (over_order_max).","minimum":0},{"type":"null"}]},"allowed_categories":{"oneOf":[{"type":"array","items":{"type":"string"},"description":"Product categories the agent may buy in and post requests in; null is every category."},{"type":"null"}]},"counterparties":{"type":"string","enum":["any","verified","list"],"description":"Members the agent may deal with: any, verified only, or the list in counterparty_member_ids."},"counterparty_member_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"allowed_hours":{"oneOf":[{"type":"object","properties":{"tz":{"type":"string","description":"An IANA time zone, such as America/Chicago."},"start":{"type":"string","description":"HH:MM"},"end":{"type":"string","description":"HH:MM; earlier than start runs past midnight."},"days":{"type":"array","items":{"type":"string","enum":["mon","tue","wed","thu","fri","sat","sun"]}}},"required":["tz","start","end","days"]},{"type":"null"}]},"allowed_actions":{"oneOf":[{"type":"array","items":{"type":"string","enum":["post","quote","accept","pay","withdraw","message","lead_post","lead_buy","capacity_quote"]},"description":"The actions the agent may take; null is every action its key allows. Reading is always allowed."},{"type":"null"}]},"auto_accept_under_ceiling":{"type":"boolean","description":"A seller’s quote at or under the request’s ceiling, inside every other rule, is accepted for the owner automatically."},"notify":{"type":"string","enum":["each","daily","none"],"description":"The owner’s email when a rule stops the agent: each time, once a day, or never."},"notify_channel":{"type":"string","enum":["email","telegram"]}},"required":["spend_cap_cents_30d","confirm_above_cents","order_max_cents","allowed_categories","counterparties","counterparty_member_ids","allowed_hours","allowed_actions","auto_accept_under_ceiling","notify","notify_channel"]},"AgentRulesView":{"type":"object","properties":{"member":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"kind":{"type":"string"}}},"key":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"label":{"type":"string"},"key_prefix":{"type":"string"},"scope":{"type":"string"}}},{"type":"null"}]},"account":{"$ref":"#/components/schemas/AgentRules"},"rules":{"$ref":"#/components/schemas/AgentRules","description":"The rules that bind this key: the money rules are the lower of the account’s and the key’s."},"key_limits":{"oneOf":[{"type":"object","additionalProperties":true,"description":"The key’s own limits (GET /keys/{id}/limits) and its per-purchase and per-day ceilings."},{"type":"null"}]},"sources":{"type":"object","additionalProperties":{"type":"string","enum":["account","key","default"]},"description":"Who sets the value that applies to each rule."},"counterparty_members":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}},"spent_30d":{"type":"object","properties":{"account":{"type":"integer"},"key":{"oneOf":[{"type":"integer"},{"type":"null"}]}}},"text":{"type":"string","description":"The rules as one paragraph for the agent’s instructions (the page’s \"Rules your agent reads\")."}},"required":["member","account","rules","sources"]},"AgentActivityItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"action":{"type":"string"},"key_id":{"oneOf":[{"type":"string"},{"type":"null"}]},"key_prefix":{"oneOf":[{"type":"string"},{"type":"null"}]},"direction":{"type":"string","enum":["call","refusal"]},"gate_result":{"type":"string"},"outcome":{"type":"string","enum":["allowed","parked","stopped"]},"rule":{"oneOf":[{"type":"string","description":"The rule behind the result: the rule a refusal names (rule_blocked), the limit a waiting call passed, or auto_accept_under_ceiling."},{"type":"null"}]},"amount_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"counterparty":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},{"type":"null"}]},"pending_id":{"oneOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["id","created_at","action","outcome"]},"RequestReach":{"type":"object","properties":{"category":{"type":"string"},"qty":{"type":"integer"},"destination_state":{"oneOf":[{"type":"string"},{"type":"null"}]},"sellers_told":{"type":"integer","description":"Sellers a public request in the category is emailed to: a live product there, or a watch on it."},"sellers_unaffiliated_told":{"type":"integer","description":"Of the sellers told, the ones not affiliated with the operator."},"sellers_affiliated_told":{"type":"integer","description":"Of the sellers told, the ones affiliated with the operator."},"sellers_with_live_products":{"type":"integer"},"sellers_watching":{"type":"integer"},"live_products":{"type":"integer","description":"Live products in the category."},"products_match":{"type":"integer","description":"Of those, the ones with the quantity available that ship to the state."},"counts_only":{"type":"boolean","description":"Always true: no seller is named."},"rule":{"type":"string"},"as_of":{"type":"string","format":"date-time"},"next":{"type":"object","properties":{"buyer":{"type":"string","description":"The free step for a buyer: post the request, which waits for the first seller."},"seller":{"type":"string","description":"The free step for a seller agent: watch the category."}}},"affiliation_note":{"type":"string","description":"Present when every seller told is affiliated with the operator."}},"required":["category","sellers_told","sellers_unaffiliated_told","live_products","products_match"]},"ShippingEstimate":{"type":"object","properties":{"lot_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"region":{"oneOf":[{"type":"string"},{"type":"null"}]},"qty":{"type":"integer"},"served":{"type":"boolean","description":"false: the seller does not ship to that state."},"low_cents":{"oneOf":[{"type":"integer","description":"The lowest of the lot’s rules for the state."},{"type":"null"}]},"high_cents":{"oneOf":[{"type":"integer","description":"The highest of them."},{"type":"null"}]},"calculated":{"type":"boolean","description":"A carrier-calculated rule: priced at the quote (POST /market/quotes)."},"rules":{"type":"array","items":{"type":"object","properties":{"service":{"type":"string"},"rate_kind":{"type":"string"},"basis":{"type":"string","description":"per_order (flat or free), per_order_by_qty (a first unit and each more), by_weight or calculated."},"low_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"high_cents":{"oneOf":[{"type":"integer"},{"type":"null"}]},"transit_days_min":{"oneOf":[{"type":"integer"},{"type":"null"}]},"transit_days_max":{"oneOf":[{"type":"integer"},{"type":"null"}]}}}},"qty_available":{"oneOf":[{"type":"integer","description":"The quantity available of the product."},{"type":"null"}]},"short_by":{"oneOf":[{"type":"integer","description":"How far qty is over qty_available (0 when it is not)."},{"type":"null"}]},"rate_basis":{"type":"string","description":"per_order: every amount is the shipping of the whole order of qty units.","enum":["per_order"]},"stock_note":{"type":"string","description":"Present when qty is over the quantity available."},"rate_note":{"type":"string","description":"What each amount is the shipping of."},"destination_zip":{"type":"string","description":"The ZIP sent, when the state was read from it."},"ship_from_state":{"oneOf":[{"type":"string","description":"The state the goods leave from."},{"type":"null"}]},"ships_from":{"oneOf":[{"type":"object","properties":{"city":{"oneOf":[{"type":"string"},{"type":"null"}]},"state":{"oneOf":[{"type":"string"},{"type":"null"}]},"area":{"oneOf":[{"type":"string","description":"City, ST."},{"type":"null"}]},"held_by":{"type":"string","enum":["seller","warehouse"]}}},{"type":"null"}]},"as_of":{"type":"string","format":"date-time"}},"required":["lot_id","state","served"]},"CategoryWatch":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"string"}},"known":{"type":"array","items":{"type":"string","description":"The category keys of the book."}},"rule":{"type":"string"}},"required":["categories"]},"SellerCapability":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"available":{"type":"boolean","description":"true: callable today; false: planned (see planned_as_of)."},"since":{"type":"string","description":"The day it went live (YYYY-MM-DD).","format":"date"},"planned_as_of":{"type":"string","description":"The day its line in What is coming was last confirmed.","format":"date"},"status":{"type":"string","enum":["planned","building"]},"tool":{"oneOf":[{"type":"string","description":"The MCP tool that does it."},{"type":"null"}]},"endpoint":{"oneOf":[{"type":"string","description":"The endpoint or the address that does it."},{"type":"null"}]},"sentence":{"type":"string","description":"One sentence."},"by":{"type":"string","description":"first_steps only: who takes the step.","enum":["agent","owner"]},"details":{"type":"object","properties":{}}},"required":["key","name","available","tool","endpoint","sentence"]},"SellerCapabilities":{"type":"object","properties":{"title":{"type":"string"},"intro":{"type":"string"},"as_of":{"oneOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"fee_sentence":{"type":"string","description":"The seller fee in the words every page uses."},"groups":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","enum":["ways_to_offer","ways_to_be_found","ways_to_be_paid","what_the_record_shows","rules","first_steps"]},"heading":{"type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/SellerCapability"}}},"required":["key","heading","items"]}},"counts":{"type":"object","properties":{"available":{"type":"integer"},"planned":{"type":"integer"}}},"owner_sentence":{"type":"string"},"links":{"type":"object","properties":{"briefing":{"type":"string"},"page":{"type":"string"},"markdown":{"type":"string"},"json":{"type":"string"},"mcp":{"type":"string"},"signup":{"type":"string"}}}},"required":["title","groups","fee_sentence"]}}}}