{"protocol":"bd-commerce/1","openapi":"https://branddesign.host/commerce/v1/openapi.json","documentation":"https://branddesign.ltd/AGENTS.md","interfaceBoundary":"Use bd-commerce/1 for direct REST. MCP at https://branddesign.ltd/mcp has separate OAuth onboarding and tool argument schemas. CLI and WebMCP cannot create orders, accept offers or start payments; besides public reads they offer only the AI representative and an enquiry the person confirms before it is sent. ACP and UCP accept self-registered agents with a Bearer derived from the agent secret and current verified domain control (KYA); UCP also needs a UCP-Agent profile on that domain, and platforms that sign requests need prior approval. On UCP, AP2 checkout mandates (dev.ucp.common.payment.ap2_mandate) are required and verified when the platform profile declares AP2.","adapterDefaults":{"mcp":{"tool":"create_order","language":{"required":false,"default":"en"},"brief":{"requiredByToolSchema":true,"emptyObjectAllowed":"Only when no required catalog field is missing."},"idempotencyKey":{"required":false,"generatedWhenOmitted":true,"retryAdvice":"Supply and reuse your own stable key for retries; omission generates a new key per invocation."}},"rest":{"language":{"required":true},"brief":{"required":false,"whenOmitted":"Equivalent to {}; required catalog fields are still validated."},"idempotencyKey":{"required":true,"minLength":16,"maxLength":100}},"scope":"Adapter defaults only. Catalog fields, accepted offer, buyer authority and payment checks are shared."},"requestExamples":{"create":{"idempotencyKey":"example-order-20261005-0001","payload":{"service":"101Ts3t","language":"en","brief":{"challenge_id":"qst_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","challenge_context_hash":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"}}},"accept":{"accessToken":"REPLACE_WITH_ORDER_ACCESS_TOKEN","payload":{"billing":{"type":"person","fullName":"Example Buyer","email":"buyer@example.com","country":"BG","city":"Varna","address":"Example address 1"},"offerVersion":"REPLACE_WITH_ORDER_OFFER_VERSION","termsHash":"REPLACE_WITH_ORDER_OFFER_TERMS_EN_HASH","accepted":true}},"status":{"accessToken":"REPLACE_WITH_ORDER_ACCESS_TOKEN"},"payment":{"accessToken":"REPLACE_WITH_ORDER_ACCESS_TOKEN","stage":"advance","confirmed":true,"sharedPaymentToken":"spt_REPLACE_WITH_BUYER_AUTHORIZED_TOKEN"},"hostedPayment":{"accessToken":"REPLACE_WITH_ORDER_ACCESS_TOKEN","stage":"advance","confirmed":true}},"exampleWarning":"Illustrative placeholders only. Use your real issued quest binding, returned order accessToken/offer hashes, and buyer-authorized billing/payment data.","workflow":["GET /catalog and read the chosen service fields","POST /agents/register; store its secret privately","For the owner limit: POST /agents/kya/challenge, publish the DNS TXT record, POST /agents/kya/verify; once verified it is read again from DNS at every order, acceptance and payment","Sign POST /orders with the required idempotencyKey + payload envelope","With buyer authorization POST /orders/{id}/accept using accessToken + payload","POST /orders/{id}/payment with explicit buyer confirmation: a shared payment token, or the link to our payment page (card in the invoice name, cardholder address in the invoice country; 3-D Secure for every agent order)","Read signed POST /orders/{id}/status; keep one order and reconcile any ambiguous payment before retry"],"seller":{"name":"Brand Design Ltd.","site":"https://branddesign.ltd","record":"https://doi.org/10.5281/zenodo.22767915"},"base":"https://branddesign.host/commerce/v1","compatibleProtocols":{"acp":{"version":"2026-04-17","discovery":"https://branddesign.host/.well-known/acp.json","base":"https://branddesign.host/acp/2026-04-17","availability":"self-registered agents (Bearer derived from the agent secret)"},"ucp":{"version":"2026-08-25","profile":"https://branddesign.host/.well-known/ucp","base":"https://branddesign.host/ucp/2026-08-25","olderVersion":{"version":"2026-04-08","profile":"https://branddesign.host/.well-known/ucp/2026-04-08","base":"https://branddesign.host/ucp/2026-04-08"},"authentication":"Bearer <clientId>.<HMAC-SHA256 of a fixed UCP label keyed with the agent secret>; the agent must have verified domain control (KYA) and send a UCP-Agent profile on that domain","availability":"self-registered agents with verified domain control (KYA)"}},"openToAgents":true,"register":{"method":"POST","path":"/agents/register","auth":"none","body":{"name":"string","contact":"https:// or mailto: URL"},"returns":["clientId","secret","kya"],"note":"The secret is shown once and is not recoverable."},"knowYourAgent":{"method":"dns-txt","assurance":"domain-control","challenge":"/agents/kya/challenge","verify":"/agents/kya/verify","status":"/agents/kya/status","rule":"Every agent order, acceptance and payment, by shared payment token or hosted checkout, needs mandatory domain verification of the robot against the domain of its maker: a request signed with the keys its maker publishes there (Web Bot Auth) or coming from the addresses its maker publishes there. A DNS TXT record on the own domain of the agent adds the owner limit. Discovery stays open; a person ordering on the website is not affected.","revocation":"Once verified, the TXT record of the agent is read again at every order, acceptance and payment. Removing it stops the agent from ordering and paying (KYA_REVOKED) as soon as the DNS answer changes; DNS that cannot answer stops the step too (KYA_DNS_UNAVAILABLE). The merchant can also stop an agent, after which none of its requests are accepted.","spendingLimit":"Optional, set by the agent owner in the same record: \"bd-kya-v1=<clientId>:<token>;max=500EUR\". An order above it is refused when it is created and at payment (AGENT_LIMIT_EXCEEDED); a malformed limit is refused (KYA_LIMIT_INVALID)."},"authentication":{"scheme":"HMAC-SHA256","headers":["x-bd-client","x-bd-time","x-bd-nonce","x-bd-signature"],"signedString":"method\\npath\\ntimestamp\\nnonce\\nsha256(body)","timestampWindowSeconds":120,"nonce":"single use","rateLimitPerMinute":180,"timestamp":"Unix epoch milliseconds as a 13-digit decimal string, not seconds","path":"Full request pathname including /commerce/v1; e.g. /commerce/v1/orders. No origin or query string.","noncePattern":"^[a-zA-Z0-9_-]{24,80}$","body":"Serialize JSON once to UTF-8; hash and send the exact same bytes with Content-Type: application/json.","signatureEncoding":"lowercase hexadecimal","secretEncoding":"Use the returned secret as a UTF-8 string; do not base64-decode it.","separator":"Join the five fields with actual LF newline characters, not the literal backslash-n string.","retry":"Every request, including retries and status checks, uses a fresh timestamp, nonce and signature. Reuse the same idempotencyKey and identical payload when retrying order creation."},"endpoints":[{"method":"GET","path":"/catalog","auth":"none"},{"method":"GET","path":"/evidence/:provider_event_reference","auth":"none","note":"Returns the immutable signed provider artifact; no billing or payment credential data."},{"method":"GET","path":"/evidence/:provider_event_reference/route","auth":"none","note":"Returns a separate signed route and KYA attestation for a new completed transaction."},{"method":"GET","path":"/evidence/:provider_event_reference/channel","auth":"none","note":"Returns a separate signed channel attestation (protocol and transport at order and payment, payment instrument, KYA) for a new completed transaction."},{"method":"POST","path":"/orders","scope":"order.create","requestSchema":"https://branddesign.host/commerce/v1/openapi.json#/components/schemas/CreateOrder"},{"method":"POST","path":"/orders/:id/accept","scope":"order.accept","requestSchema":"https://branddesign.host/commerce/v1/openapi.json#/components/schemas/AcceptOrder"},{"method":"POST","path":"/orders/:id/payment","scope":"payment.start","requestSchema":"https://branddesign.host/commerce/v1/openapi.json#/components/schemas/StartPayment","note":"Send a buyer-authorized sharedPaymentToken to settle without a page. Without one, form.redirect links our payment page; on that page the card must be in the name on the invoice (for a company: its representative or the company name) and the cardholder address must be in the invoice country, and every order placed by an AI agent needs the cardholder to confirm with the bank (3-D Secure). Agents must be verified robots."},{"method":"POST","path":"/orders/:id/status","scope":"order.read","requestSchema":"https://branddesign.host/commerce/v1/openapi.json#/components/schemas/OrderAccess"},{"method":"POST","path":"/orders/:id/withdraw","scope":"order.accept","requestSchema":"https://branddesign.host/commerce/v1/openapi.json#/components/schemas/WithdrawOrder","note":"Consumer right of withdrawal: 14 days from the conclusion of the contract, natural persons only, not for printed products made to order."}],"amounts":{"unit":"minor","currency":"EUR","example":"100000 = 1000.00 EUR","note":"Every amount in this API is an integer in the minor unit of the currency. 100000 means 1000.00 EUR, not 100000.00 EUR."},"payment":{"provider":"stripe","instrument":"shared payment token","networkBusinessProfile":"profile_61VPFr90RWZmafGq9A6VPFr9Qr9EuUpOLB5w91KhcDl2","currency":"EUR","note":"Grant the token to the profile above, then pass it as sharedPaymentToken."},"terms":"https://branddesign.ltd/terms"}