> ## Documentation Index
> Fetch the complete documentation index at: https://www.zinc.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Claim a Sandbox
> Fold a provisional sandbox — its order history and its API key — into a real Zinc account without breaking the agent that created it.
Folds a provisional sandbox into the **authenticated** account. This is what the `claim_url` from [the mint response](/docs/v2/api-reference/sandbox/mint-sandbox-key) leads to: a human signs in, and the agent's sandbox becomes part of their Zinc account.
Claiming is always a **merge** — signing in creates the account if it didn't exist, so by the time this endpoint runs there is always a real account to merge into.
## What moves
| | Result |
| -------------- | ------------------------------------------------------------------------ |
| Sandbox orders | Repointed to the claiming account. The test history survives. |
| API keys | **Reassigned, not revoked.** Whatever the agent hardcoded keeps working. |
The response reports the counts (`orders_moved`, `keys_moved`) plus a human-readable `message`.
Not revoking the key is the whole point of claiming rather than starting over. An agent that has been running against a sandbox for a week doesn't need redeployment to keep going.
## Errors
| Status | Cause |
| ------ | ----------------------------------------------------------------------------------------------------------------- |
| `404` | Unknown, already-used, or expired claim token. Tokens are **single-use** and die with the sandbox they belong to. |
| `403` | A sandbox key tried to claim a sandbox. This endpoint needs a signed-in Zinc account, not a `zn_test_` key. |
The claim token is returned **once**, in the `claim_url` at mint time — only its hash is stored, so the URL cannot be regenerated. If it's lost, mint a new sandbox.
## After claiming
A claimed key still only reaches the sandbox. To place real orders, the account owner mints a `zn_live_` key in the [dashboard](https://app.zinc.com) and funds a [wallet](/docs/v2/wallet). The agent can confirm the claim landed with [`GET /sandbox/status`](/docs/v2/api-reference/sandbox/get-sandbox-status).
## OpenAPI
````yaml versions/latest.json POST /sandbox/claim
openapi: 3.1.0
info:
title: Zinc
summary: >-
Zinc lets you search, buy, and return items from top online retailers with a
single API.
description: >-
Search, buy, and return items from top online retailers with a single API.
Supports AI agent ordering via MPP (HTTP 402) — no account required.
Supported retailers include 1-800-Flowers, Ace Hardware, Amazon, Amazon DE,
Barnes & Noble, Best Buy, Chewy, Gap, IBS, Lowe's, Macys, Partstown, and 11
more. Ships to the US and 2 other countries (DE, IT).
version: '2026-08-21'
x-logo:
url: https://mintlify.s3.us-west-1.amazonaws.com/zinc/logo/light.png
contact:
name: Zinc API Support
email: support@zinc.com
url: https://zinc.com/docs
x-guidance: >-
Zinc lets AI agents buy products from online retailers via a single API. Use
POST /agent/orders to place an order — no Zinc account needed, payment is
handled via MPP (HTTP 402 flow). Provide a product URL from a supported
retailer, a shipping address, and max_price in cents. The API charges
max_price + $1 API fee upfront and refunds the difference on completion. To
find products first, the /agent/* data endpoints (search, products/search,
products/offers, products/details) are MPP-paid at $0.01 per call;
/agent/search returns orderable URLs to feed straight into /agent/orders.
GET /retailers lists supported retailers for free (no payment or account).
Authenticated equivalents (orders, products, managed-accounts) require a
Bearer token (API key prefixed zn_). Docs: https://zinc.com/docs Supported
retailers include 1-800-Flowers, Ace Hardware, Amazon, Amazon DE, Barnes &
Noble, Best Buy, Chewy, Gap, IBS, Lowe's, Macys, Partstown, and 11 more,
shipping to the US and 2 other countries (DE, IT).
x-supported-retailers:
- 1-800-Flowers
- Ace Hardware
- Amazon
- Amazon DE
- Barnes & Noble
- Best Buy
- Chewy
- Gap
- IBS
- Lowe's
- Macys
- Partstown
- Pokémon Center
- Sephora
- Target
- The Home Depot
- TikTok
- Walmart
- Wayfair
- Zinc
- eBay
- libraccio
- zazzle
x-supported-countries:
- US
- DE
- IT
servers:
- url: https://api.zinc.com
description: Production
security:
- BearerAuth: []
paths:
/sandbox/claim:
post:
tags:
- sandbox
summary: Claim a sandbox into your account
description: >-
Fold a provisional sandbox into the authenticated account.
Always a merge: Stytch's callback creates a real user row on first
login,
so a caller reaching this endpoint already has an account. The agent's
key
is reassigned rather than revoked, so whatever it has hardcoded keeps
working — that is the point of claiming rather than starting over.
operationId: claim_sandbox_sandbox_claim_post
parameters:
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SandboxClaimRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SandboxClaimResponse'
'404':
description: >-
Unknown, already-used, or swept claim token. Claim tokens are
single-use and die with the sandbox they belong to.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
SandboxClaimRequest:
properties:
token:
type: string
maxLength: 128
minLength: 1
title: Token
type: object
required:
- token
title: SandboxClaimRequest
description: The raw claim token from a claim URL.
SandboxClaimResponse:
properties:
claimed:
type: boolean
title: Claimed
orders_moved:
type: integer
title: Orders Moved
keys_moved:
type: integer
title: Keys Moved
message:
type: string
title: Message
type: object
required:
- claimed
- orders_moved
- keys_moved
- message
title: SandboxClaimResponse
description: What a completed claim moved onto the account.
ErrorResponse:
properties:
error:
$ref: '#/components/schemas/ErrorDetail'
type: object
required:
- error
title: ErrorResponse
description: Wrapper for error responses.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ErrorDetail:
properties:
code:
$ref: '#/components/schemas/ErrorCode'
message:
type: string
title: Message
details:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Details
type: object
required:
- code
- message
title: ErrorDetail
description: Standard error response body.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
ErrorCode:
type: string
enum:
- unauthorized
- forbidden
- invalid_token
- token_expired
- not_found
- already_exists
- validation_error
- insufficient_funds
- payment_failed
- payment_method_required
- invalid_payment_method
- invalid_shipping_address
- url_unreachable
- non_us_retailer
- unsupported_retailer
- unsupported_country
- retailer_country_not_supported
- guest_checkout_not_supported
- invalid_variant
- out_of_stock
- shipping_unavailable
- order_not_cancellable
- return_not_allowed
- external_service_error
- stripe_error
- stytch_error
- internal_error
- bad_request
- rate_limit_exceeded
- service_unavailable
title: ErrorCode
description: Standardized error codes for the API.
securitySchemes:
BearerAuth:
type: apiKey
in: header
name: Authorization
description: Zinc API key (Bearer zn_...)
````