Elastic Path · Schema
Carts, Checkout, Orders Introduction
A cart contains a list of the products that a shopper adds to the cart while browsing your catalog. In the context of a cart, a selected product is called a cart item.
CommerceHeadless CommerceComposable CommerceeCommerceB2BProductsCatalogsOrdersPromotionsSubscriptionsPayments
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/api-evangelist/elastic-path/main/json-schema/carts.json",
"title": "Carts, Checkout, Orders Introduction",
"description": "A cart contains a list of the products that a shopper adds to the cart while browsing your catalog. In the context of a cart, a selected product is called a cart item.",
"version": "26.0313.7324347",
"$defs": {
"CartContact": {
"title": "CartContact",
"type": "object",
"properties": {
"email": {
"description": "The email address attached to a cart.",
"type": "string",
"format": "email",
"examples": [
"[email protected]"
]
}
}
},
"DiscountSettings": {
"title": "DiscountSettings",
"type": "object",
"properties": {
"custom_discounts_enabled": {
"description": "This parameter enables custom discounts for a cart. When set to true, Elastic Path promotions will not be applied to the new carts. Default is set from cart discount settings for the store. See [Cart Settings](/docs/api/carts/put-v-2-settings-cart).",
"type": "boolean",
"examples": [
false
]
},
"use_rule_promotions": {
"description": "When set to true, this parameter allows the cart to use rule promotions.",
"type": "boolean",
"examples": [
false
]
}
}
},
"InventorySettings": {
"title": "InventorySettings",
"type": "object",
"properties": {
"defer_inventory_check": {
"description": "This parameter enables deferring inventory checks on the cart. This allows items to be added to or updating in the cart without checking stock levels. Inventory checks are still performed as normal on checkout",
"type": "boolean",
"examples": [
false
]
}
}
},
"ItemSettings": {
"title": "ItemSettings",
"type": "object",
"properties": {
"separate_items_by_location": {
"description": "When set to true, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When false (default), items with the same SKU are merged and the location is updated to the most recent value.",
"type": "boolean",
"examples": [
false
]
}
}
},
"CustomAttributes": {
"title": "CustomAttributes",
"type": "object",
"description": "Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n \"is_member\": {\n \"type\": \"boolean\",\n \"value\": true\n },",
"additionalProperties": {
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"type": "string",
"description": "The type of the custom attribute value.",
"enum": [
"string",
"integer",
"boolean",
"float"
]
},
"value": {
"description": "The value of the custom attribute.",
"type": [
"string",
"boolean",
"number"
]
}
}
}
},
"FormattedPriceData": {
"title": "FormattedPriceData",
"type": "object",
"properties": {
"amount": {
"description": "The raw total.",
"type": "number",
"examples": [
10000
]
},
"currency": {
"description": "The currency set for this amount.",
"type": "string",
"examples": [
"USD"
]
},
"formatted": {
"description": "The formatted total based on the amount and currency.",
"type": "string",
"examples": [
"$10.00"
]
}
}
},
"CartTimestamps": {
"type": "object",
"properties": {
"created_at": {
"description": "The date this was created.",
"type": "string"
},
"updated_at": {
"description": "The date this was last updated.",
"type": "string"
},
"expires_at": {
"description": "The date this expires.",
"type": "string"
}
}
},
"RelationshipItem": {
"title": "RelationshipItem",
"description": "Relationship data entry",
"required": [
"type",
"id"
],
"type": "object",
"properties": {
"type": {
"description": "The type of related resource.",
"type": "string"
},
"id": {
"description": "The ID of the related resource.",
"type": "string",
"format": "uuid"
}
}
},
"RelationshipArray": {
"title": "RelationshipArray",
"description": "Array of relationships",
"type": "object",
"properties": {
"data": {
"description": "Individual relationships",
"type": "array",
"items": {
"$ref": "#/components/schemas/RelationshipItem"
}
}
}
},
"BaseCartResponse": {
"title": "BaseCartResponse",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for the cart. Use SDK or create it yourself.",
"type": "string"
},
"name": {
"description": "The name of this cart.",
"type": "string",
"examples": [
"cart name"
]
},
"description": {
"description": "A description of the cart.",
"type": "string",
"examples": [
"cart description"
]
},
"contact": {
"$ref": "#/components/schemas/CartContact"
},
"discount_settings": {
"$ref": "#/components/schemas/DiscountSettings"
},
"inventory_settings": {
"$ref": "#/components/schemas/InventorySettings"
},
"item_settings": {
"$ref": "#/components/schemas/ItemSettings"
},
"payment_intent_id": {
"description": "Stripe-assigned unique identifier for the linked Payment Intent",
"type": "string"
},
"custom_attributes": {
"$ref": "#/components/schemas/CustomAttributes"
},
"snapshot_date": {
"description": "The snapshot date for the cart.",
"type": "string",
"format": "date-time"
},
"links": {
"type": "object",
"properties": {
"self": {
"description": "A link to that specific resource.",
"type": "string"
}
},
"examples": [
"https://useast.api.elasticpath.com/v2/carts/1"
]
},
"meta": {
"type": "object",
"properties": {
"display_price": {
"type": "object",
"properties": {
"with_tax": {
"$ref": "#/components/schemas/FormattedPriceData"
},
"without_tax": {
"$ref": "#/components/schemas/FormattedPriceData"
},
"tax": {
"$ref": "#/components/schemas/FormattedPriceData"
},
"discount": {
"$ref": "#/components/schemas/FormattedPriceData"
},
"without_discount": {
"$ref": "#/components/schemas/FormattedPriceData"
},
"shipping": {
"$ref": "#/components/schemas/FormattedPriceData"
},
"shipping_discount": {
"$ref": "#/components/schemas/FormattedPriceData"
}
}
},
"timestamps": {
"$ref": "#/components/schemas/CartTimestamps"
},
"promotion_suggestions": {
"description": "Array of promotion suggestions",
"type": "array",
"items": {
"type": "object",
"properties": {
"bundle": {
"description": "Bundle configuration with promotion targets",
"type": "array",
"items": {
"type": "object",
"properties": {
"auto_add_free_gift": {
"description": "Whether to automatically add free gift",
"type": "boolean"
},
"cart_item_id": {
"description": "Cart item ID for the target",
"type": "string"
},
"quantity": {
"description": "Quantity for the promotion",
"type": "integer"
},
"targets": {
"description": "Array of target SKUs",
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": true
}
},
"code": {
"type": "string"
},
"info": {
"type": "string"
},
"message": {
"type": "string"
},
"promotion_id": {
"type": "string"
}
}
}
}
}
},
"relationships": {
"type": "object",
"properties": {
"customers": {
"anyOf": [
{
"$ref": "#/components/schemas/RelationshipArray"
},
{
"type": "object",
"maxProperties": 0
}
]
},
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/RelationshipArray"
},
{
"type": "object",
"properties": {
"data": {
"oneOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"type": {
"type": "string"
}
}
}
}
]
}
},
"required": [
"data"
]
}
]
},
"accounts": {
"anyOf": [
{
"$ref": "#/components/schemas/RelationshipArray"
},
{
"type": "object",
"maxProperties": 0
}
]
},
"custom_discounts": {
"$ref": "#/components/schemas/RelationshipArray"
},
"promotions": {
"$ref": "#/components/schemas/RelationshipArray"
}
}
}
}
},
"CartResponse": {
"title": "CartResponse",
"allOf": [
{
"$ref": "#/components/schemas/BaseCartResponse"
},
{
"type": "object",
"properties": {
"type": {
"description": "The type of object being returned.",
"type": "string",
"const": "cart"
}
}
}
]
},
"Response.PageLinks": {
"type": "object",
"properties": {
"current": {
"description": "Always the current page.",
"type": "string"
},
"first": {
"description": "Always the first page.",
"type": "string"
},
"last": {
"description": "If there is only one page, it is `null`.",
"type": "string"
},
"next": {
"description": "If there is only one page, it is `null`.",
"type": "string"
},
"prev": {
"description": "if the user is on the first page, it is `null`.",
"type": "string"
}
}
},
"Response.PaginationPage": {
"type": "object",
"properties": {
"current": {
"description": "The current page.",
"type": "integer"
},
"limit": {
"description": "The maximum number of records per page for this response. You can set this value up to 100.",
"type": "integer"
},
"offset": {
"description": "The current offset by number of records, not pages. Offset is zero-based.",
"type": "integer"
},
"total": {
"description": "The total page count.",
"type": "integer"
}
}
},
"Response.PaginationResults": {
"type": "object",
"properties": {
"total": {
"description": "The total page count.",
"type": "integer"
}
}
},
"Response.Meta.Carts": {
"type": "object",
"properties": {
"page": {
"$ref": "#/components/schemas/Response.PaginationPage"
},
"results": {
"$ref": "#/components/schemas/Response.PaginationResults"
}
}
},
"CartCollectionResponse": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CartResponse"
}
},
"links": {
"$ref": "#/components/schemas/Response.PageLinks"
},
"meta": {
"$ref": "#/components/schemas/Response.Meta.Carts"
}
},
"required": [
"data"
]
},
"Response.ErrorItem": {
"type": "object",
"required": [
"status",
"title"
],
"properties": {
"title": {
"type": "string",
"description": "A brief summary of the error.",
"examples": [
"Bad Request"
]
},
"status": {
"type": [
"string",
"integer"
],
"description": "The HTTP response code of the error.",
"examples": [
"400"
]
},
"detail": {
"type": "string",
"description": "Optional additional detail about the error.",
"examples": [
"The field 'name' is required"
]
},
"source": {
"type": "string",
"description": "The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity')."
},
"meta": {
"type": "object",
"description": "Additional metadata associated with the error. May include arbitrary keys.",
"properties": {
"id": {
"type": "string",
"description": "The resource id associated with the error"
},
"ids": {
"type": "array",
"items": {
"type": "string",
"description": "The resource ids associated with the error"
}
},
"item_ids": {
"type": "array",
"items": {
"type": "string",
"description": "The cart_item ids associated with the error"
}
},
"shipping_group_id": {
"type": "string",
"description": "The shipping group id associated with the error"
},
"shipping_group_ids": {
"type": "array",
"items": {
"type": "string",
"description": "The shipping group ids associated with the error"
}
},
"cart_id": {
"type": "string",
"description": "The cart id associated with the error"
},
"code": {
"type": "string",
"description": "The code associated with the error."
},
"order_id": {
"type": "string",
"description": "The order id associated with the error."
},
"sku": {
"type": "string",
"description": "The SKU associated with the error."
},
"email": {
"type": "string",
"format": "email",
"description": "The email address associated with the error."
},
"component_product_id": {
"type": "string",
"format": "uuid",
"description": "The component product ID associated with the error."
},
"error-meta-key": {
"type": "string",
"description": "Custom error metadata key used for additional error context (e.g., in payment rejections)."
},
"value": {
"description": "The value associated with the error.",
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
},
{
"type": "boolean"
},
{
"type": "object",
"additionalProperties": true
},
{
"type": "array"
}
]
}
}
}
}
},
"Response.ErrorResponse": {
"type": "object",
"required": [
"errors"
],
"properties": {
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Response.ErrorItem"
}
}
}
},
"CartsRequest": {
"title": "CartsRequest",
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "The cart description.",
"examples": [
"cart description"
]
},
"discount_settings": {
"$ref": "#/components/schemas/DiscountSettings"
},
"inventory_settings": {
"$ref": "#/components/schemas/InventorySettings"
},
"item_settings": {
"$ref": "#/components/schemas/ItemSettings"
},
"name": {
"description": "The cart name provided by the shopper. A cart name must contain 1 to 255 characters. You cannot use whitespace characters, but special characters are permitted. For more information, see the [Safe Characters](/guides/Getting-Started/safe-characters) section.",
"type": "string",
"examples": [
"my cart name"
]
},
"contact": {
"$ref": "#/components/schemas/CartContact"
},
"snapshot_date": {
"description": "This optional parameter sets a reference date for the cart. If this parameter is set, it allows the cart to act as one that might occur on that specified date. For example, such future carts might acquire future-enabled discounts, allowing users to test and validate future interactions with carts. The snapshot_date must be in the format 2026-02-21T15:07:25Z. By default, this parameter is left empty.",
"type": "string",
"examples": [
"2026-09-10T00:12:00Z"
]
},
"custom_attributes": {
"description": "Specifies custom attributes for cart objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nAttribute types include:\n - string\n - boolean\n - integer\n - float\n\nMultiple custom attributes may be submitted together. A cart can have a maximum of 20 custom attributes.\n\nExample:\n```\n\"custom_attributes\": {\n \"is_member\": {\n \"type\": \"boolean\",\n \"value\": true\n },\n \"membership_level\": {\n \"type\": \"string\",\n \"value\": \"premium\"\n }\n}\n```\n\nUpdating an existing cart with new custom attributes clears previously-saved attributes. In order to maintain existing custom attributes on a cart, please include them in the update request along with any new attributes.\n",
"$ref": "#/components/schemas/CustomAttributes"
},
"payment_intent_id": {
"description": "To remove the Stripe payment intent from a cart, pass the empty value in the `payment_intent_id` field. You must use an empty value for this field. You cannot use this endpoint to directly update the cart to use an existing Payment Intent.",
"type": "string",
"examples": [
""
]
}
}
}
}
},
"CustomDiscountResponse": {
"title": "CustomDiscountResponse",
"type": "object",
"properties": {
"type": {
"description": "Specifies the type of the resource. Always `custom_discount`.",
"type": "string",
"const": "custom_discount"
},
"id": {
"description": "Specifies the UUID of the custom discount.",
"type": "string",
"format": "uuid",
"examples": [
"662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"
]
},
"external_id": {
"description": "Specifies an external id for the custom discount.",
"type": "string",
"examples": [
"custom-discount-external-id"
]
},
"discount_engine": {
"description": "Specifies from where the custom discount is applied.\n",
"type": "string",
"examples": [
"Custom Discount Engine"
]
},
"amount": {
"description": "The amount of the custom discount.",
"$ref": "#/components/schemas/FormattedPriceData"
},
"description": {
"description": "Specifies a description for the custom discount.",
"type": "string",
"examples": [
"Custom discount description"
]
},
"discount_code": {
"description": "Specifies the discount code used for the custom discount.",
"type": "string",
"examples": [
"cart-custom-promo-code"
]
},
"relationships": {
"description": "Relationships to other resources like cart items",
"type": "object",
"properties": {
"item": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "The cart item ID this discount is related to"
},
"type": {
"type": "string",
"enum": [
"cart_item",
"custom_item"
]
}
}
}
}
}
}
}
}
},
"CondensedPromotionResponse": {
"title": "CondensedPromotionResponse",
"type": "object",
"properties": {
"type": {
"description": "Specifies the type of the resource. Always `promotion`.",
"type": "string",
"const": "promotion",
"examples": [
"promotion"
]
},
"id": {
"description": "Specifies the UUID of the promotion.",
"type": "string",
"format": "uuid",
"readOnly": true,
"examples": [
"662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9"
]
},
"name": {
"description": "The name of the promotion.",
"type": "string",
"examples": [
"Summer Sale"
]
},
"description": {
"description": "The description of the promotion.",
"type": "string",
"examples": [
"Get 20% off all summer items"
]
},
"automatic": {
"description": "Whether the promotion is applied automatically.",
"type": "boolean",
"examples": [
true
]
},
"promotion_type": {
"description": "The type of promotion (for v1 promotions).",
"type": "string",
"examples": [
"discount"
]
},
"promotion_source": {
"description": "The source of the promotion (for rule promotions).",
"type": "string",
"examples": [
"rule-promotion"
]
},
"start": {
"description": "The start date and time of the promotion.",
"type": "string",
"format": "date-time",
"examples": [
"2024-06-01T00:00:00Z"
]
},
"end": {
"description": "The end date and time of the promotion.",
"type": "string",
"format": "date-time",
"examples": [
"2024-08-31T23:59:59Z"
]
}
}
},
"CartEntityResponse": {
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/CartResponse"
},
"included": {
"type": "object",
"description": "Related objects that are included in the response.",
"properties": {
"custom_discounts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CustomDiscountResponse"
}
},
"promotions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CondensedPromotionResponse"
}
}
}
},
"meta": {
"type": "object",
"description": "Additional metadata for the cart response.",
"properties": {
"payment_intent": {
"type": "object",
"description": "Payment intent details with nested structure including status and other Stripe payment intent fields",
"additionalProperties": true
}
}
},
"errors": {
"type": "array",
"description": "Array of error objects, if any errors occurred.",
"items": {
"$ref": "#/components/schemas/Response.ErrorItem"
}
}
}
},
"ItemPriceData": {
"title": "Order Price Data",
"type": "object",
"properties": {
"amount": {
"description": "The amount for this item as an integer.",
"type": "number",
"readOnly": true,
"examples": [
10000
]
},
"currency": {
"description": "The currency this item was added to the cart as.",
"type": "string",
"readOnly": true,
"examples": [
"USD"
]
},
"includes_tax": {
"description": "Whether or not this price is tax inclusive.",
"type": "boolean",
"readOnly": true,
"examples": [
false
]
}
}
},
"Money": {
"type": "object",
"properties": {
"amount": {
"type": "integer",
"description": "Amount in minor currency units (e.g., cents)."
},
"currency": {
"type": "string",
"description": "ISO 4217 currency code (e.g., \"USD\")."
},
"includes_tax": {
"type": "boolean",
"description": "Whether the amount includes tax."
}
},
"required": [
"amount",
"currency",
"includes_tax"
]
},
"Discount": {
"type": "object",
"properties": {
"amount": {
"$ref": "#/components/schemas/Money"
},
"code": {
"type": "string",
"description": "The discount code used, if applicable."
},
"id": {
"type": "string",
"description": "Unique identifier for the discount."
},
"promotion_source": {
"type": "string",
"description": "The source or origin of the promotion, if applicable."
},
"is_cart_discount": {
"type": "boolean",
"description": "Indicates whether the discount applies to the entire cart."
},
"ordinal": {
"type": "integer",
"description": "Order in which the discount was applied."
}
},
"required": [
"amount",
"id"
]
},
"CartItemFormattedPriceData": {
"title": "CartItemFormattedPriceData",
"type": "object",
"properties": {
"unit": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/FormattedPriceData"
}
],
"description": "The amount per each single unit."
},
"value": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/FormattedPriceData"
}
],
"description": "The total amount of the item (i.e., unit * quantity)."
}
}
},
"Timestamps": {
"type": "object",
"properties": {
"created_at": {
"description": "The date this was created.",
"type": "string"
},
"updated_at": {
"description": "The date this was last updated.",
"type": "string"
}
}
},
"CartItemResponse": {
"title": "Cart Item Response",
"type": "object",
"properties": {
"id": {
"description": "The unique identifier for the cart item.",
"type": "string",
"format": "uuid",
"readOnly": true,
"examples": [
"4649fbb3-b8ee-4883-82c9-49a3d5fbacf1"
]
},
"type": {
"description": "The type of cart item.",
"type": "string",
"readOnly": true,
"enum": [
"cart_item",
"custom_item",
"subscription_item",
"promotion_item"
],
"examples": [
"cart_item"
]
},
"product_id": {
"description": "The unique ID of the product (for cart_item type).",
"type": "string",
"format": "uuid",
"readOnly": true,
"examples": [
"55cda543-f9d7-42a4-b40a-665f2e4ff7c5"
]
},
"promotion_id": {
"description": "The unique ID of the promotion (for promotion_item type).",
"type": "string",
"fo
# --- truncated at 32 KB (171 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/json-schema/carts.json