Skip to main content
POST
/
api
/
v2
/
storefront
/
cart
/
add_item
Add an Item to Cart
curl --request POST \
  --url https://demo.spreecommerce.org/api/v2/storefront/cart/add_item \
  --header 'Content-Type: application/vnd.api+json' \
  --header 'X-Spree-Order-Token: <api-key>' \
  --data '
{
  "variant_id": "1",
  "quantity": 5,
  "public_metadata": {
    "first_item_order": true
  },
  "private_metadata": {
    "recommended_by_us": false
  }
}
'
{ "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.

Body

application/vnd.api+json

Additional parameters can be passed in the options hash. Each custom parameter must be registered in config/initializers/spree.rb, eg.

  Spree::PermittedAttributes.line_item_attributes << :foo
​
variant_id
string
​
quantity
integer
​
public_metadata
object

The public metadata for the added item.

​
private_metadata
object

The private metadata for the added item.

​
options
object

Additional custom options. Activate these by adding: Spree::PermittedAttributes.line_item_attributes << :foo in config/initializers/spree.rb

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

​
included
(Line Item · object | Promotion · object | Variant · object | Payment · object | User · object | Shipment · object | Digital Link · object | Product · object)[]