Orders

erDiagram
    Order ||--o{ LineItem : "has many"
    Order ||--o{ Shipment : "has many"
    Order ||--o{ Payment : "has many"
    Order ||--o{ Adjustment : "has many"
    Order }o--|| Address : "ship_address"
    Order }o--|| Address : "bill_address"
    Order }o--|| User : "belongs to"
    Order }o--|| Store : "belongs to"
    LineItem }o--|| Variant : "belongs to"
    Shipment }o--|| StockLocation : "ships from"
    Payment }o--|| PaymentMethod : "belongs to"

    Order {
        string number
        string state
        string email
        string currency
        decimal total
        string payment_state
        string shipment_state
    }

    LineItem {
        integer quantity
        decimal price
    }

    Shipment {
        string number
        string state
        string tracking
    }

    Payment {
        decimal amount
        string state
    }

// Create a cart
const cart = await client.carts.create()
// cart.token => "abc123" (save this for guest checkout)

// Get existing cart
const cart = await client.carts.get(cartId, { spreeToken: 'xxx' })

// Add an item
const updatedOrder = await client.carts.items.create(cart.id, {
  variant_id: 'var_xxx',
  quantity: 2,
})

// Update quantity
await client.carts.items.update(cart.id, 'li_xxx', {
  quantity: 3,
})

// Remove an item
await client.carts.items.delete(cart.id, 'li_xxx')

# Create a cart
curl -X POST 'https://api.mystore.com/api/v3/store/carts' \
  -H 'Authorization: Bearer pk_xxx'

# Get existing cart
curl 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
  -H 'Authorization: Bearer pk_xxx' \
  -H 'X-Spree-Token: abc123'

# Add an item
curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items' \
  -H 'Authorization: Bearer pk_xxx' \
  -H 'X-Spree-Token: abc123' \
  -H 'Content-Type: application/json' \
  -d '{ "variant_id": "var_xxx", "quantity": 2 }'

# Update quantity
curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items/li_xxx' \
  -H 'Authorization: Bearer pk_xxx' \
  -H 'X-Spree-Token: abc123' \
  -H 'Content-Type: application/json' \
  -d '{ "quantity": 3 }'

# Remove an item
curl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/items/li_xxx' \
  -H 'Authorization: Bearer pk_xxx' \
  -H 'X-Spree-Token: abc123'

// Set addresses
await client.carts.update(cartId, {
  email: '[email protected]',
  ship_address: {
    firstname: 'John', lastname: 'Doe',
    address1: '123 Main St', city: 'Los Angeles',
    country_iso: 'US', state_abbr: 'CA', zipcode: '90001',
    phone: '555-0100',
  },
})

// Get shipments and select a shipping rate
const { data: shipments } = await client.carts.shipments.list(cartId)
await client.carts.shipments.update(cartId, shipments[0].id, {
  selected_shipping_rate_id: 'sr_xxx',
})

// Create a payment session (e.g., Stripe)
const session = await client.carts.paymentSessions.create(cartId, {
  payment_method_id: 'pm_xxx',
})
// session.external_data.client_secret => use with Stripe.js

// Complete the payment session after provider confirmation
await client.carts.paymentSessions.complete(cartId, session.id)

// Complete the order
await client.carts.complete(cartId)

# Set addresses
curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx' \
  -H 'Authorization: Bearer pk_xxx' \
  -H 'X-Spree-Token: abc123' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "ship_address": {
      "firstname": "John", "lastname": "Doe",
      "address1": "123 Main St", "city": "Los Angeles",
      "country_iso": "US", "state_abbr": "CA", "zipcode": "90001",
      "phone": "555-0100"
    }
  }'

# Select a shipping rate
curl -X PATCH 'https://api.mystore.com/api/v3/store/carts/cart_xxx/shipments/shp_xxx' \
  -H 'Authorization: Bearer pk_xxx' \
  -H 'X-Spree-Token: abc123' \
  -H 'Content-Type: application/json' \
  -d '{ "selected_shipping_rate_id": "sr_xxx" }'

# Complete the order
curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/complete' \
  -H 'Authorization: Bearer pk_xxx' \
  -H 'X-Spree-Token: abc123'

// Apply a discount code
await client.carts.discountCodes.apply(cartId, 'SAVE20')

// Remove a discount code
await client.carts.discountCodes.remove(cartId, 'SAVE20')

# Apply a discount code
curl -X POST 'https://api.mystore.com/api/v3/store/carts/cart_xxx/discount_codes' \
  -H 'Authorization: Bearer pk_xxx' \
  -H 'X-Spree-Token: abc123' \
  -H 'Content-Type: application/json' \
  -d '{ "code": "SAVE20" }'

# Remove a discount code
curl -X DELETE 'https://api.mystore.com/api/v3/store/carts/cart_xxx/discount_codes/SAVE20' \
  -H 'Authorization: Bearer pk_xxx' \
  -H 'X-Spree-Token: abc123'

// List past orders
const { data: orders } = await client.customer.orders.list()

// Get a specific order with details
const order = await client.orders.get('or_xxx', {
  expand: ['items', 'shipments', 'payments'],
})

# List past orders
curl 'https://api.mystore.com/api/v3/store/customer/orders' \
  -H 'Authorization: Bearer <jwt_token>'

# Get a specific order
curl 'https://api.mystore.com/api/v3/store/orders/or_xxx?expand=items,shipments,payments' \
  -H 'Authorization: Bearer <jwt_token>'