Spree SDK
import { createClient } from '@spree/sdk'
const client = createClient({
baseUrl: 'https://your-store.com',
publishableKey: '<api-key>',
})
const carts = await client.carts.list({
token: '<token>',
})curl --request GET \
--url http://{defaultHost}/api/v3/store/carts \
--header 'Authorization: Bearer <token>' \
--header 'x-spree-api-key: <api-key>'{
"data": [
{
"id": "cart_UkLWZg9DAJ",
"market_id": "mkt_UkLWZg9DAJ",
"channel_id": "ch_UkLWZg9DAJ",
"preferred_stock_location_id": null,
"company_id": null,
"company_name": null,
"po_number_required": false,
"po_document_filename": null,
"po_document_byte_size": null,
"number": "cart_UkLWZg9DAJ",
"token": "ckMf2iQ6r5adLceTPfKVH9BP",
"email": null,
"customer_note": null,
"po_number": null,
"currency": "USD",
"locale": "en",
"total_quantity": 1,
"warnings": [],
"coupon_code": null,
"item_total": "10.00",
"display_item_total": "$10.00",
"discount_total": "0.00",
"display_discount_total": "$0.00",
"tax_total": "0.00",
"display_tax_total": "$0.00",
"included_tax_total": "0.00",
"display_included_tax_total": "$0.00",
"additional_tax_total": "0.00",
"display_additional_tax_total": "$0.00",
"delivery_total": "0.00",
"display_delivery_total": "$0.00",
"fee_total": "0.00",
"display_fee_total": "$0.00",
"gift_card_total": "0.00",
"display_gift_card_total": "$0.00",
"store_credit_total": "0.00",
"display_store_credit_total": "$0.00",
"total": "10.00",
"display_total": "$10.00",
"amount_due": "10.00",
"display_amount_due": "$10.00",
"covered_by_store_credit": false,
"payments": [],
"adjustment_total": "0.00",
"display_adjustment_total": "$0.00",
"current_step": "address",
"completed_steps": [],
"requirements": [
{
"code": "email_required",
"step": "address",
"field": "email",
"message": "Email address is required"
},
{
"code": "ship_address_required",
"step": "address",
"field": "ship_address",
"message": "Shipping address is required"
},
{
"code": "delivery_method_required",
"step": "delivery",
"field": "shipping_method",
"message": "Select a delivery method for all fulfillments"
},
{
"code": "payment_required",
"step": "payment",
"field": "payment",
"message": "Add a payment method"
}
],
"order_minimum": null,
"order_minimum_shortfall": null,
"below_order_minimum": false,
"freight_summary": null,
"shipping_eq_billing_address": false,
"discounts": [],
"fees": [],
"items": [
{
"id": "li_UkLWZg9DAJ",
"variant_id": "variant_UkLWZg9DAJ",
"seller_id": null,
"preorder": false,
"preorder_ships_at": null,
"quantity": 1,
"currency": "USD",
"name": "Product 318715",
"slug": "product-318715",
"options_text": "",
"price": "10.00",
"display_price": "$10.00",
"total": "10.00",
"display_total": "$10.00",
"adjustment_total": "0.00",
"display_adjustment_total": "$0.00",
"additional_tax_total": "0.00",
"display_additional_tax_total": "$0.00",
"included_tax_total": "0.00",
"display_included_tax_total": "$0.00",
"discount_total": "0.00",
"display_discount_total": "$0.00",
"pre_tax_amount": "10.00",
"display_pre_tax_amount": "$10.00",
"discounted_amount": "10.00",
"display_discounted_amount": "$10.00",
"display_compare_at_amount": "$0.00",
"compare_at_amount": null,
"thumbnail_url": null,
"option_values": [],
"digital_links": []
}
],
"fulfillments": [],
"billing_address": null,
"shipping_address": null,
"payment_methods": [],
"gift_card": null,
"market": {
"id": "mkt_UkLWZg9DAJ",
"name": "United States",
"currency": "USD",
"default_locale": "en",
"tax_inclusive": false,
"default": true,
"country_codes": [
"US"
],
"country_isos": [
"US"
],
"supported_locales": [
"en"
]
}
},
{
"id": "cart_gbHJdmfrXB",
"market_id": "mkt_UkLWZg9DAJ",
"channel_id": "ch_UkLWZg9DAJ",
"preferred_stock_location_id": null,
"company_id": null,
"company_name": null,
"po_number_required": false,
"po_document_filename": null,
"po_document_byte_size": null,
"number": "cart_gbHJdmfrXB",
"token": "pvLw1ZWLLQNxh1uvSPUCdSmt",
"email": null,
"customer_note": null,
"po_number": null,
"currency": "USD",
"locale": "en",
"total_quantity": 1,
"warnings": [],
"coupon_code": null,
"item_total": "10.00",
"display_item_total": "$10.00",
"discount_total": "0.00",
"display_discount_total": "$0.00",
"tax_total": "0.00",
"display_tax_total": "$0.00",
"included_tax_total": "0.00",
"display_included_tax_total": "$0.00",
"additional_tax_total": "0.00",
"display_additional_tax_total": "$0.00",
"delivery_total": "0.00",
"display_delivery_total": "$0.00",
"fee_total": "0.00",
"display_fee_total": "$0.00",
"gift_card_total": "0.00",
"display_gift_card_total": "$0.00",
"store_credit_total": "0.00",
"display_store_credit_total": "$0.00",
"total": "10.00",
"display_total": "$10.00",
"amount_due": "10.00",
"display_amount_due": "$10.00",
"covered_by_store_credit": false,
"payments": [],
"adjustment_total": "0.00",
"display_adjustment_total": "$0.00",
"current_step": "address",
"completed_steps": [],
"requirements": [
{
"code": "email_required",
"step": "address",
"field": "email",
"message": "Email address is required"
},
{
"code": "ship_address_required",
"step": "address",
"field": "ship_address",
"message": "Shipping address is required"
},
{
"code": "delivery_method_required",
"step": "delivery",
"field": "shipping_method",
"message": "Select a delivery method for all fulfillments"
},
{
"code": "payment_required",
"step": "payment",
"field": "payment",
"message": "Add a payment method"
}
],
"order_minimum": null,
"order_minimum_shortfall": null,
"below_order_minimum": false,
"freight_summary": null,
"shipping_eq_billing_address": false,
"discounts": [],
"fees": [],
"items": [
{
"id": "li_gbHJdmfrXB",
"variant_id": "variant_gbHJdmfrXB",
"seller_id": null,
"preorder": false,
"preorder_ships_at": null,
"quantity": 1,
"currency": "USD",
"name": "Product 3192171",
"slug": "product-3192171",
"options_text": "",
"price": "10.00",
"display_price": "$10.00",
"total": "10.00",
"display_total": "$10.00",
"adjustment_total": "0.00",
"display_adjustment_total": "$0.00",
"additional_tax_total": "0.00",
"display_additional_tax_total": "$0.00",
"included_tax_total": "0.00",
"display_included_tax_total": "$0.00",
"discount_total": "0.00",
"display_discount_total": "$0.00",
"pre_tax_amount": "10.00",
"display_pre_tax_amount": "$10.00",
"discounted_amount": "10.00",
"display_discounted_amount": "$10.00",
"display_compare_at_amount": "$0.00",
"compare_at_amount": null,
"thumbnail_url": null,
"option_values": [],
"digital_links": []
}
],
"fulfillments": [],
"billing_address": null,
"shipping_address": null,
"payment_methods": [],
"gift_card": null,
"market": {
"id": "mkt_UkLWZg9DAJ",
"name": "United States",
"currency": "USD",
"default_locale": "en",
"tax_inclusive": false,
"default": true,
"country_codes": [
"US"
],
"country_isos": [
"US"
],
"supported_locales": [
"en"
]
}
}
],
"meta": {
"page": 1,
"limit": 25,
"count": 2,
"pages": 1,
"from": 1,
"to": 2,
"in": 2,
"previous": null,
"next": null
}
}{
"error": {
"code": "authentication_required",
"message": "Authentication required"
}
}List active carts
Returns all active (incomplete) carts for the authenticated user.
GET
/
api
/
v3
/
store
/
carts
Spree SDK
import { createClient } from '@spree/sdk'
const client = createClient({
baseUrl: 'https://your-store.com',
publishableKey: '<api-key>',
})
const carts = await client.carts.list({
token: '<token>',
})curl --request GET \
--url http://{defaultHost}/api/v3/store/carts \
--header 'Authorization: Bearer <token>' \
--header 'x-spree-api-key: <api-key>'{
"data": [
{
"id": "cart_UkLWZg9DAJ",
"market_id": "mkt_UkLWZg9DAJ",
"channel_id": "ch_UkLWZg9DAJ",
"preferred_stock_location_id": null,
"company_id": null,
"company_name": null,
"po_number_required": false,
"po_document_filename": null,
"po_document_byte_size": null,
"number": "cart_UkLWZg9DAJ",
"token": "ckMf2iQ6r5adLceTPfKVH9BP",
"email": null,
"customer_note": null,
"po_number": null,
"currency": "USD",
"locale": "en",
"total_quantity": 1,
"warnings": [],
"coupon_code": null,
"item_total": "10.00",
"display_item_total": "$10.00",
"discount_total": "0.00",
"display_discount_total": "$0.00",
"tax_total": "0.00",
"display_tax_total": "$0.00",
"included_tax_total": "0.00",
"display_included_tax_total": "$0.00",
"additional_tax_total": "0.00",
"display_additional_tax_total": "$0.00",
"delivery_total": "0.00",
"display_delivery_total": "$0.00",
"fee_total": "0.00",
"display_fee_total": "$0.00",
"gift_card_total": "0.00",
"display_gift_card_total": "$0.00",
"store_credit_total": "0.00",
"display_store_credit_total": "$0.00",
"total": "10.00",
"display_total": "$10.00",
"amount_due": "10.00",
"display_amount_due": "$10.00",
"covered_by_store_credit": false,
"payments": [],
"adjustment_total": "0.00",
"display_adjustment_total": "$0.00",
"current_step": "address",
"completed_steps": [],
"requirements": [
{
"code": "email_required",
"step": "address",
"field": "email",
"message": "Email address is required"
},
{
"code": "ship_address_required",
"step": "address",
"field": "ship_address",
"message": "Shipping address is required"
},
{
"code": "delivery_method_required",
"step": "delivery",
"field": "shipping_method",
"message": "Select a delivery method for all fulfillments"
},
{
"code": "payment_required",
"step": "payment",
"field": "payment",
"message": "Add a payment method"
}
],
"order_minimum": null,
"order_minimum_shortfall": null,
"below_order_minimum": false,
"freight_summary": null,
"shipping_eq_billing_address": false,
"discounts": [],
"fees": [],
"items": [
{
"id": "li_UkLWZg9DAJ",
"variant_id": "variant_UkLWZg9DAJ",
"seller_id": null,
"preorder": false,
"preorder_ships_at": null,
"quantity": 1,
"currency": "USD",
"name": "Product 318715",
"slug": "product-318715",
"options_text": "",
"price": "10.00",
"display_price": "$10.00",
"total": "10.00",
"display_total": "$10.00",
"adjustment_total": "0.00",
"display_adjustment_total": "$0.00",
"additional_tax_total": "0.00",
"display_additional_tax_total": "$0.00",
"included_tax_total": "0.00",
"display_included_tax_total": "$0.00",
"discount_total": "0.00",
"display_discount_total": "$0.00",
"pre_tax_amount": "10.00",
"display_pre_tax_amount": "$10.00",
"discounted_amount": "10.00",
"display_discounted_amount": "$10.00",
"display_compare_at_amount": "$0.00",
"compare_at_amount": null,
"thumbnail_url": null,
"option_values": [],
"digital_links": []
}
],
"fulfillments": [],
"billing_address": null,
"shipping_address": null,
"payment_methods": [],
"gift_card": null,
"market": {
"id": "mkt_UkLWZg9DAJ",
"name": "United States",
"currency": "USD",
"default_locale": "en",
"tax_inclusive": false,
"default": true,
"country_codes": [
"US"
],
"country_isos": [
"US"
],
"supported_locales": [
"en"
]
}
},
{
"id": "cart_gbHJdmfrXB",
"market_id": "mkt_UkLWZg9DAJ",
"channel_id": "ch_UkLWZg9DAJ",
"preferred_stock_location_id": null,
"company_id": null,
"company_name": null,
"po_number_required": false,
"po_document_filename": null,
"po_document_byte_size": null,
"number": "cart_gbHJdmfrXB",
"token": "pvLw1ZWLLQNxh1uvSPUCdSmt",
"email": null,
"customer_note": null,
"po_number": null,
"currency": "USD",
"locale": "en",
"total_quantity": 1,
"warnings": [],
"coupon_code": null,
"item_total": "10.00",
"display_item_total": "$10.00",
"discount_total": "0.00",
"display_discount_total": "$0.00",
"tax_total": "0.00",
"display_tax_total": "$0.00",
"included_tax_total": "0.00",
"display_included_tax_total": "$0.00",
"additional_tax_total": "0.00",
"display_additional_tax_total": "$0.00",
"delivery_total": "0.00",
"display_delivery_total": "$0.00",
"fee_total": "0.00",
"display_fee_total": "$0.00",
"gift_card_total": "0.00",
"display_gift_card_total": "$0.00",
"store_credit_total": "0.00",
"display_store_credit_total": "$0.00",
"total": "10.00",
"display_total": "$10.00",
"amount_due": "10.00",
"display_amount_due": "$10.00",
"covered_by_store_credit": false,
"payments": [],
"adjustment_total": "0.00",
"display_adjustment_total": "$0.00",
"current_step": "address",
"completed_steps": [],
"requirements": [
{
"code": "email_required",
"step": "address",
"field": "email",
"message": "Email address is required"
},
{
"code": "ship_address_required",
"step": "address",
"field": "ship_address",
"message": "Shipping address is required"
},
{
"code": "delivery_method_required",
"step": "delivery",
"field": "shipping_method",
"message": "Select a delivery method for all fulfillments"
},
{
"code": "payment_required",
"step": "payment",
"field": "payment",
"message": "Add a payment method"
}
],
"order_minimum": null,
"order_minimum_shortfall": null,
"below_order_minimum": false,
"freight_summary": null,
"shipping_eq_billing_address": false,
"discounts": [],
"fees": [],
"items": [
{
"id": "li_gbHJdmfrXB",
"variant_id": "variant_gbHJdmfrXB",
"seller_id": null,
"preorder": false,
"preorder_ships_at": null,
"quantity": 1,
"currency": "USD",
"name": "Product 3192171",
"slug": "product-3192171",
"options_text": "",
"price": "10.00",
"display_price": "$10.00",
"total": "10.00",
"display_total": "$10.00",
"adjustment_total": "0.00",
"display_adjustment_total": "$0.00",
"additional_tax_total": "0.00",
"display_additional_tax_total": "$0.00",
"included_tax_total": "0.00",
"display_included_tax_total": "$0.00",
"discount_total": "0.00",
"display_discount_total": "$0.00",
"pre_tax_amount": "10.00",
"display_pre_tax_amount": "$10.00",
"discounted_amount": "10.00",
"display_discounted_amount": "$10.00",
"display_compare_at_amount": "$0.00",
"compare_at_amount": null,
"thumbnail_url": null,
"option_values": [],
"digital_links": []
}
],
"fulfillments": [],
"billing_address": null,
"shipping_address": null,
"payment_methods": [],
"gift_card": null,
"market": {
"id": "mkt_UkLWZg9DAJ",
"name": "United States",
"currency": "USD",
"default_locale": "en",
"tax_inclusive": false,
"default": true,
"country_codes": [
"US"
],
"country_isos": [
"US"
],
"supported_locales": [
"en"
]
}
}
],
"meta": {
"page": 1,
"limit": 25,
"count": 2,
"pages": 1,
"from": 1,
"to": 2,
"in": 2,
"previous": null,
"next": null
}
}{
"error": {
"code": "authentication_required",
"message": "Authentication required"
}
}Filters
Filter withq[<attribute>_<predicate>]=value, for example q[number_cont]=…. Send a list as q[<attribute>_in][]=a&q[<attribute>_in][]=b. How filters work.
| Attribute | Kind | Predicates |
|---|---|---|
channel_id | Prefixed ID | eq not_eq in not_in null not_null |
completed_at | Date and time | eq not_eq in not_in lt lteq gt gteq null not_null |
created_at | Date and time | eq not_eq in not_in lt lteq gt gteq null not_null |
currency | One of the CurrencyCode codes | eq not_eq in not_in null not_null |
customer_id | Prefixed ID | eq not_eq in not_in null not_null |
delivery_total | Amount | eq not_eq in not_in lt lteq gt gteq null not_null |
fulfillment_status | One of backorder, canceled, partial, unfulfilled, fulfilled, delivered, pending, ready, shipped | eq not_eq in not_in null not_null |
id | Prefixed ID | eq not_eq in not_in null not_null |
item_total | Amount | eq not_eq in not_in lt lteq gt gteq null not_null |
locale | One of the LocaleCode codes | eq not_eq in not_in null not_null |
market_id | Prefixed ID | eq not_eq in not_in null not_null |
number | Text | eq not_eq in not_in cont i_cont not_cont start end null not_null present blank |
order_group_id | Prefixed ID | eq not_eq in not_in null not_null |
payment_status | One of none, authorized, partially_paid, paid, partially_refunded, refunded, overcharged, voided, balance_due, credit_owed, failed, void | eq not_eq in not_in null not_null |
po_number | Text | eq not_eq in not_in cont i_cont not_cont start end null not_null present blank |
seller_id | Prefixed ID | eq not_eq in not_in null not_null |
status | One of draft, placed, canceled | eq not_eq in not_in null not_null |
total | Amount | eq not_eq in not_in lt lteq gt gteq null not_null |
total_quantity | Number | eq not_eq in not_in lt lteq gt gteq null not_null |
updated_at | Date and time | eq not_eq in not_in lt lteq gt gteq null not_null |
channel_id, completed_at, created_at, currency, customer_id, delivery_total, fulfillment_status, id, item_total, locale, market_id, number, order_group_id, payment_status, po_number, seller_id, status, total, total_quantity, updated_at. Prefix a field with - to sort descending.Authorizations
Publishable API key for store access
JWT token for authenticated customers
Query Parameters
Set to true to apply complete.
Set to true to apply incomplete.
Set to true to apply partially_refunded.
Set to true to apply refunded.
Page number (default: 1)
Number of results per page (default: 25, max: 100)
Sort order. Prefix with - for descending. Values: created_at, -created_at, updated_at, -updated_at
Attribute filters, as q[<attribute>_<predicate>]=value. See Filters above for the list.
Comma-separated associations to expand (items, fulfillments, payments, discounts, billing_address, shipping_address, gift_card, payment_methods). Use "none" to skip associations.
Comma-separated list of fields to include (e.g., total,amount_due,item_count). id is always included.
Response
carts listed
Was this page helpful?
⌘I