Ada Diamonds Agentic checkout (hosted link) API
The Agentic checkout (hosted link) API from Ada Diamonds — 1 operation(s) for agentic checkout (hosted link).
The Agentic checkout (hosted link) API from Ada Diamonds — 1 operation(s) for agentic checkout (hosted link).
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/adadiamonds-com:adadiamonds-com-agentic-checkout-hosted-link-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Ada Diamonds Agent Agentic checkout (hosted link) API
version: 1.1.0
summary: Read Ada Diamonds' lab grown diamond inventory, engagement ring settings, fine jewelry, and buying guides — and request a jeweler consultation.
description: 'The Ada Diamonds Agent API gives AI agents and applications structured access to Ada Diamonds'' live catalog and published content.
**Catalog and content endpoints require no credential.** An agent answering a shopper''s question should not need an onboarding step first. Credentials exist to raise rate limits and to reach the endpoints that touch a specific customer''s data. The API roots (`/api`, `/api/v1`) are the one read that challenges anonymous callers, with a `WWW-Authenticate: Bearer` header that points at the OAuth metadata.
**Pricing model.** An engagement ring is a setting plus a loose diamond, priced separately. `priceFrom` on a setting excludes the center stone. All prices are US dollars.
**Getting a credential.** `POST /api/v1/keys` issues a working API key immediately, no account required. For customer-specific access, register an OAuth client at `/api/oauth/register` and use the authorization code flow with PKCE.
**Sandbox.** Request `{"env":"sandbox"}` when creating a key. Sandbox credentials read the real catalog and accept writes without creating anything.
**Batching.** `POST /api/v1/batch` runs up to 20 public reads in one request and returns each sub-response with its own status. Use it to assemble a quote (a setting plus several stones) in a single round trip. A batch counts as one request against the rate limit.
**Long-running operations.** Whole-catalog exports are asynchronous: `POST /api/v1/exports` answers 202 with a `Location` header for the job. Poll `GET /api/v1/jobs/{id}` (honouring `Retry-After`) until `status` is `succeeded`, then download `result_url`. Exports complete within seconds and job ids stay valid for 24 hours. Operations marked `x-async: true` follow this pattern.
**MCP.** The same catalog is available as an MCP server at https://www.adadiamonds.com/mcp (streamable HTTP); the server card at https://www.adadiamonds.com/.well-known/mcp/server-card.json lists its tools.'
termsOfService: https://www.adadiamonds.com/terms
contact:
name: Ada Diamonds developer support
email: it@adadiamonds.com
url: https://www.adadiamonds.com/developers
license:
name: Ada Diamonds API Terms
url: https://www.adadiamonds.com/terms
servers:
- url: https://www.adadiamonds.com
description: Production
- url: https://www.adadiamonds.com/sandbox
description: 'Sandbox: every path below, mounted under /sandbox. Credential-less requests are treated as the public sandbox key; reads return the live catalog, writes are acknowledged and create nothing. Described at /sandbox.'
security:
- {}
- apiKey: []
- oauth2:
- catalog:read
- content:read
tags:
- name: Agentic checkout (hosted link)
paths:
/api/v1/checkout_links:
post:
operationId: createCheckoutLink
summary: Create a hosted checkout link
description: 'Assemble a cart from product-feed item ids (`diamond:`, `setting:`, `jewelry:`) 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).'
tags:
- Agentic checkout (hosted link)
parameters:
- in: header
name: Idempotency-Key
required: false
description: Optional but recommended on state-changing requests; a reused key with a different body is rejected with 409.
schema:
type: string
maxLength: 255
- in: header
name: Request-Id
required: false
description: Trace id; echoed back when provided.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutLinkCreateRequest'
responses:
'200':
description: The cart needs more input; `problems[]` lists what is missing and `url` is null.
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutLink'
'201':
description: A payable link was created; `url` is the Stripe-hosted checkout page.
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutLink'
'400':
description: Malformed body, unknown item id, or an unavailable product.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
AcpAddress:
type: object
required:
- line_one
- city
- state
- country
- postal_code
properties:
name:
type: string
line_one:
type: string
line_two:
type: string
city:
type: string
state:
type: string
description: ISO 3166-2 region code, e.g. NY
country:
type: string
description: ISO 3166-1 alpha-2
postal_code:
type: string
phone_number:
type: string
description: E.164
CheckoutLink:
type: object
required:
- object
- id
- url
- simulated
- state
- totals
properties:
object:
type: string
enum:
- checkout_link
id:
type: string
description: Session id, `link_<uuid>`.
url:
type: string
nullable: true
description: Stripe-hosted checkout URL; null while `state` is `needs_input`.
simulated:
type: boolean
description: 'True in sandbox: nothing is payable.'
expires_at:
type: string
nullable: true
format: date-time
state:
type: string
enum:
- ready
- needs_input
currency:
type: string
totals:
type: object
description: 'All cents: items_base_amount, discount, subtotal, fulfillment, tax, total.'
line_items:
type: array
items:
type: object
messages:
type: array
items:
type: object
problems:
type: array
items:
type: object
description: Blocking problems when `state` is `needs_input`.
CheckoutLinkCreateRequest:
type: object
required:
- items
- shipping_address
properties:
items:
type: array
minItems: 1
items:
$ref: '#/components/schemas/AcpItem'
description: A complete engagement ring is one setting item plus one diamond item.
shipping_address:
$ref: '#/components/schemas/AcpAddress'
buyer:
type: object
properties:
email:
type: string
description: Optional; Stripe collects it on the payment page when missing.
full_name:
type: string
phone_number:
type: string
env:
type: string
enum:
- production
- sandbox
description: 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.
AcpItem:
type: object
required:
- id
properties:
id:
type: string
description: diamond:<id>, setting:<slug>, or jewelry:<slug>
example: diamond:LG123456
quantity:
type: integer
minimum: 1
default: 1
description: Diamonds are unique stones; quantity must be 1.
Error:
type: object
required:
- error
- error_description
properties:
error:
type: string
description: Stable machine-readable code.
example: not_found
error_description:
type: string
description: What went wrong and what to do about it.
documentation_url:
type: string
format: uri
additionalProperties: true
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'An Ada API key or OAuth access token sent as `Authorization: Bearer <credential>`. Agentic checkout requires it; sandbox keys (ada_test_*) complete without charging.'
apiKey:
type: apiKey
in: header
name: X-Ada-Api-Key
description: 'Self-serve key from POST /api/v1/keys. Also accepted as `Authorization: Bearer <key>`. Public read scopes only.'
oauth2:
type: oauth2
description: OAuth 2.1. PKCE is mandatory on the authorization code flow. Clients may self-register at /api/oauth/register (RFC 7591).
flows:
authorizationCode:
authorizationUrl: https://www.adadiamonds.com/oauth/authorize
tokenUrl: https://www.adadiamonds.com/api/oauth/token
refreshUrl: https://www.adadiamonds.com/api/oauth/token
scopes:
catalog:read: Read the public product catalog — diamonds, engagement rings, and fine jewelry, with prices and specifications.
content:read: Read published editorial content — knowledge base articles, buying guides, and showroom information.
profile:read: Read the signed-in customer's account profile (name, email, saved preferences).
orders:read: Read the signed-in customer's order history and order status.
cart:write: Create and modify a shopping cart on the signed-in customer's behalf.
appointments:write: Request a consultation or showroom appointment on the signed-in customer's behalf.
clientCredentials:
tokenUrl: https://www.adadiamonds.com/api/oauth/token
scopes:
catalog:read: Read the public product catalog — diamonds, engagement rings, and fine jewelry, with prices and specifications.
content:read: Read published editorial content — knowledge base articles, buying guides, and showroom information.
externalDocs:
description: Ada Diamonds developer documentation
url: https://www.adadiamonds.com/developers