Skip to main content

​
Base Endpoint

All cart operations use a single endpoint: 
POST /api/v2/cart

​
Request Structure

All cart requests follow this structure: 
{
  "payload": {
    "operation": "get|add|set|delete|clear|selection|bulk_delete",
    "type": "products|giftvouchers|meta",
    "data": { /* operation-specific data */ }
  },
  "localcart": { /* current cart state */ },
  "is_partial_cart": true
}
​
payload.operation
string
required
The cart operation to perform: get, add, set, delete, clear, selection, bulk_delete
​
payload.type
string
Item type: products, giftvouchers, or meta
​
payload.data
object
Operation-specific data (see individual operations below)
​
localcart
object
Current state of the cart for synchronization
​
is_partial_cart
boolean
default:"true"
If false, clears selected products before operation

​
Get Cart

Retrieve the current cart contents.

​
Request

{
  "payload": {
    "operation": "get"
  }
}

​
Query Parameters

​
platform
string
Platform identifier: web or app
​
re_init
integer
Force cart recalculation: 0 or 1

​
Response

{
  "products": {
    "items": [
      {
        "prod_id": 12345,
        "parent_prod_id": 12340,
        "product": "Cotton T-Shirt",
        "quantity": 2,
        "price": 699.0,
        "spl_price": 499.0,
        "exclusive_price": 449.0,
        "stock": 50,
        "size": "M",
        "gender_type": "1",
        "prod_type": 1,
        "url_key": "cotton-t-shirt",
        "categories": [101, 205],
        "images": ["/images/tshirt-1.jpg"],
        "select": true,
        "index_key": "12345"
      }
    ],
    "index": {}
  },
  "giftvouchers": {
    "items": [],
    "index": {}
  },
  "meta": {
    "items": [
      {
        "name": "calculations",
        "main_sub_total": 998.0,
        "sub_total": 998.0,
        "discount": 400.0,
        "shipping_charges": 0.0,
        "gift_wrap_amount": 0.0,
        "used_tss_money": 0.0,
        "used_reward_points": 0.0,
        "used_tss_points": 0.0,
        "total": 598.0
      }
    ],
    "index": {
      "calculations": 0
    }
  },
  "cart_count": {
    "product_count": 2,
    "giftvoucher_count": 0,
    "complementary_count": 0,
    "total_count": 2
  }
}

​
Add Product

Add a product to the cart. If the product already exists, the quantity is incremented.

​
Request

{
  "payload": {
    "operation": "add",
    "type": "products",
    "data": {
      "prod_id": 12345,
      "parent_prod_id": 12340,
      "quantity": 2,
      "gender_type": "1",
      "size": "M",
      "price": 699.0,
      "spl_price": 499.0,
      "url_key": "cotton-t-shirt",
      "product": "Cotton T-Shirt",
      "prod_type": 1,
      "categories": [101, 205],
      "print_name": ""
    }
  },
  "localcart": { /* current cart */ }
}

​
Request Parameters

​
data.prod_id
integer
required
Product ID to add
​
data.quantity
integer
required
Quantity to add (max 10 per product)
​
data.parent_prod_id
integer
Parent product ID if this is a variant
​
data.gender_type
string
Gender type: “0” (unisex), “1” (male), “2” (female)
​
data.size
string
Product size
​
data.price
float
required
Regular price
​
data.spl_price
float
Special price if available
​
data.url_key
string
required
Product URL slug
​
data.product
string
required
Product name
​
data.prod_type
integer
required
Product type (1=simple, 6=bundle)
​
data.categories
array
Array of category IDs
​
data.print_name
string
Custom text for customizable products
​
data.is_mystery_product
integer
Mystery product flag (0 or 1)

​
Bundle Products

For bundle products (prod_type=6), include the options array: 
{
  "payload": {
    "operation": "add",
    "type": "products",
    "data": {
      "prod_id": 50000,
      "quantity": 1,
      "prod_type": 6,
      "options": [
        {
          "option_id": 12345,
          "sku": 12345
        },
        {
          "option_id": 12346,
          "sku": 12346
        }
      ]
    }
  }
}
​
data.options
array
Array of bundle options
​
options[].option_id
integer
required
Option identifier
​
options[].sku
integer
required
Product SKU for this option

​
Validation Rules

  • Maximum quantity per product: 10
  • Mystery products: quantity must be 1, only one per parent product
  • Nestle products cannot be combined with other products
  • Bundle products automatically calculate combo discounts when complete
  • Membership products cannot be added if user is already a member
  • Customizable products require valid print_name and custom product ID

​
Response

Returns the updated cart object (same structure as GET operation).

​
Set Product Quantity

Set a product’s quantity directly (not incremental).

​
Request

{
  "payload": {
    "operation": "set",
    "type": "products",
    "data": {
      "prod_id": 12345,
      "quantity": 3,
      "url_key": "cotton-t-shirt",
      "prod_type": 1
    }
  }
}
​
data.prod_id
integer
required
Product ID to update
​
data.quantity
integer
required
New quantity (max 10)
​
data.url_key
string
required
Product URL slug
​
data.prod_type
integer
required
Product type

​
Response

Returns the updated cart object.

​
Delete Product

Remove a product from the cart.

​
Request

{
  "payload": {
    "operation": "delete",
    "type": "products",
    "data": {
      "prod_id": 12345
    }
  }
}
​
data.prod_id
integer
required
Product ID to remove

​
Special Behavior

  • Deleting a membership product removes associated membership-only products
  • Deleting a combo product resets discount for other combo items
  • If cart becomes empty, associated metadata (like climes ID) is removed

​
Response

Returns the updated cart object.

​
Bulk Delete

Remove multiple products at once.

​
Request

{
  "payload": {
    "operation": "bulk_delete",
    "select": ["12345", "12346", "12347"]
  }
}
​
select
array
required
Array of product IDs (as strings or index_key values) to remove

​
Response

Returns the updated cart object.

​
Clear Cart

Empty the entire cart or only selected items.

​
Request

{
  "payload": {
    "operation": "clear"
  }
}

​
Behavior

  • If selected products exist, only selected items are cleared
  • If no selections, entire cart is cleared
  • All metadata is reset

​
Response

Returns an empty cart object.

​
Selection Management

Mark products as selected or unselected for checkout.

​
Request

{
  "payload": {
    "operation": "selection",
    "select": [
      {
        "prod_id": "12345",
        "select": true
      },
      {
        "prod_id": "12346",
        "select": false
      }
    ]
  }
}
​
select
array
required
Array of selection objects
​
select[].prod_id
string
required
Product ID or index_key
​
select[].select
boolean
required
Selection status

​
Special Behavior

  • Exclusive membership products cannot be unselected
  • When combo products are partially unselected, combo discount is removed
  • When all combo products are selected, discount is automatically applied
  • Response includes selected_calculations metadata with totals for selected items only

​
Response

Returns the cart with updated selection states and separate calculations for selected items.

​
Sync Cart

Sync a local cart with the server after user login. 
POST /api/v2/cart/sync

​
Request

{
  "token": "user_jwt_token",
  "localcart": {
    "products": { /* local cart products */ },
    "giftvouchers": { /* local gift vouchers */ },
    "meta": { /* local metadata */ }
  }
}
​
token
string
required
User JWT token (standard or 2FA token starting with “2f.”)
​
localcart
object
required
Local cart state to sync with server

​
Response

{
  "cart": {
    "products": { /* merged cart */ },
    "giftvouchers": {},
    "meta": {}
  }
}

​
App User Cart

Simplified cart API for mobile apps with authentication. 
POST /api/v2/cart/app
This endpoint requires app authentication via the check_app_auth decorator.

​
Request

{
  "operation": "get|add|set|delete|clear",
  "product_id": 12345,
  "parent_prod_id": 12340,
  "quantity": 2,
  "gender_type": "1"
}
​
operation
string
required
Cart operation: get, add, set, delete, or clear
​
product_id
integer
Product ID (required for add/set/delete)
​
parent_prod_id
integer
Parent product ID for variants
​
quantity
integer
Product quantity (required for add/set)
​
gender_type
string
Gender type: “0”, “1”, or “2”

​
Response

{
  "status": 200,
  "message": "product added",
  "object": {
    "user_cart": {
      "products": [
        {
          "product_id": 12345,
          "product_name": "Cotton T-Shirt",
          "images": ["https://cdn.example.com/image.jpg"],
          "price": 699.0,
          "spl_price": 499.0,
          "exclusive_price": 449.0,
          "size": "M",
          "quantity": 2,
          "gender_type": "1"
        }
      ],
      "cart_total": 898.0
    }
  }
}
​
status
integer
HTTP status code (200, 201, or 400)
​
message
string
Human-readable operation result
​
object.user_cart
object
Simplified cart object with products array and cart_total

​
Get Gift Vouchers

Retrieve available gift voucher options. 
GET /api/v2/cart/giftvoucher

​
Response

[
  {
    "id": 1,
    "voucher_value": 500.0
  },
  {
    "id": 2,
    "voucher_value": 1000.0
  },
  {
    "id": 3,
    "voucher_value": 2000.0
  },
  {
    "id": 4,
    "voucher_value": 5000.0
  }
]
​
id
integer
Gift voucher ID
​
voucher_value
float
Voucher amount in currency

​
Error Responses

​
Common Errors

​
400 Bad Request
Invalid request or validation error
{
  "title": "Bad Request",
  "description": "Per product quantity should be less than or equal to 10."
}

​
Error Messages

  • "Item already removed" - Product no longer in cart
  • "Specified quantity is out of stock" - Insufficient stock
  • "Please refresh cart" - Cart state is stale
  • "You are already a member" - Cannot add membership product
  • "Mystery product quantity should be 1" - Invalid mystery product quantity
  • "Bundle Product Already Added" - Cannot add duplicate bundle
  • "Customizable product not available" - Invalid customization
  • "Minimum order amount should be {amount}" - Order below minimum
  • "Exclusive Membership can't be purchased alone with current cart" - Invalid cart combination

Build docs developers (and LLMs) love

Get started for freeTalk to us