{"openapi":"3.1.0","info":{"title":"Neuron Cart API","description":"Headless cart, checkout, and orders. Every response is `{ success: true, data }` or `{ success: false, error: { code, message } }` — branch on `error.code`, never on `message`.\n\nAll money values are integer cents.\n\nGet a key at https://cart-admin.neuroncommerce.com/signup — new stores run against a sandbox, so checkout works before you configure any provider. Guides and the error catalog: https://neuroncommerce.com/developers\n\nNeuron Cart™ is a trademark of Xumulus Inc.","version":"v1","contact":{"name":"Neuron Cart","url":"https://neuroncommerce.com/developers"},"license":{"name":"Proprietary — © Xumulus Inc.","url":"https://neuroncommerce.com"}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"x-api-key","in":"header","description":"Tenant API key (`cs_live_…`). **Server-side only** — it identifies your store and must never reach a browser."},"customerToken":{"type":"apiKey","name":"x-customer-token","in":"header","description":"Customer JWT from any `/v1/auth/*` success. Optional: anonymous carts and guest checkout work without it."}},"schemas":{}},"paths":{"/openapi.json":{"get":{"tags":[],"responses":{"200":{"description":"Default Response"}}}},"/v1/carts/":{"post":{"tags":["carts"],"responses":{"200":{"description":"Default Response"}}}},"/v1/carts/{cartId}/attribution":{"put":{"tags":["carts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"gclid":{"type":"string","maxLength":500},"gbraid":{"type":"string","maxLength":500},"wbraid":{"type":"string","maxLength":500},"fbclid":{"type":"string","maxLength":500},"ttclid":{"type":"string","maxLength":500},"msclkid":{"type":"string","maxLength":500},"sccid":{"type":"string","maxLength":500},"twclid":{"type":"string","maxLength":500},"liclid":{"type":"string","maxLength":500},"_gl":{"type":"string","maxLength":500},"utmSource":{"type":"string","maxLength":255},"utmMedium":{"type":"string","maxLength":255},"utmCampaign":{"type":"string","maxLength":255},"utmContent":{"type":"string","maxLength":255},"utmTerm":{"type":"string","maxLength":255},"referrer":{"type":"string","maxLength":2000},"landingUrl":{"type":"string","maxLength":2000},"channel":{"type":"string","maxLength":255}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/carts/session/{sessionToken}":{"get":{"tags":["carts"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"sessionToken","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/carts/{cartId}":{"get":{"tags":["carts"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/carts/mine":{"get":{"tags":["carts"],"responses":{"200":{"description":"Default Response"}}}},"/v1/carts/{cartId}/items":{"post":{"tags":["carts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sku":{"type":"string","minLength":1},"quantity":{"default":1,"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["sku"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"tags":["carts"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/carts/{cartId}/items/{itemId}":{"patch":{"tags":["carts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quantity":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["quantity"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true},{"schema":{"type":"string"},"in":"path","name":"itemId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"tags":["carts"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true},{"schema":{"type":"string"},"in":"path","name":"itemId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/carts/{cartId}/merge":{"post":{"tags":["carts"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/carts/{cartId}/coupon":{"post":{"tags":["carts"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"tags":["carts"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/carts/{cartId}/gift-card":{"post":{"tags":["carts"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"tags":["carts"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/carts/gift-card/balance":{"get":{"tags":["carts"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/register":{"post":{"tags":["auth"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/login":{"post":{"tags":["auth"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/refresh":{"post":{"tags":["auth"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/magic-link":{"post":{"tags":["auth"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/magic-link/verify":{"post":{"tags":["auth"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/otp/request":{"post":{"tags":["auth"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/otp/verify":{"post":{"tags":["auth"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/otp/email/request":{"post":{"tags":["auth"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/otp/email/verify":{"post":{"tags":["auth"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/password/reset-request":{"post":{"tags":["auth"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/password/reset":{"post":{"tags":["auth"],"responses":{"200":{"description":"Default Response"}}}},"/v1/auth/logout":{"post":{"tags":["auth"],"responses":{"200":{"description":"Default Response"}}}},"/v1/checkout/sessions":{"post":{"tags":["checkout"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cartId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["cartId"]}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/checkout/sessions/{cartId}/shipping-address":{"put":{"tags":["checkout"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":1},"lastName":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"type":"string"},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1},"postalCode":{"type":"string","minLength":1},"country":{"default":"US","type":"string","minLength":2,"maxLength":2},"phone":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["firstName","lastName","line1","city","state","postalCode"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/checkout/sessions/{cartId}/verify-address":{"post":{"tags":["checkout"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/checkout/sessions/{cartId}/shipping-rates":{"get":{"tags":["checkout"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/checkout/sessions/{cartId}/quote/resume":{"post":{"tags":["checkout"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/checkout/sessions/{cartId}/shipping-rate":{"put":{"tags":["checkout"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rateId":{"type":"string","minLength":1},"rateName":{"type":"string","minLength":1},"amount":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["rateId","rateName","amount"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/checkout/sessions/{cartId}/payment-intent":{"post":{"tags":["checkout"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/checkout/eligibility":{"get":{"tags":["checkout"],"responses":{"200":{"description":"Default Response"}}}},"/v1/checkout/sessions/{cartId}/express-prepare":{"post":{"tags":["checkout"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/checkout/sessions/{cartId}/wallet-rates":{"post":{"tags":["checkout"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/checkout/sessions/{cartId}/wallet-express":{"post":{"tags":["checkout"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/checkout/sessions/{cartId}/confirm":{"post":{"tags":["checkout"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"paymentIntentId":{"type":"string","minLength":1},"billingAddress":{"type":"object","properties":{"firstName":{"type":"string","minLength":1},"lastName":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"type":"string"},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1},"postalCode":{"type":"string","minLength":1},"country":{"default":"US","type":"string","minLength":2,"maxLength":2},"phone":{"type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["firstName","lastName","line1","city","state","postalCode"]},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"notes":{"type":"string","maxLength":500},"providerId":{"type":"string"}},"required":["paymentIntentId","billingAddress"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/orders/":{"get":{"tags":["orders"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"page","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100},"in":"query","name":"pageSize","required":false},{"schema":{"type":"string","enum":["pending","confirmed","processing","shipped","delivered","cancelled","refunded","partially_refunded"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"customerId","required":false},{"schema":{"type":"string","minLength":1,"maxLength":120},"in":"query","name":"search","required":false},{"schema":{"type":"string","enum":["createdAt","orderNumber","total","status","customer"]},"in":"query","name":"sortBy","required":false},{"schema":{"type":"string","enum":["asc","desc"]},"in":"query","name":"sortDir","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/v1/orders/{orderId}":{"get":{"tags":["orders"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/orders/number/{orderNumber}":{"get":{"tags":["orders"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderNumber","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/orders/{orderId}/status":{"patch":{"tags":["orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","confirmed","processing","shipped","delivered","cancelled","refunded","partially_refunded"]}},"required":["status"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/orders/{orderId}/shipments":{"post":{"tags":["orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"carrierCode":{"type":"string","minLength":1,"maxLength":40},"trackingNumber":{"type":"string","minLength":1,"maxLength":120},"trackingUrl":{"type":"string","maxLength":500,"format":"uri"},"notes":{"type":"string","maxLength":2000},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"status":{"type":"string","enum":["pending","in_transit","delivered","exception","returned","cancelled"]}},"required":["carrierCode","trackingNumber"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"responses":{"200":{"description":"Default Response"}}},"get":{"tags":["orders"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/orders/{orderId}/sms-notifications":{"post":{"tags":["orders"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/orders/{orderId}/shipments/{shipmentId}":{"patch":{"tags":["orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["pending","in_transit","delivered","exception","returned","cancelled"]}},"required":["status"]}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true},{"schema":{"type":"string"},"in":"path","name":"shipmentId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/customers/me":{"get":{"tags":["customers"],"responses":{"200":{"description":"Default Response"}}},"put":{"tags":["customers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":1},"lastName":{"type":"string","minLength":1},"phone":{"type":"string"}}}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/customers/me/addresses":{"get":{"tags":["customers"],"responses":{"200":{"description":"Default Response"}}},"post":{"tags":["customers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","maxLength":50},"firstName":{"type":"string","minLength":1},"lastName":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"type":"string"},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1},"postalCode":{"type":"string","minLength":1},"country":{"default":"US","type":"string","minLength":2,"maxLength":2},"phone":{"type":"string"},"isDefault":{"type":"boolean"}},"required":["firstName","lastName","line1","city","state","postalCode"]}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/customers/me/addresses/{addressId}":{"get":{"tags":["customers"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"addressId","required":true}],"responses":{"200":{"description":"Default Response"}}},"put":{"tags":["customers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","maxLength":50},"firstName":{"type":"string","minLength":1},"lastName":{"type":"string","minLength":1},"line1":{"type":"string","minLength":1},"line2":{"type":"string"},"city":{"type":"string","minLength":1},"state":{"type":"string","minLength":1},"postalCode":{"type":"string","minLength":1},"country":{"default":"US","type":"string","minLength":2,"maxLength":2},"phone":{"type":"string"},"isDefault":{"type":"boolean"}}}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"addressId","required":true}],"responses":{"200":{"description":"Default Response"}}},"delete":{"tags":["customers"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"addressId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/customers/me/sms-consent":{"get":{"tags":["customers"],"responses":{"200":{"description":"Default Response"}}},"put":{"tags":["customers"],"responses":{"200":{"description":"Default Response"}}}},"/v1/customers/me/email/claim":{"post":{"tags":["customers"],"responses":{"200":{"description":"Default Response"}}}},"/v1/customers/me/email/verify":{"post":{"tags":["customers"],"responses":{"200":{"description":"Default Response"}}}},"/v1/payments/providers":{"get":{"tags":["payments"],"responses":{"200":{"description":"Default Response"}}}},"/v1/payments/orders/{orderId}/refund":{"post":{"tags":["payments"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/payments/orders/{orderId}/void":{"post":{"tags":["payments"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/payments/orders/{orderId}/transactions":{"get":{"tags":["payments"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/payments/methods":{"get":{"tags":["payments"],"responses":{"200":{"description":"Default Response"}}},"post":{"tags":["payments"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"providerId":{"type":"string","minLength":1},"paymentToken":{"type":"string","minLength":1}},"required":["providerId","paymentToken"]}}}},"responses":{"200":{"description":"Default Response"}}}},"/v1/payments/methods/{paymentMethodId}":{"delete":{"tags":["payments"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"paymentMethodId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/upsells/recommendations":{"post":{"tags":["upsells"],"responses":{"200":{"description":"Default Response"}}}},"/v1/upsells/orders/{orderId}/offers":{"get":{"tags":["upsells"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/upsells/orders/{orderId}/accept":{"post":{"tags":["upsells"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/upsells/orders/{orderId}":{"get":{"tags":["upsells"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"orderId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/config/":{"get":{"tags":["config"],"responses":{"200":{"description":"Default Response"}}}},"/v1/add-ons/carts/{cartId}":{"get":{"tags":["add-ons"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/add-ons/carts/{cartId}/warranty/offers":{"get":{"tags":["add-ons"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/add-ons/carts/{cartId}/warranty":{"post":{"tags":["add-ons"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/add-ons/carts/{cartId}/insurance/quote":{"get":{"tags":["add-ons"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/add-ons/carts/{cartId}/insurance":{"post":{"tags":["add-ons"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/add-ons/carts/{cartId}/{addOnId}":{"delete":{"tags":["add-ons"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"cartId","required":true},{"schema":{"type":"string"},"in":"path","name":"addOnId","required":true}],"responses":{"200":{"description":"Default Response"}}}},"/v1/signup/":{"post":{"tags":["signup"],"responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://cart-api.neuroncommerce.com","description":"Production"}],"security":[{"apiKey":[]}],"tags":[{"name":"carts","description":"Cart lifecycle, line items, coupons, gift cards."},{"name":"checkout","description":"The six-step checkout, plus express and wallet paths."},{"name":"orders","description":"Order read and shipment tracking."},{"name":"customers","description":"Profile, address book, SMS consent."},{"name":"auth","description":"Customer registration, login, OTP, magic links."},{"name":"payments","description":"Providers, saved methods, refunds."},{"name":"upsells","description":"Recommendations and post-purchase offers."},{"name":"add-ons","description":"Warranty and shipping protection."},{"name":"config","description":"Browser-safe storefront configuration."}]}