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/{line_id}— Update a line item's quantityDELETE /cart-sessions/{id}/line-items/{line_id}— 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
Scope: cart:write
Path Parameters
uuidResponse Body
application/json
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": "8c9d0e1f-2a3b-4c54-8e5f-6a7b8c9d0e53", "object": "cart_session", "merchant_id": "8f14e45f-ceea-4e7a-9b4b-7c3f1a2d5e60", "customer_id": "c2a1e7d4-5b3f-4a8e-9d21-6f0b3e4c7a11", "currency": "GBP", "mode": "subscription", "status": "converted", "line_items": [ { "id": "cli_3f6c2a1e-8b4d-4e7f-9a2c-5d1e0f3b6a74", "product_id": "a7b3c9d2-1e4f-4b6a-8c5d-2f9e0a1b3c42", "name": "Pro plan", "quantity": 1, "unit_price_minor": 4900, "currency": "GBP", "recurring": { "interval": "month", "interval_count": 1 }, "billing_max_cycles": null, "trial_period_days": 14, "start_rule": "immediate", "billing_anchor_rule": "same_day", "billing_anchor_day": null, "due_today_minor": 0, "first_charge_minor": 4900, "first_renewal_at": "2026-05-02T09:00:00.000Z", "effective_start_rule": "immediate", "metadata": null } ], "add_ons_offered": [], "add_ons_selected": [], "discount_code": null, "email": "ada.lovelace@example.com", "promotional_consent": false, "sms_consent": false, "subtotal_minor": 4900, "total_minor": 4900, "metadata": null, "converted_to_checkout_session_id": "9d0e1f2a-3b4c-4d65-9f6a-7b8c9d0e1f64", "public_token": "cart_tok_example_7q2k9m", "created_at": "2026-04-18T09:00:00.000Z", "updated_at": "2026-04-18T09:05:00.000Z", "expires_at": "2026-04-19T09:00:00.000Z" }, "checkout_session": { "id": "9d0e1f2a-3b4c-4d65-9f6a-7b8c9d0e1f64", "object": "checkout_session", "merchant_id": "8f14e45f-ceea-4e7a-9b4b-7c3f1a2d5e60", "customer_id": "c2a1e7d4-5b3f-4a8e-9d21-6f0b3e4c7a11", "session_token": "rvk_cs_example_8m3x", "checkout_url": "https://pay.revkeen.com/p/rvk_cs_example_8m3x", "status": "pending", "mode": "subscription", "amount_minor": 4900, "currency": "GBP", "line_items": [ { "id": "cli_3f6c2a1e-8b4d-4e7f-9a2c-5d1e0f3b6a74", "product_id": "a7b3c9d2-1e4f-4b6a-8c5d-2f9e0a1b3c42", "name": "Pro plan", "quantity": 1, "unit_price_minor": 4900, "currency": "GBP", "recurring": { "interval": "month", "interval_count": 1 }, "billing_max_cycles": null, "trial_period_days": 14, "start_rule": "immediate", "billing_anchor_rule": "same_day", "billing_anchor_day": null, "due_today_minor": 0, "first_charge_minor": 4900, "first_renewal_at": "2026-05-02T09:00:00.000Z", "effective_start_rule": "immediate", "metadata": null } ], "metadata": null, "expires_at": "2026-04-18T10:05:00.000Z", "created_at": "2026-04-18T09:05:00.000Z", "updated_at": "2026-04-18T09:05:00.000Z" } }}