Guides

Cart & Checkout

The complete shopping cart lifecycle — from adding your first item through checkout and order tracking.

What you'll learn

  • How to create a cart and manage items (add, update, remove)
  • How delivery specification, promo codes, and rewards affect the cart
  • How to validate a cart before checkout
  • How to create an order (checkout) and track its status
  • How to list past orders and integrate with deals (promotions & rewards)
  • API version differences between v4 and v5

Prerequisites

  • A Store UUID (staging: e87437f2-3e35-4738-af5e-6307e368255c)
  • A valid JWT token — see the Authentication guide
  • A product ID from the catalog — see the Quick Start

All cart and order endpoints use the jwt_optional_authenticated pipeline — a token is accepted but not strictly required for cart operations. However, associating a user with the cart (for rewards, loyalty, order history) requires a valid token.

Step 1: Create a Cart

Creating a cart requires at least one item. The initial request also sets the delivery_specification (pickup vs delivery) and inventory_type.

POST /api/v5/carts

The payload wraps an item object inside the cart attributes, along with the delivery and inventory configuration.

cURL 

curl -X POST https://ecom-api.staging.blaze.me/api/v5/carts \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "type": "carts",
      "attributes": {
        "delivery_specification": "pickup",
        "inventory_type": "recreational",
        "item": {
          "product_id": "PRODUCT_UUID",
          "quantity": 1
        }
      }
    }
  }'

JavaScript (fetch) 

const STORE_UUID = "e87437f2-3e35-4738-af5e-6307e368255c";
const BASE_URL = "https://ecom-api.staging.blaze.me";

const response = await fetch(`${BASE_URL}/api/v5/carts`, {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    Accept: "application/vnd.api+json",
    "X-Store": STORE_UUID,
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    data: {
      type: "carts",
      attributes: {
        delivery_specification: "pickup",
        inventory_type: "recreational",
        item: {
          product_id: "PRODUCT_UUID",
          quantity: 1,
        },
      },
    },
  }),
});

const { data } = await response.json();
const cartId = data.id;
console.log(`Cart created: ${cartId}`);

Response 

{
  "data": {
    "id": "cart-uuid",
    "type": "carts",
    "attributes": {
      "uuid": "cart-uuid",
      "delivery_specification": "pickup",
      "inventory_type": "recreational",
      "subtotal": 45.0,
      "total": 49.28,
      "tax": 4.28,
      "promo_codes": [],
      "reward_id": null,
      "items": [
        {
          "id": "item-uuid",
          "product_id": "PRODUCT_UUID",
          "quantity": 1,
          "price": 45.0,
          "name": "Blue Dream"
        }
      ]
    }
  }
}

Key attributes:

  • delivery_specification — "pickup" or "delivery"
  • inventory_type — "recreational" or "medical" (depends on store configuration)
  • conversion_breadcrumb — optional tracking field for analytics (e.g., how the user found the product)

Step 2: Add Items

Once a cart exists, add more items via the cart items endpoint.

POST /api/v5/carts/{cart_uuid}/items

cURL 

curl -X POST https://ecom-api.staging.blaze.me/api/v5/carts/CART_UUID/items \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "type": "cart_items",
      "attributes": {
        "product_id": "ANOTHER_PRODUCT_UUID",
        "quantity": 2
      }
    }
  }'

JavaScript (fetch) 

const response = await fetch(`${BASE_URL}/api/v5/carts/${cartId}/items`, {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    Accept: "application/vnd.api+json",
    "X-Store": STORE_UUID,
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    data: {
      type: "cart_items",
      attributes: {
        product_id: "ANOTHER_PRODUCT_UUID",
        quantity: 2,
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Cart now has ${data.attributes.items.length} items`);

Step 3: Update an Item

Change the quantity or variant of an existing cart item.

PATCH /api/v5/carts/{cart_uuid}/items/{item_uuid} 

curl -X PATCH https://ecom-api.staging.blaze.me/api/v5/carts/CART_UUID/items/ITEM_UUID \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "id": "ITEM_UUID",
      "type": "cart_items",
      "attributes": {
        "product_id": "PRODUCT_UUID",
        "quantity": 3
      }
    }
  }'

The product_id is required even on updates. You can also change the product entirely (e.g., switching to a different variant or weight).

Step 4: Remove an Item

DELETE /api/v5/carts/{cart_uuid}/items/{item_uuid} 

curl -X DELETE https://ecom-api.staging.blaze.me/api/v5/carts/CART_UUID/items/ITEM_UUID \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns the updated cart without the removed item.

Step 5: Set Delivery Specification

The delivery specification determines whether the order is for pickup or delivery, and includes address and scheduling details for delivery orders.

PUT /api/v4/carts/{cart_uuid}/delivery-specification

Note: This endpoint is only available on v4 (and v5). See API Version Notes for details.

curl -X PUT https://ecom-api.staging.blaze.me/api/v4/carts/CART_UUID/delivery-specification \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "id": "CART_UUID",
      "type": "carts",
      "attributes": {
        "delivery_specification": "delivery",
        "address": {
          "address": "456 Oak Avenue",
          "address_line2": "Apt 2B",
          "city": "Los Angeles",
          "state": "CA",
          "zip_code": "90001",
          "country": "US",
          "lat": 34.0522,
          "lng": -118.2437
        }
      }
    }
  }'

Use PATCH as an alternative to PUT — both are supported.

Delivery Address Verification

Before setting a delivery address, verify the store delivers to that location:

curl -X POST https://ecom-api.staging.blaze.me/api/v4/deliveries/stores \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -d '{
    "data": {
      "type": "addresses",
      "attributes": {
        "address": {
          "address": "456 Oak Avenue",
          "city": "Los Angeles",
          "state": "CA",
          "zip_code": "90001",
          "country": "US",
          "lat": 34.0522,
          "lng": -118.2437
        },
        "preferred_inventories": [],
        "mode": "delivery"
      }
    }
  }'

Schedule & Time Slots

Fetch available time slots for pickup or delivery:

curl -X GET "https://ecom-api.staging.blaze.me/api/v1/store/availabilities/pickup" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c"

Replace pickup with delivery to get delivery time slots.

Step 6: Apply Promo Codes

Promo codes are applied via the cart update endpoint. The promo_codes field is an array — you can apply multiple codes.

PUT /api/v5/carts/{cart_uuid} 

curl -X PUT https://ecom-api.staging.blaze.me/api/v5/carts/CART_UUID \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "id": "CART_UUID",
      "type": "carts",
      "attributes": {
        "promo_codes": ["SAVE10", "WELCOME"]
      }
    }
  }'

The response includes updated pricing reflecting any applicable discounts.

Step 7: Apply Rewards

If the user has available loyalty rewards, apply one via reward_id on the cart update.

PUT /api/v5/carts/{cart_uuid} 

curl -X PUT https://ecom-api.staging.blaze.me/api/v5/carts/CART_UUID \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "id": "CART_UUID",
      "type": "carts",
      "attributes": {
        "reward_id": "REWARD_UUID",
        "promo_codes": []
      }
    }
  }'

Tip: Fetch available rewards for the current user with GET /api/v1/users/me/rewards (requires authentication). For store-level rewards visible to all users, use GET /api/v1/store/deals/rewards.

Step 8: Validate the Cart

Before checkout, validate the cart to check for stock availability, pricing changes, delivery eligibility, and other business rules.

POST /api/v5/carts/{cart_uuid}/valid

cURL 

curl -X POST https://ecom-api.staging.blaze.me/api/v5/carts/CART_UUID/valid \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "type": "carts",
      "attributes": {
        "promo_codes": ["SAVE10"],
        "reward_id": null
      }
    }
  }'

JavaScript (fetch) 

const response = await fetch(`${BASE_URL}/api/v5/carts/${cartId}/valid`, {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    Accept: "application/vnd.api+json",
    "X-Store": STORE_UUID,
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    data: {
      type: "carts",
      attributes: {
        promo_codes: ["SAVE10"],
        reward_id: null,
      },
    },
  }),
});

const result = await response.json();

if (response.ok) {
  console.log("Cart is valid — ready for checkout");
} else {
  console.error("Validation errors:", result.errors);
}

What validation checks

  • Stock availability — are all items still in stock at the requested quantities?
  • Price changes — have any product prices changed since the cart was created?
  • Delivery eligibility — is the delivery address within the store's delivery zone?
  • Order minimums — does the cart meet minimum order requirements?
  • Promo code validity — are all applied promo codes still valid?
  • Schedule availability — is the selected time slot still available?

If validation fails, the response includes an errors array with specific failure reasons.

Step 9: Create an Order (Checkout)

🔒 Certified Partners only. Creating orders and processing payments through the API is restricted to certified partners. If you are not certified, use the Checkout Handoff instead — it needs no certification and hands the shopper to Blaze-hosted checkout with the cart intact. To apply for certification, contact your Blaze account manager or ecomsupport@blaze.me. Full list of restricted operations: Access Tiers.

After validation passes, create an order by referencing the cart UUID.

POST /api/v4/orders

cURL 

curl -X POST https://ecom-api.staging.blaze.me/api/v4/orders \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "data": {
      "type": "orders",
      "attributes": {
        "cart_uuid": "CART_UUID"
      }
    }
  }'

JavaScript (fetch) 

const response = await fetch(`${BASE_URL}/api/v4/orders`, {
  method: "POST",
  headers: {
    "Content-Type": "application/vnd.api+json",
    Accept: "application/vnd.api+json",
    "X-Store": STORE_UUID,
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    data: {
      type: "orders",
      attributes: {
        cart_uuid: cartId,
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Order created: ${data.id}`);
console.log(`Status: ${data.attributes.status}`);

You can pass additional attributes alongside cart_uuid for order-specific info (e.g., notes, special instructions).

Response 

{
  "data": {
    "id": "order-uuid",
    "type": "orders",
    "attributes": {
      "uuid": "order-uuid",
      "status": "pending",
      "subtotal": 90.00,
      "total": 98.55,
      "tax": 8.55,
      "delivery_specification": "pickup",
      "items": [ ... ]
    }
  }
}

Step 10: Order Status

Get Order Details

GET /api/v1/orders/{uuid} 

curl -X GET https://ecom-api.staging.blaze.me/api/v1/orders/ORDER_UUID \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN"

Refresh Order Status

If the order status is managed by the POS, force a status refresh from the external system:

PATCH /api/v1/orders/{uuid}/refresh-status 

curl -X PATCH https://ecom-api.staging.blaze.me/api/v1/orders/ORDER_UUID/refresh-status \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Order from Cart

You can also look up an order by its cart UUID:

GET /api/v1/carts/{cart_uuid}/order 

curl -X GET https://ecom-api.staging.blaze.me/api/v1/carts/CART_UUID/order \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN"

Step 11: Order History

List past orders for the authenticated user.

GET /api/v1/orders 

curl -X GET "https://ecom-api.staging.blaze.me/api/v1/orders?limit=10&offset=0" \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c" \
  -H "Authorization: Bearer YOUR_TOKEN"

This endpoint requires jwt_authenticated — a valid token is mandatory.

Supports standard pagination with limit and offset query parameters.

Deals Integration

Promotions and rewards are fetched from the deals endpoints and affect cart pricing when applied.

Promotions

GET /api/v1/store/deals/promotions 

curl -X GET https://ecom-api.staging.blaze.me/api/v1/store/deals/promotions \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c"

No authentication required. Returns active promotions with their conditions and discount details.

Get a Single Promotion 

GET /api/v1/store/deals/promotions/{slug_or_id}

Rewards

GET /api/v1/store/deals/rewards 

curl -X GET https://ecom-api.staging.blaze.me/api/v1/store/deals/rewards \
  -H "Content-Type: application/vnd.api+json" \
  -H "Accept: application/vnd.api+json" \
  -H "X-Store: e87437f2-3e35-4738-af5e-6307e368255c"

No authentication required. Returns available loyalty rewards.

Get a Single Reward 

GET /api/v1/store/deals/rewards/{slug_or_id}

How Deals Affect the Cart

  • Promotions — automatically applied based on cart contents (product, category, quantity rules). No manual action needed from the customer.
  • Promo codes — manually entered codes applied via cart update (promo_codes array).
  • Rewards — loyalty rewards applied via cart update (reward_id field). Requires the user to be authenticated and have earned the reward.

API Version Notes

Cart and order endpoints are available across multiple API versions (v1–v5). The primary differences:

v5 — recommended for carts

  • All cart CRUD operations: create, show, update, add/update/delete items, validate
  • Delivery specification: PUT /api/v5/carts/{cart_uuid}/delivery-specification
  • Full feature set with latest improvements
  • POST /api/v5/orders exists but is not the order-creation endpoint most integrations want — it enqueues an asynchronous submission and returns the cart, not the order. Use POST /api/v4/orders unless you specifically want the async flow.

v4 — recommended for order creation

  • POST /api/v4/orders — creates the order synchronously and returns it (201, an orders resource). This is what both the Blaze web storefront and mobile app use.
  • Same cart operations as v5
  • Introduced the dedicated delivery-specification sub-resource endpoint:
    • PUT /api/v4/carts/{cart_uuid}/delivery-specification
    • PATCH /api/v4/carts/{cart_uuid}/delivery-specification
  • Item deletion (DELETE /api/v4/carts/{cart_uuid}/items/{item_uuid}) first available in v4

v2 / v3

  • Cart create, update, validate, add/update items
  • No item deletion endpoint
  • No dedicated delivery-specification endpoint
  • Order creation available

v1

  • Full cart CRUD including item deletion
  • Order operations: create, show, list, refresh-status
  • Deals endpoints (promotions, rewards)
  • The most complete set of non-cart endpoints (orders list, user rewards, etc.)

Recommendation: Use v5 for carts, v4 for order creation, and v1 for order listing, order detail, deals, and other read endpoints that are only available on v1.

Complete Flow Example

Here's the typical sequence for a full cart-to-order flow:

  1. Browse products → GET /api/v1/products
  2. Create cart with first item → POST /api/v5/carts
  3. Add more items → POST /api/v5/carts/{cart_uuid}/items
  4. Set delivery details → PUT /api/v4/carts/{cart_uuid}/delivery-specification
  5. Apply promo codes → PUT /api/v5/carts/{uuid} (with promo_codes)
  6. Apply reward → PUT /api/v5/carts/{uuid} (with reward_id)
  7. Validate cart → POST /api/v5/carts/{cart_uuid}/valid
  8. Finish the checkout — one of:
  9. Track order → GET /api/v1/orders/{uuid}
  10. Refresh status → PATCH /api/v2/orders/{uuid}/refresh-status

What's Next?

For request/response format details, see the General Concepts guide. For authentication setup, see the Authentication guide.

Previous
Ads & Recommendations
Next
Checkout Handoff