Retrieve a Cart

Retrieve a Cart

curl --request GET \
  --url https://demo.spreecommerce.org/api/v2/storefront/cart \
  --header 'X-Spree-Order-Token: <api-key>'

{
  "data": {
    "id": "1",
    "type": "cart",
    "attributes": {
      "number": "R123456789",
      "token": "eL0nVxe1Aum-Qr9-UkryPA1633360128076",
      "item_total": "19.99",
      "subtotal_cents": 1999,
      "store_credit_total_cents": 0,
      "total": "29.99",
      "total_cents": 2999,
      "total_minus_store_credits": "29.99",
      "total_minus_store_credits_cents": 2999,
      "ship_total": "5.0",
      "ship_total_cents": 500,
      "adjustment_total": "10.0",
      "created_at": "2020-02-16T07:14:54.617Z",
      "updated_at": "2020-02-16T07:14:54.617Z",
      "completed_at": "2023-11-07T05:31:56Z",
      "included_tax_total": "5.00",
      "additional_tax_total": "5.0",
      "display_additional_tax_total": "$5.00",
      "tax_total": "10.0",
      "tax_total_cents": 1000,
      "currency": "USD",
      "state": "cart",
      "email": "[email protected]",
      "display_item_total": "$19.99",
      "display_ship_total": "$19.99",
      "display_adjustment_total": "$10.00",
      "display_included_tax_total": "$5.00",
      "promo_total": "-10.0",
      "promo_total_cents": -1000,
      "display_promo_total": "-$10.00",
      "item_count": 2,
      "special_instructions": "Please wrap it as a gift",
      "display_total": "$29.99",
      "display_total_minus_store_credits": "$29.99",
      "pre_tax_item_amount": "17.00",
      "display_pre_tax_item_amount": "$17.00",
      "pre_tax_total": "20.00",
      "display_tax_total": "$10.00",
      "display_pre_tax_total": "$20.00",
      "shipment_state": "pending",
      "payment_state": "balance_due"
    },
    "relationships": {
      "line_items": {
        "data": [
          {
            "id": "<string>",
            "type": "<string>"
          }
        ]
      },
      "variants": {
        "data": [
          {
            "id": "<string>",
            "type": "<string>"
          }
        ]
      },
      "promotions": {
        "data": [
          {
            "id": "<string>",
            "type": "<string>"
          }
        ]
      },
      "payments": {
        "data": [
          {
            "id": "<string>",
            "type": "<string>"
          }
        ]
      },
      "shipments": {
        "data": [
          {
            "id": "<string>",
            "type": "<string>"
          }
        ]
      },
      "user": {
        "data": {
          "id": "<string>",
          "type": "<string>"
        }
      },
      "billing_address": {
        "data": {
          "id": "<string>",
          "type": "<string>"
        }
      },
      "shipping_address": {
        "data": {
          "id": "<string>",
          "type": "<string>"
        }
      }
    }
  },
  "included": [
    {
      "id": "1",
      "type": "line_item",
      "attributes": {
        "name": "Sample product",
        "quantity": 1,
        "slug": "sample-product",
        "options_text": "Size: small, Color: red",
        "price": "125.0",
        "currency": "USD",
        "display_price": "$125.00",
        "total": "250.0",
        "display_total": "$250.00",
        "adjustment_total": "10.0",
        "display_adjustment_total": "$10.00",
        "additional_tax_total": "5.0",
        "display_additional_tax_total": "$5.00",
        "discounted_amount": "125.0",
        "display_discounted_amount": "$125.00",
        "pre_tax_amount": "125.0",
        "display_pre_tax_amount": "$125.00",
        "promo_total": "-5.0",
        "display_promo_total": "<string>",
        "included_tax_total": "0.0",
        "display_inluded_tax_total": "$0.00",
        "compare_at_amount": "290.99",
        "display_compare_at_amount": "$290.99",
        "public_metadata": {
          "recommended_by_us": true
        }
      },
      "relationships": {
        "variant": {
          "data": {
            "id": "<string>",
            "type": "<string>"
          }
        },
        "digital_links": {
          "data": [
            {
              "id": "<string>",
              "type": "<string>"
            }
          ]
        }
      }
    }
  ]
}

GET

api

storefront

cart

Retrieve a Cart

curl --request GET \
  --url https://demo.spreecommerce.org/api/v2/storefront/cart \
  --header 'X-Spree-Order-Token: <api-key>'

{
  "data": {
    "id": "1",
    "type": "cart",
    "attributes": {
      "number": "R123456789",
      "token": "eL0nVxe1Aum-Qr9-UkryPA1633360128076",
      "item_total": "19.99",
      "subtotal_cents": 1999,
      "store_credit_total_cents": 0,
      "total": "29.99",
      "total_cents": 2999,
      "total_minus_store_credits": "29.99",
      "total_minus_store_credits_cents": 2999,
      "ship_total": "5.0",
      "ship_total_cents": 500,
      "adjustment_total": "10.0",
      "created_at": "2020-02-16T07:14:54.617Z",
      "updated_at": "2020-02-16T07:14:54.617Z",
      "completed_at": "2023-11-07T05:31:56Z",
      "included_tax_total": "5.00",
      "additional_tax_total": "5.0",
      "display_additional_tax_total": "$5.00",
      "tax_total": "10.0",
      "tax_total_cents": 1000,
      "currency": "USD",
      "state": "cart",
      "email": "[email protected]",
      "display_item_total": "$19.99",
      "display_ship_total": "$19.99",
      "display_adjustment_total": "$10.00",
      "display_included_tax_total": "$5.00",
      "promo_total": "-10.0",
      "promo_total_cents": -1000,
      "display_promo_total": "-$10.00",
      "item_count": 2,
      "special_instructions": "Please wrap it as a gift",
      "display_total": "$29.99",
      "display_total_minus_store_credits": "$29.99",
      "pre_tax_item_amount": "17.00",
      "display_pre_tax_item_amount": "$17.00",
      "pre_tax_total": "20.00",
      "display_tax_total": "$10.00",
      "display_pre_tax_total": "$20.00",
      "shipment_state": "pending",
      "payment_state": "balance_due"
    },
    "relationships": {
      "line_items": {
        "data": [
          {
            "id": "<string>",
            "type": "<string>"
          }
        ]
      },
      "variants": {
        "data": [
          {
            "id": "<string>",
            "type": "<string>"
          }
        ]
      },
      "promotions": {
        "data": [
          {
            "id": "<string>",
            "type": "<string>"
          }
        ]
      },
      "payments": {
        "data": [
          {
            "id": "<string>",
            "type": "<string>"
          }
        ]
      },
      "shipments": {
        "data": [
          {
            "id": "<string>",
            "type": "<string>"
          }
        ]
      },
      "user": {
        "data": {
          "id": "<string>",
          "type": "<string>"
        }
      },
      "billing_address": {
        "data": {
          "id": "<string>",
          "type": "<string>"
        }
      },
      "shipping_address": {
        "data": {
          "id": "<string>",
          "type": "<string>"
        }
      }
    }
  },
  "included": [
    {
      "id": "1",
      "type": "line_item",
      "attributes": {
        "name": "Sample product",
        "quantity": 1,
        "slug": "sample-product",
        "options_text": "Size: small, Color: red",
        "price": "125.0",
        "currency": "USD",
        "display_price": "$125.00",
        "total": "250.0",
        "display_total": "$250.00",
        "adjustment_total": "10.0",
        "display_adjustment_total": "$10.00",
        "additional_tax_total": "5.0",
        "display_additional_tax_total": "$5.00",
        "discounted_amount": "125.0",
        "display_discounted_amount": "$125.00",
        "pre_tax_amount": "125.0",
        "display_pre_tax_amount": "$125.00",
        "promo_total": "-5.0",
        "display_promo_total": "<string>",
        "included_tax_total": "0.0",
        "display_inluded_tax_total": "$0.00",
        "compare_at_amount": "290.99",
        "display_compare_at_amount": "$290.99",
        "public_metadata": {
          "recommended_by_us": true
        }
      },
      "relationships": {
        "variant": {
          "data": {
            "id": "<string>",
            "type": "<string>"
          }
        },
        "digital_links": {
          "data": [
            {
              "id": "<string>",
              "type": "<string>"
            }
          ]
        }
      }
    }
  ]
}

Authorizations

X-Spree-Order-Token

string

header

required

Order token to authorize Cart and Checkout requests.

How to obtain X-Spree-Order-Token

Query Parameters

include

string

Specify the related resources you would like to receive in the response body. More Information.

fields[cart]

string

Specify the fields you would like returned in the response body. More information.

currency

string

Must be specified when is different than current store default currency.

Response

200 Success - Returns the cart object.

data

Cart · object

required

The Cart provides a central place to collect information about an order, including line items, adjustments, payments, addresses, and shipments. Read more in Spree docs

Show child attributes

data.id

string

required

Example:

"1"

data.type

string

default:cart

required

data.attributes

object

required

Show child attributes

data.attributes.number

string

Used as the {order_number} value in the URI to identify a completed order.

Example:

"R123456789"

data.attributes.token

string

Used for authorizing actions through the X-Spree-Order-Token API Key.

Example:

"eL0nVxe1Aum-Qr9-UkryPA1633360128076"

data.attributes.item_total

string

Example:

"19.99"

data.attributes.subtotal_cents

integer

Example:

1999

data.attributes.store_credit_total_cents

integer

Example:

0

data.attributes.total

string

Example:

"29.99"

data.attributes.total_cents

integer

Example:

2999

data.attributes.total_minus_store_credits

string

Example:

"29.99"

data.attributes.total_minus_store_credits_cents

integer

Example:

2999

data.attributes.ship_total

string

Example:

"5.0"

data.attributes.ship_total_cents

integer

Example:

500

data.attributes.adjustment_total

string

Example:

"10.0"

data.attributes.created_at

string<date-time>

Example:

"2020-02-16T07:14:54.617Z"

data.attributes.updated_at

string<date-time>

Example:

"2020-02-16T07:14:54.617Z"

data.attributes.completed_at

string<date-time> | null

data.attributes.included_tax_total

string

Example:

"5.00"

data.attributes.additional_tax_total

string

Example:

"5.0"

data.attributes.display_additional_tax_total

string

Example:

"$5.00"

data.attributes.tax_total

string

Example:

"10.0"

data.attributes.tax_total_cents

integer

Example:

1000

data.attributes.currency

string

Example:

"USD"

data.attributes.state

enum<string>

State of the Cart in the Checkout flow. Please see The Order State machine for a full list with description.

Available options:

cart,

address,

delivery,

payment,

confirm,

complete

Example:

"cart"

data.attributes.email

string<email> | null

Example:

"[email protected]"

data.attributes.display_item_total

string

Example:

"$19.99"

data.attributes.display_ship_total

string

Example:

"$19.99"

data.attributes.display_adjustment_total

string

Example:

"$10.00"

data.attributes.display_included_tax_total

string

Example:

"$5.00"

Example:

"-10.0"

Example:

-1000

Example:

"-$10.00"

data.attributes.item_count

number

Total quantity number of all items added to the Cart

Required range: x >= 0

Example:

2

data.attributes.special_instructions

string | null

Message added by the Customer

Example:

"Please wrap it as a gift"

data.attributes.display_total

string

Example:

"$29.99"

data.attributes.display_total_minus_store_credits

string

Example:

"$29.99"

data.attributes.pre_tax_item_amount

string

Example:

"17.00"

data.attributes.display_pre_tax_item_amount

string

Example:

"$17.00"

data.attributes.pre_tax_total

string

Example:

"20.00"

data.attributes.display_tax_total

string

Example:

"$10.00"

data.attributes.display_pre_tax_total

string

Example:

"$20.00"

data.attributes.shipment_state

enum<string> | null

Overall state of the Shipments. Please see Order Shipments states for a full list with description.

Available options:

pending,

backorder,

canceled,

partial,

ready,

shipped,

data.attributes.payment_state

enum<string> | null

Overall state of the Payments. Please see Order Payments states for a full list with description.

Available options:

balance_due,

credit_owed,

failed,

paid,

void,

data.relationships

object

required

Show child attributes

data.relationships.line_items

object

Show child attributes

data.relationships.line_items.data

(object | null)[]

Show child attributes

data.relationships.line_items.data.id

string

required

data.relationships.line_items.data.type

string

required

data.relationships.variants

object

Show child attributes

data.relationships.variants.data

(object | null)[]

Show child attributes

data.relationships.variants.data.id

string

required

data.relationships.variants.data.type

string

required

data.relationships.promotions

object

Show child attributes

data.relationships.promotions.data

(object | null)[]

Show child attributes

data.relationships.promotions.data.id

string

required

data.relationships.promotions.data.type

string

required

data.relationships.payments

object

Show child attributes

data.relationships.payments.data

(object | null)[]

Show child attributes

data.relationships.payments.data.id

string

required

data.relationships.payments.data.type

string

required

data.relationships.shipments

object

Show child attributes

data.relationships.shipments.data

(object | null)[]

Show child attributes

data.relationships.shipments.data.id

string

required

data.relationships.shipments.data.type

string

required

data.relationships.user

object

Show child attributes

data.relationships.user.data

object

Show child attributes

data.relationships.user.data.id

string

required

data.relationships.user.data.type

string

required

data.relationships.billing_address

object

Show child attributes

data.relationships.billing_address.data

object

Show child attributes

data.relationships.billing_address.data.id

string

required

data.relationships.billing_address.data.type

string

required

data.relationships.shipping_address

object

Show child attributes

data.relationships.shipping_address.data

object

Show child attributes

data.relationships.shipping_address.data.id

string

required

data.relationships.shipping_address.data.type

string

required

included

Show child attributes

included.id

string

required

Example:

"1"

included.type

string

default:line_item

required

included.attributes

object

required

Show child attributes

included.attributes.name

string

Example:

"Sample product"

included.attributes.quantity

integer

Example:

1

included.attributes.slug

string

Example:

"sample-product"

included.attributes.options_text

string

Example:

"Size: small, Color: red"

included.attributes.price

string

Price of Product per quantity

Example:

"125.0"

included.attributes.currency

string

Example:

"USD"

included.attributes.display_price

string

Price of Product per quantity

Example:

"$125.00"

included.attributes.total

string

Total price of Line Item including adjastments, promotions and taxes

Example:

"250.0"

included.attributes.display_total

string

Total price of Line Item including adjastments, promotions and taxes

Example:

"$250.00"

included.attributes.adjustment_total

string

TBD

Example:

"10.0"

included.attributes.display_adjustment_total

string

TBD

Example:

"$10.00"

included.attributes.additional_tax_total

string

Example:

"5.0"

included.attributes.display_additional_tax_total

string

Example:

"$5.00"

included.attributes.discounted_amount

string

Example:

"125.0"

included.attributes.display_discounted_amount

string

Example:

"$125.00"

included.attributes.pre_tax_amount

string

Example:

"125.0"

included.attributes.display_pre_tax_amount

string

Example:

"$125.00"

Example:

"-5.0"

included.attributes.included_tax_total

string

Taxes included in the price, eg. VAT

Example:

"0.0"

included.attributes.display_inluded_tax_total

string

Example:

"$0.00"

included.attributes.compare_at_amount

string

Compare at price of the Line Item

Example:

"290.99"

included.attributes.display_compare_at_amount

string

Display compare at price of the Line Item

Example:

"$290.99"

included.attributes.public_metadata

object

The public metadata for the Line Item.

Example:

{ "recommended_by_us": true }

included.relationships

object

required

Show child attributes

included.relationships.variant

object

Show child attributes

included.relationships.variant.data

object

Show child attributes

included.relationships.variant.data.id

string

required

included.relationships.variant.data.type

string

required

included.relationships.digital_links

object

Show child attributes

included.relationships.digital_links.data

(object | null)[]

Show child attributes

included.relationships.digital_links.data.id

string

required

included.relationships.digital_links.data.type

string

required

Retrieve an Order Status

Create a Cart

⌘I

API basics

Tutorials

Storefront API

Platform API

Authorizations

Query Parameters

Response