BrainerceCreate checkout from cart
Honors Idempotency-Key header. See /docs/api/idempotency. Strongly recommended on this endpoint.
Admin API key (server-to-server). Issue via the dashboard at Settings → API keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.
In: header
Header Parameters
Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.
- Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
- Reusing a key with a different body returns
409 Conflictwithcode: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response. - Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
- Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
- Sending this header on a
GETreturns400withcode: "IDEMPOTENCY_KEY_NOT_SUPPORTED"— GETs are already idempotent. - Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.
length <= 255ID of the cart to convert into a checkout. The cart must belong to the same store and contain at least one purchasable line item.
ID of the logged-in customer to attach to the checkout. When omitted, the checkout is treated as a guest checkout and the customer record (if any) is matched/created from the email on setCustomerInfo.
Subset of cart line-item IDs to include in this checkout. Use this for "buy now" / express-checkout flows that purchase a single item from a larger cart. When omitted, every line item in the cart is included.
ID of the region to associate with this checkout (multi-region commerce). The region must belong to the same store. Recorded for reporting + provider scoping. FX-at-checkout: when the region currency differs from the store base AND its payment provider can settle that currency (presentment-enabled, which today means Stripe), the checkout pins a charging rate and the payment intent is charged in the region currency; the response carries a presentment overlay with the charged amounts. Otherwise the checkout is charged in the store base currency (presentment unavailable → safe fallback). When omitted, the store default region applies.
curl -X POST "https://api.brainerce.com/api/v1/checkout" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "cartId": "cart_01HQ7Z2YK3M8N4P5R6S7T8V9W0" }'{
"id": "clx1a2b3c4d5e6f7g8h9",
"status": "PENDING",
"email": "[email protected]",
"customerId": "clx1a2b3c4d5e6f7g8h9",
"deliveryType": "shipping",
"pickupLocation": {
"id": "clx1a2b3c4d5e6f7g8h9",
"name": "Main store",
"rateName": "Store pickup",
"address": {
"line1": "Herzl 12",
"line2": "Apt 4",
"city": "Tel Aviv",
"region": "Center District",
"postalCode": "6578301",
"country": "IL"
},
"phone": "+972501234567",
"hours": "Sun-Thu 09:00-18:00",
"instructions": "Bring your order number",
"price": "0.00",
"currency": "USD"
},
"shippingAddress": {
"firstName": "Dana",
"lastName": "Cohen",
"company": "Acme Ltd",
"line1": "Herzl 12",
"line2": "Apt 4",
"city": "Tel Aviv",
"region": "Center District",
"postalCode": "6578301",
"country": "IL",
"phone": "+972501234567"
},
"billingAddress": {
"firstName": "Dana",
"lastName": "Cohen",
"company": "Acme Ltd",
"line1": "Herzl 12",
"line2": "Apt 4",
"city": "Tel Aviv",
"region": "Center District",
"postalCode": "6578301",
"country": "IL",
"phone": "+972501234567"
},
"shippingRateId": "clx1a2b3c4d5e6f7g8h9",
"shippingMethod": {
"id": "clx1a2b3c4d5e6f7g8h9",
"name": "Standard shipping",
"description": "Delivery in 3 to 5 business days",
"price": "15.00",
"currency": "USD",
"estimatedDays": 4,
"source": "manual",
"carrier": "ups",
"service": "ground",
"speedTier": "cheapest",
"requiresPickupPoint": true
},
"currency": "USD",
"subtotal": "59.80",
"discountAmount": "5.00",
"ruleDiscountAmount": "5.00",
"appliedRules": [
{
"id": "clx1a2b3c4d5e6f7g8h9",
"name": "Summer sale",
"type": "ORDER_DISCOUNT",
"discountAmount": "10.00"
}
],
"shippingAmount": "15.00",
"taxAmount": "11.46",
"taxBreakdown": {
"subtotal": 50.9,
"shippingNet": 12.71,
"totalTax": 11.46,
"total": 75.1,
"breakdown": [
{
"name": "VAT",
"rate": 18,
"amount": 9.17
}
],
"currency": "USD"
},
"total": "81.26",
"surchargeAmount": "0.00",
"appliedSurcharges": [
{
"key": "handling",
"name": "Handling fee",
"value": "string",
"amount": "5.00"
}
],
"customFieldValues": {},
"couponCode": "WELCOME10",
"tenders": [
{
"tenderId": "clx1a2b3c4d5e6f7g8h9",
"amountApplied": "50.00"
}
],
"providerAmountDue": "81.26",
"notes": "Leave at the door",
"lineItems": [
{
"id": "clx1a2b3c4d5e6f7g8h9",
"productId": "clx1a2b3c4d5e6f7g8h9",
"variantId": "clx1a2b3c4d5e6f7g8h9",
"quantity": 2,
"unitPrice": "29.90",
"discountAmount": "0.00",
"product": {
"id": "clx1a2b3c4d5e6f7g8h9",
"name": "Classic T-Shirt",
"sku": "TSHIRT-BLK-M",
"images": [
{}
],
"isDownloadable": true
},
"variant": {
"id": "clx1a2b3c4d5e6f7g8h9",
"name": "Black / M",
"sku": "TSHIRT-BLK-M"
},
"notes": "Gift wrap please",
"metadata": {},
"customizations": {}
}
],
"itemCount": 2,
"availableShippingRates": [
{
"id": "clx1a2b3c4d5e6f7g8h9",
"name": "Standard shipping",
"description": "Delivery in 3 to 5 business days",
"price": "15.00",
"currency": "USD",
"estimatedDays": 4,
"source": "manual",
"carrier": "ups",
"service": "ground",
"speedTier": "cheapest",
"requiresPickupPoint": true
}
],
"expiresAt": "2019-08-24T14:15:22Z",
"recoveryEmailSentAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"reservation": {
"hasReservation": true,
"expiresAt": "2019-08-24T14:15:22Z",
"remainingSeconds": 540,
"strategy": "ON_PAYMENT",
"countdownMessage": "Your items are reserved for 9 minutes"
},
"presentment": {
"currency": "USD",
"subtotal": "59.80",
"discountAmount": "0.00",
"shippingAmount": "15.00",
"taxAmount": "11.46",
"surchargeAmount": "0.00",
"total": "86.26",
"fxChargingRate": "3.65",
"fxBufferPercent": "2.00"
},
"pickupPoint": {
"id": "pp_48213",
"name": "Kiosk Herzl",
"kind": "store",
"address": {
"street1": "Herzl 12",
"city": "Tel Aviv",
"zip": "6578301",
"country": "IL"
},
"latitude": 32.0668,
"longitude": 34.7647,
"hours": "Sun-Thu 08:00-20:00",
"note": "Next to the pharmacy",
"distanceKm": 0.8
},
"totalAmount": "81.26"
}{
"statusCode": 400,
"code": "VALIDATION_FAILED",
"message": "name should not be empty, price must be a positive number",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/checkout"
}{
"statusCode": 401,
"code": "UNAUTHORIZED",
"message": "Invalid or expired credential",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/checkout"
}{
"statusCode": 403,
"code": "INSUFFICIENT_SCOPE",
"message": "API key does not have the required scope: products:write",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/checkout"
}{
"statusCode": 404,
"code": "RESOURCE_NOT_FOUND",
"message": "Resource not found",
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/checkout"
}{
"statusCode": 429,
"code": "RATE_LIMITED",
"message": "Too many requests",
"details": {
"retryAfterSeconds": 12
},
"timestamp": "2026-08-23T10:15:00.000Z",
"path": "/api/v1/store"
}