Retrieve a Cart - Spree Commerce documentation

Community

Github

API basics

Tutorials

Quick Checkout with Stripe and Storefront API

Storefront API

Authentication
Account
Account / Address
Account / Credit Cards
Account / Orders
Order Status
Cart
- GET
  Retrieve a Cart
- POST
  Create a Cart
- DEL
  Delete a Cart
Cart / Line Items
Cart / Other
Cart / Coupons
Checkout
Checkout / State
Checkout / Shipments
Checkout / Payments
Checkout / Store Credit
Stripe
Products
Vendors
Stores
Taxons
Countries
CMS Pages
Menus
Wishlists
Wishlists / Wished Items
Digital Downloads

Platform API

Authentication
Addresses
Adjustments
Classifications
CMS Pages
CMS Sections
Countries
Data Feeds
Digital Links
Digital Assets
Line Items
Menu Items
Menus
Option Types
Option Values
Orders
Payment Methods
Payments
Products
Promotion Actions
Promotion Categories
Promotion Rules
Promotions
Roles
Shipments
Shipping Categories
Shipping Methods
States
Stock Items
Stock Locations
Store Credit Categories
Store Credit Types
Store Credits
Tax Categories
Tax Rates
Taxonomies
Taxons
Users
Variants
Vendors
Webhook Events
Webhook Subscribers
Wished Items
Wishlists
Zones

GET

api

storefront

cart

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

{
  "data": {
    "id": "17",
    "type": "cart",
    "attributes": {
      "number": "R233871560",
      "item_total": "0.0",
      "total": "0.0",
      "subtotal_cents": 0,
      "store_credit_total_cents": 0,
      "total_cents": 0,
      "total_minus_store_credits": "0.0",
      "total_minus_store_credits_cents": 0,
      "ship_total": "0.0",
      "ship_total_cents": 0,
      "adjustment_total": "0.0",
      "created_at": "2021-09-28T22:15:07.471Z",
      "updated_at": "2021-09-28T22:15:07.471Z",
      "completed_at": null,
      "included_tax_total": "0.0",
      "additional_tax_total": "0.0",
      "display_additional_tax_total": "$0.00",
      "display_included_tax_total": "$0.00",
      "tax_total": "0.0",
      "tax_total_cents": 0,
      "currency": "USD",
      "state": "cart",
      "token": "zTEpsukRq_yEUcXVCSv0uw1632867307450",
      "email": null,
      "display_item_total": "$0.00",
      "display_ship_total": "$0.00",
      "display_adjustment_total": "$0.00",
      "display_tax_total": "$0.00",
      "promo_total": "0.0",
      "display_promo_total": "$0.00",
      "promo_total_cents": 0,
      "item_count": 0,
      "special_instructions": null,
      "display_total": "$0.00",
      "display_total_minus_store_credits": "$0.00",
      "pre_tax_item_amount": "0.0",
      "display_pre_tax_item_amount": "$0.00",
      "pre_tax_total": "0.0",
      "display_pre_tax_total": "$0.00",
      "shipment_state": null,
      "payment_state": null
    },
    "relationships": {
      "line_items": {
        "data": []
      },
      "variants": {
        "data": []
      },
      "promotions": {
        "data": []
      },
      "payments": {
        "data": []
      },
      "shipments": {
        "data": []
      },
      "user": {
        "data": null
      },
      "billing_address": {
        "data": null
      },
      "shipping_address": {
        "data": null
      }
    }
  }
}

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

application/vnd.api+json

200 Success - Returns the `cart` object.

data

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

data.id

string

required

Example:

"1"

data.type

string

default:cart

required

data.attributes

object

required

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

Example:

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

data.attributes.updated_at

string

Example:

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

data.attributes.completed_at

string | 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 <a href="/developer/core-concepts/orders#the-order-state-machine"> The Order State machine </a> for a full list with description.

Available options:

cart,

address,

delivery,

payment,

confirm,

complete

Example:

"cart"

data.attributes.email

string | 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 <a href="/developer/core-concepts/orders#order-shipment-states-1"> Order Shipments states </a> 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 <a href="/developer/core-concepts/orders#order-payment-states"> Order Payments states </a> for a full list with description.

Available options:

balance_due,

credit_owed,

failed,

paid,

void

data.relationships

object

required

included

object[]

included.id

string

required

Example:

"1"

included.type

string

default:line_item

required

included.attributes

object

required

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.public_metadata

object

The public metadata for the Line Item.

Example:

{ "recommended_by_us": true }

included.relationships

object

required

Was this page helpful?

Suggest edits Raise issue

Create a CartCreates a new cart. **Please be aware**; The `token` value found in the response body is used to authorize all future operations on this cart through the Auth API Key `X-Spree-Order-Token`.

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

{
  "data": {
    "id": "17",
    "type": "cart",
    "attributes": {
      "number": "R233871560",
      "item_total": "0.0",
      "total": "0.0",
      "subtotal_cents": 0,
      "store_credit_total_cents": 0,
      "total_cents": 0,
      "total_minus_store_credits": "0.0",
      "total_minus_store_credits_cents": 0,
      "ship_total": "0.0",
      "ship_total_cents": 0,
      "adjustment_total": "0.0",
      "created_at": "2021-09-28T22:15:07.471Z",
      "updated_at": "2021-09-28T22:15:07.471Z",
      "completed_at": null,
      "included_tax_total": "0.0",
      "additional_tax_total": "0.0",
      "display_additional_tax_total": "$0.00",
      "display_included_tax_total": "$0.00",
      "tax_total": "0.0",
      "tax_total_cents": 0,
      "currency": "USD",
      "state": "cart",
      "token": "zTEpsukRq_yEUcXVCSv0uw1632867307450",
      "email": null,
      "display_item_total": "$0.00",
      "display_ship_total": "$0.00",
      "display_adjustment_total": "$0.00",
      "display_tax_total": "$0.00",
      "promo_total": "0.0",
      "display_promo_total": "$0.00",
      "promo_total_cents": 0,
      "item_count": 0,
      "special_instructions": null,
      "display_total": "$0.00",
      "display_total_minus_store_credits": "$0.00",
      "pre_tax_item_amount": "0.0",
      "display_pre_tax_item_amount": "$0.00",
      "pre_tax_total": "0.0",
      "display_pre_tax_total": "$0.00",
      "shipment_state": null,
      "payment_state": null
    },
    "relationships": {
      "line_items": {
        "data": []
      },
      "variants": {
        "data": []
      },
      "promotions": {
        "data": []
      },
      "payments": {
        "data": []
      },
      "shipments": {
        "data": []
      },
      "user": {
        "data": null
      },
      "billing_address": {
        "data": null
      },
      "shipping_address": {
        "data": null
      }
    }
  }
}