Themes built on the Twig templating engine are now deprecated and require migration to Vitrin to ensure continued support and compatibility with Zid.

Add Cart Item

Developing

POST

https://api.zid.sa//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

Example

{
    "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"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api.zid.sa//cart/items' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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"
}'

Responses

🟢201Success

application/json

Body

Example

{
    "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
}

🟠422Validation Error

Modified at 2025-12-29 06:52:42

Duplicate Cart

Empty Cart