Convert a cart session into a checkout session
Atomically materialise a pending checkout session from the cart snapshot, reserve tracked availability, flip the cart to converted, and emit commerce.cart.converted + commerce.checkout.started through the outbox.
/cart-sessions/{id}/convertAtomically materialise a pending checkout session from the cart snapshot, reserve tracked availability, flip the cart to converted, and emit commerce.cart.converted + commerce.checkout.started through the outbox.
Idempotent on re-call (returns the existing checkout session). Concurrency-safe via a compare-and-swap lock on cart status; product availability is guarded by the database reserve step.
Validation that runs inside the lock and rolls back on failure:
CART_SESSION_EMPTY— the cart has no line items.AVAILABILITY_EXCEEDED— a tracked/capacity-limited product can no longer satisfy the requested quantity.CART_SESSION_NOT_FOUND— no cart for this id under the calling merchant.CART_SESSION_CLOSED— the cart is alreadyabandonedorexpired.
On rollback the cart returns to open and the customer can retry after fixing the cause.
Related endpoints
POST /cart-sessions— Create a cart sessionGET /cart-sessions/{id}— Retrieve a cart sessionPOST /cart-sessions/{id}/line-items— Add a line item to a cart sessionPATCH /cart-sessions/{id}/line-items/{lineId}— Update a line item's quantityDELETE /cart-sessions/{id}/line-items/{lineId}— Remove a line item from a cart sessionPOST /cart-sessions/{id}/add-ons— Toggle an add-on on a cart sessionPOST /cart-sessions/{id}/discount-code— Set or clear a cart discount codePOST /cart-sessions/{id}/contact— Capture customer email + consent on a cart
Common errors
401 authentication_error— missing, invalid, expired, or revoked credential. Codes:authentication_failed,invalid_api_key,expired_api_key,api_key_revoked,session_invalid,merchant_required. Carries aWWW-Authenticate: Bearerchallenge.404 resource_missing— the referenced resource does not exist or is not visible to your key.409 conflict— Idempotency-Key collision with a different body, or a concurrent state-transition conflict.
Idempotency
Pass an Idempotency-Key header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see the idempotency guide.
Your RevKeen merchant API key. Create and manage keys in Dashboard → Settings → Developer. Use rk_sandbox_* for staging/test and rk_live_* for production. The same key may be sent as Authorization: Bearer <key> if that suits your HTTP client better. A missing, invalid, expired, or revoked key returns 401 with a WWW-Authenticate: Bearer challenge; a valid key without the required scope returns 403.
In: header
Path Parameters
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://api.revkeen.com/v2/cart-sessions/11111111-1111-4111-8111-111111111111/convert" \
-H "x-api-key: $REVKEEN_API_KEY"Synthetic documentation data, validated against the response schema; not a live API result.
{ "data": { "cart_session": { "id": "00000000-0000-4000-8000-000000000001", "object": "cart_session", "merchant_id": "00000000-0000-4000-8000-000000000001", "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e", "currency": "str", "mode": "payment", "status": "open", "line_items": [ { "id": "cli_550e8400-e29b-41d4-a716-446655440000", "product_id": "00000000-0000-4000-8000-000000000001", "name": "Example customer", "quantity": 1, "unit_price_minor": 0, "currency": "str", "recurring": { "interval": "month", "interval_count": 1 }, "billing_max_cycles": 1, "trial_period_days": 0, "start_rule": "immediate", "billing_anchor_rule": "same_day", "billing_anchor_day": 1, "due_today_minor": 0, "first_charge_minor": 0, "first_renewal_at": "2019-08-24T14:15:22Z", "effective_start_rule": "immediate", "metadata": { "property1": null, "property2": null } } ], "add_ons_offered": [ "00000000-0000-4000-8000-000000000001" ], "add_ons_selected": [ "00000000-0000-4000-8000-000000000001" ], "discount_code": "string", "email": "user@example.com", "promotional_consent": true, "sms_consent": true, "subtotal_minor": 0, "total_minor": 0, "metadata": { "property1": null, "property2": null }, "converted_to_checkout_session_id": "5d37f263-6519-4765-9535-e6aa5913d87c", "public_token": "string", "created_at": "2026-09-01T12:00:00Z", "updated_at": "2026-09-01T12:00:00Z", "expires_at": "2026-09-01T12:00:00Z" }, "checkout_session": { "id": "00000000-0000-4000-8000-000000000001", "object": "checkout_session", "merchant_id": "00000000-0000-4000-8000-000000000001", "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e", "session_token": "string", "status": "pending", "mode": "string", "amount_minor": 0, "currency": "string", "line_items": [ { "id": "cli_550e8400-e29b-41d4-a716-446655440000", "product_id": "00000000-0000-4000-8000-000000000001", "name": "Example customer", "quantity": 1, "unit_price_minor": 0, "currency": "str", "recurring": { "interval": "month", "interval_count": 1 }, "billing_max_cycles": 1, "trial_period_days": 0, "start_rule": "immediate", "billing_anchor_rule": "same_day", "billing_anchor_day": 1, "due_today_minor": 0, "first_charge_minor": 0, "first_renewal_at": "2019-08-24T14:15:22Z", "effective_start_rule": "immediate", "metadata": { "property1": null, "property2": null } } ], "metadata": { "property1": null, "property2": null }, "expires_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" } }}