Cart API Reference
The Cart API allows customers to create and manage their shopping carts, add items, configure shipping, and complete checkout.
Create Cart
Create a new shopping cart with optional initial items.
Region ID for pricing and tax calculations
Currency code (e.g., “USD”). Defaults to region’s currency.
Initial items to add to cart
Custom metadata for the line item
Shipping address for the cart
shipping_address.first_name
First name
shipping_address.last_name
Last name
shipping_address.address_1
Street address
shipping_address.postal_code
Postal/ZIP code
shipping_address.country_code
ISO country code (e.g., “us”)
curl -X POST 'https://switchyard.run/store/carts' \
-H 'Content-Type: application/json' \
-H 'x-publishable-api-key: YOUR_KEY' \
-d '{
"region_id": "reg_123",
"items": [
{
"variant_id": "variant_456",
"quantity": 2
}
],
"email": "customer@example.com"
}'
{
"cart": {
"id": "cart_01H...",
"region_id": "reg_123",
"customer_id": null,
"email": "customer@example.com",
"currency_code": "USD",
"items": [
{
"id": "cali_01H...",
"title": "Organic Apples",
"variant_id": "variant_456",
"quantity": 2,
"unit_price": 499,
"subtotal": 998
}
],
"subtotal": 998,
"tax_total": 90,
"total": 1088,
"created_at": "2024-01-15T10:00:00Z"
}
}
Get Cart
Retrieve a cart by its ID.
Comma-separated list of fields to include
Comma-separated list of relations to expand
curl -X GET 'https://switchyard.run/store/carts/cart_01H123' \
-H 'x-publishable-api-key: YOUR_KEY'
{
"cart": {
"id": "cart_01H...",
"region_id": "reg_123",
"items": [
{
"id": "cali_01H...",
"title": "Organic Apples",
"variant_id": "variant_456",
"quantity": 2,
"unit_price": 499,
"subtotal": 998,
"total": 1088
}
],
"shipping_methods": [],
"shipping_address": null,
"payment_collection": null,
"subtotal": 998,
"tax_total": 90,
"shipping_total": 0,
"discount_total": 0,
"total": 1088
}
}
Update Cart
Update a cart’s properties including addresses and email.
Shipping address (see Create Cart for properties)
Billing address (same properties as shipping)
curl -X POST 'https://switchyard.run/store/carts/cart_01H123' \
-H 'Content-Type: application/json' \
-H 'x-publishable-api-key: YOUR_KEY' \
-d '{
"email": "newemail@example.com",
"shipping_address": {
"first_name": "Jane",
"last_name": "Doe",
"address_1": "456 Oak Ave",
"city": "Los Angeles",
"postal_code": "90001",
"country_code": "us"
}
}'
Add Line Item
Add a product variant to the cart.
POST /store/carts/:id/line-items
Product variant ID to add
Custom metadata for the line item
curl -X POST 'https://switchyard.run/store/carts/cart_01H123/line-items' \
-H 'Content-Type: application/json' \
-H 'x-publishable-api-key: YOUR_KEY' \
-d '{
"variant_id": "variant_789",
"quantity": 1,
"metadata": {
"gift_message": "Happy Birthday!"
}
}'
{
"cart": {
"id": "cart_01H...",
"items": [
{
"id": "cali_01H...",
"variant_id": "variant_789",
"quantity": 1,
"unit_price": 1299,
"subtotal": 1299,
"metadata": {
"gift_message": "Happy Birthday!"
}
}
],
"total": 1416
}
}
If the variant already exists in the cart, the quantity is updated instead of creating a duplicate line item.
Update Line Item
Update a line item’s quantity or metadata.
POST /store/carts/:id/line-items/:line_id
curl -X POST 'https://switchyard.run/store/carts/cart_01H123/line-items/cali_01H456' \
-H 'Content-Type: application/json' \
-H 'x-publishable-api-key: YOUR_KEY' \
-d '{
"quantity": 3
}'
Delete Line Item
Remove a line item from the cart.
DELETE /store/carts/:id/line-items/:line_id
The line item ID to remove
curl -X DELETE 'https://switchyard.run/store/carts/cart_01H123/line-items/cali_01H456' \
-H 'x-publishable-api-key: YOUR_KEY'
{
"id": "cali_01H456",
"object": "line_item",
"deleted": true,
"parent": {
"id": "cart_01H123",
"items": []
}
}
Add Shipping Method
Add a shipping method to the cart.
POST /store/carts/:id/shipping-methods
curl -X POST 'https://switchyard.run/store/carts/cart_01H123/shipping-methods' \
-H 'Content-Type: application/json' \
-H 'x-publishable-api-key: YOUR_KEY' \
-d '{
"option_id": "so_standard_shipping"
}'
{
"cart": {
"id": "cart_01H...",
"shipping_methods": [
{
"id": "casm_01H...",
"shipping_option_id": "so_standard_shipping",
"name": "Standard Shipping",
"amount": 599,
"subtotal": 599,
"tax_total": 54,
"total": 653
}
],
"shipping_total": 653,
"total": 1741
}
}
Complete Cart
Complete the cart and create an order. The cart must have a valid payment session, shipping method, and shipping address.
POST /store/carts/:id/complete
curl -X POST 'https://switchyard.run/store/carts/cart_01H123/complete' \
-H 'x-publishable-api-key: YOUR_KEY'
{
"type": "order",
"order": {
"id": "order_01H...",
"status": "pending",
"items": [
{
"id": "ordli_01H...",
"title": "Organic Apples",
"quantity": 2
}
],
"shipping_methods": [...],
"total": 1741,
"created_at": "2024-01-15T10:30:00Z"
}
}
Once completed, a cart cannot be modified. Attempting to update a completed cart will return an error.
Response Objects
Cart Object
Unique identifier with cart prefix
Associated customer ID (null for guests)
Currency code (e.g., “USD”)
Selected shipping methods
Total before tax and shipping (in cents)
Shipping cost with tax (in cents)
Total discounts (in cents)
Line Item Object
Unique identifier with cali prefix
Price per unit (in cents)
Line total before tax (in cents)
Line total with tax (in cents)
Error Codes
| Code | HTTP Status | Description |
|---|
cart_not_found | 404 | Cart with the given ID doesn’t exist |
cart_completed | 400 | Cart has already been completed |
insufficient_inventory | 409 | Not enough stock for requested quantity |
invalid_shipping_address | 400 | Shipping address is missing or invalid |
payment_required | 400 | Payment must be authorized before completing |
payment_requires_action | 400 | Additional payment action needed |
region_not_found | 404 | Invalid region ID |
variant_not_found | 404 | Invalid variant ID |
Webhooks
The cart module emits these events that you can subscribe to:
| Event | Description |
|---|
cart.created | A new cart was created |
cart.updated | Cart was modified (items, addresses, etc.) |
order.placed | Cart was completed and order created |
