Add Cart Item

POST

{store_url}/api/v1//cart/items

Adds a new item to the current shopping cart.

This endpoint supports:

Standard products

Custom fields (e.g., text inputs, add-ons with pricing)

Selection groups / sub-items (e.g., bundles, modifiers)

Shared cart flows via share_token

Request

Body Params application/jsonRequired

Examples

Responses

🟢201Success

application/json

Bodyapplication/json

🟠422Validation Error

🟠401Unauthorized

🔴500Internal Server error

Request Example

Shell

JavaScript

Java

Swift

curl --location --globoff '{store_url}/api/v1//cart/items' \
--header 'Content-Type: application/json' \
--data '{
    "product_id": "prod_123",
    "quantity": 2,
    "custom_fields": [
        {
            "group_id": "cf_group_1",
            "price_settings": {
                "price": "10",
                "currency": "SAR"
            },
            "type": "TEXT",
            "value": "Happy Birthday"
        }
    ],
    "sub_items": [
        {
            "id": "item_456",
            "quantity": 1,
            "selection_group_id": "sg_001"
        }
    ],
    "share_token": "share_tok_abc"
}'

Response Example

201 - Example 1

{
    "item": {
        "id": 10,
        "product_id": "prod_123",
        "name": "Custom Mug",
        "quantity": 2,
        "price": 50,
        "price_string": "50 ر.س",
        "custom_fields": [
            {
                "name": "string",
                "label": "string",
                "type": "string",
                "value": "string",
                "formatted_value": "string"
            }
        ]
    },
    "cart_items_quantity": 3
}

Modified at 2026-02-17 07:25:10

Duplicate Cart

Empty Cart