commerce

POST `/v1/carts/adopt`

Carry a guest basket into the signed-in account.

Authentication

Send an API key as a bearer token. The key must carry the billing.payment.manage permission; a key without it is refused with 403, not 404.

Where your organisation id goes

This endpoint takes org_id as a field in the JSON body.

Your organisation id is on the API keys screen in your dashboard, beside the key itself. It is the same id in every call you make.

Try it

Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.

curl -X POST https://api.zinndigital.com/v1/carts/adopt \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "token": <string> }'

Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console

Details

Moves the items of an anonymous guest cart into the caller's organization cart, so a visitor who built a basket on the public site and then signed in continues instead of starting again (`docs/87` §575, #2599). ⛔ **Two credentials, both required.** The raw cart `token` proves the caller built the basket; the authenticated principal decides which organization it lands in. Neither alone is sufficient — a token cannot name a destination and a session cannot claim a basket it never held. One-way and idempotent: the guest cart is closed under a conditional update, so a double-submit or a refresh adopts once. Requires `billing.payment.manage`. ⛔ Declared before `/v1/carts/{cartId}` so the literal `adopt` is not read as a cart id.

Request body

Name	Type	Required	What it is
`token`	`string`	Yes	The guest cart's raw bearer token — never its digest. The caller proves possession of the credential that already lets them read and modify that cart, so adoption grants not…
`org_id`	`string`	No	Required only when the caller manages billing for more than one organization.

Response

Name	Type	Required	What it is
`cart_id`	`string`	Yes	The organization cart the items now live in. Empty when the guest basket held nothing — which is a success with zero moved, not a failure.
`adopted`	`integer`	Yes	How many items were carried over.

Errors this endpoint can return

401 · 403 · 422 · 429