Agentic checkout (hosted link)

Create a hosted checkout link

Assemble a cart from product-feed item ids (diamond:<report number>, setting:<slug>, jewelry:<slug>) and get back a Stripe-hosted checkout URL the buyer opens to pay; no card data passes through the agent. Requires the shipping address (tax and shipping are priced into the link); buyer email is optional and collected on the payment page when missing. Anonymous callers are allowed, and an anonymous or production-credential request without env: "sandbox" creates a LIVE, payable Stripe Checkout session; a sandbox credential or env: "sandbox" returns a simulated link and creates no Stripe session. (The MCP create_checkout_link tool differs: anonymous MCP calls default to sandbox and need env: "production" for a live link.) Links expire after 24 hours. On payment, the order flows through the standard pipeline (order confirmation email, jeweler follow-up on size and metal).

post/api/v1/checkout_links

Request

  • Base URL: https://www.adadiamonds.com
  • URL: https://www.adadiamonds.com/api/v1/checkout_links
  • Auth: one of:
    • none
    • API key in header X-Ada-Api-Key
    • OAuth 2 (authorization code, authorization URL https://www.adadiamonds.com/oauth/authorize, token URL https://www.adadiamonds.com/api/oauth/token; client credentials, token URL https://www.adadiamonds.com/api/oauth/token, scopes: catalog:read, content:read)

Headers

Idempotency-Keystring

Optional but recommended on state-changing requests; a reused key with a different body is rejected with 409.

Request-Idstring

Trace id; echoed back when provided.

Request body

env'production' | 'sandbox'

sandbox returns a simulated link and never touches Stripe. Omitted on this REST endpoint, anonymous and production-credential calls default to production and create a live, payable Stripe session.

Example request

{
  "items": [
    {
      "id": "diamond:LG123456"
    }
  ]
}

Response

The cart needs more input; problems[] lists what is missing and url is null.

object'checkout_link' required
idstring required

Session id, link_<uuid>.

urlstring nullable required

Stripe-hosted checkout URL; null while state is needs_input.

simulatedboolean required

True in sandbox: nothing is payable.

expires_atstring date-time nullable
state'ready' | 'needs_input' required
currencystring
totalsobject required

All cents: items_base_amount, discount, subtotal, fulfillment, tax, total.

line_itemsobject[]
messagesobject[]
problemsobject[]

Blocking problems when state is needs_input.

Changes

No recorded changes to this operation across all 1 revision of this API.