> ## Documentation Index
> Fetch the complete documentation index at: https://docs.salesive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Add item to cart

> Add a product, variant, food, or service item with optional add-ons to the authenticated shopper's cart.

## Request

```http theme={null}
POST /cart
Authorization: Bearer {{token}}
x-shop-id: {{shopId}}
Content-Type: application/json

{
  "productId": "692cd420b07303c9be5eafd7",
  "quantity": 2
}
```

## Headers

| Header          | Type   | Description                                   |
| --------------- | ------ | --------------------------------------------- |
| `Authorization` | string | Provide the customer token as `Bearer <jwt>`. |
| `x-shop-id`     | string | Identify the shop that owns the cart.         |
| `Content-Type`  | string | Always set to `application/json`.             |

## Body parameters

| Field            | Type    | Required | Description                                                                      |
| ---------------- | ------- | -------- | -------------------------------------------------------------------------------- |
| `productId`      | string  | No       | Product identifier to add. Provide one of `productId`, `foodId`, or `serviceId`. |
| `foodId`         | string  | No       | Food item identifier (restaurant stores).                                        |
| `serviceId`      | string  | No       | Service identifier (business stores).                                            |
| `variantId`      | string  | No       | Variant identifier. Include it to add a specific product variant.                |
| `quantity`       | integer | No       | Quantity to add. Defaults to `1`.                                                |
| `selectedAddons` | array   | No       | Array of add-on objects `{addonId, quantity}` for food **or** service items.     |

<Note>
  A storefront's catalog type is determined by the shop type: `product` for ecommerce, `food` for restaurant, and `service` for business stores. Add the matching identifier (`productId`, `foodId`, or `serviceId`). Services behave like foods — they have no variants but can carry add-ons.
</Note>

## Food request example

```http theme={null}
POST /cart
Authorization: Bearer {{token}}
x-shop-id: {{shopId}}
Content-Type: application/json

{
  "foodId": "68e5bb463a1fc56a8ac150c0",
  "quantity": 1,
  "selectedAddons": [
    {
      "addonId": "68e5bb463a1fc56a8ac150d1",
      "quantity": 2
    }
  ]
}
```

## Service request example

```http theme={null}
POST /cart
Authorization: Bearer {{token}}
x-shop-id: {{shopId}}
Content-Type: application/json

{
  "serviceId": "6a2f8a7ba6656ba8cddfc1f5",
  "quantity": 1,
  "selectedAddons": [
    {
      "addonId": "6a2f8a7ba6656ba8cddfc201",
      "quantity": 1
    }
  ]
}
```

A service cart item is returned with `itemType: "service"` and a populated `service` object (plus a `serviceId` convenience field), mirroring the food shape:

```json theme={null}
{
    "itemType": "service",
    "service": {
        "_id": "6a2f8a7ba6656ba8cddfc1f5",
        "name": "Home Cleaning"
    },
    "serviceId": "6a2f8a7ba6656ba8cddfc1f5",
    "name": "Home Cleaning",
    "image": "https://cdn.salesive.com/services/cleaning.webp",
    "price": 20000,
    "quantity": 1,
    "selectedAddons": []
}
```

## Successful response

```json theme={null}
{
    "status": 200,
    "success": true,
    "message": "Item added to cart",
    "data": {
        "_id": "693606ada7a8f7dc8ae32d80",
        "items": [
            {
                "itemType": "food",
                "food": {
                    "_id": "68e5bb463a1fc56a8ac150c0",
                    "name": "Margherita Pizza"
                },
                "foodId": "68e5bb463a1fc56a8ac150c0",
                "name": "Margherita Pizza",
                "image": "https://cdn.salesive.com/foods/margherita.webp",
                "price": 7500,
                "quantity": 1,
                "selectedAddons": [
                    {
                        "addonId": "68e5bb463a1fc56a8ac150d1",
                        "name": "Extra Cheese",
                        "description": "A richer mozzarella finish baked on top.",
                        "price": 1500,
                        "quantity": 2
                    }
                ],
                "_id": "6937b6e9e455c711f1fc9064",
                "id": "6937b6e9e455c711f1fc9064"
            }
        ],
        "totalPrice": 10500,
        "id": "693606ada7a8f7dc8ae32d80"
    }
}
```

## Error response

```json theme={null}
{
    "status": 404,
    "success": false,
    "message": "Product not found",
    "data": null
}
```


## OpenAPI

````yaml POST /cart
openapi: 3.1.0
info:
  title: Salesive Store API
  description: >-
    REST interface for querying products, categories, and merchandising banners
    exposed by Salesive storefronts.
  version: 1.0.0
servers:
  - description: Production
    url: https://store.salesive.com/api/v1
security:
  - BearerAuth: []
    ShopIdHeader: []
paths:
  /cart:
    post:
      summary: Add item to cart
      description: >-
        Add a base product, variant, or food item with optional add-ons to the
        shopper's cart.
      parameters:
        - $ref: '#/components/parameters/XShopIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCartItemRequest'
      responses:
        '200':
          description: Cart updated with the new item.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartResponse'
        '404':
          description: Product or variant not found.
components:
  parameters:
    XShopIdHeader:
      name: x-shop-id
      in: header
      description: >-
        Optional identifier that scopes responses to a specific storefront when
        the referer cannot be inferred.
      required: false
      schema:
        type: string
  schemas:
    AddCartItemRequest:
      type: object
      description: >-
        Add a product/variant line item, a food line item, or a service line
        item, with optional add-ons. Use the identifier that matches the
        storefront catalog type: productId (ecommerce), foodId (restaurant), or
        serviceId (business).
      properties:
        productId:
          type: string
          description: Identifier of the product to add to the cart (ecommerce stores).
        foodId:
          type: string
          description: Identifier of the food item to add to the cart (restaurant stores).
        serviceId:
          type: string
          description: Identifier of the service to add to the cart (business stores).
        variantId:
          type: string
          description: Optional identifier of the product variant to add.
        quantity:
          type: integer
          minimum: 1
          default: 1
          description: Quantity of the product, food, or service to add. Defaults to 1.
        selectedAddons:
          type: array
          items:
            $ref: '#/components/schemas/AddonSelectionRequest'
          description: Optional add-on selections for food or service items.
      anyOf:
        - required:
            - productId
        - required:
            - foodId
        - required:
            - serviceId
    CartResponse:
      type: object
      required:
        - status
        - success
        - message
        - data
      properties:
        status:
          type: integer
          description: HTTP status code returned by the API.
        success:
          type: boolean
          description: Indicates whether the request succeeded.
        message:
          type: string
          description: Human-readable response message.
        data:
          $ref: '#/components/schemas/Cart'
    AddonSelectionRequest:
      type: object
      required:
        - addonId
      properties:
        addonId:
          type: string
        quantity:
          type: integer
          minimum: 1
          default: 1
    Cart:
      type: object
      required:
        - _id
        - items
        - totalPrice
      properties:
        _id:
          type: string
          description: Cart identifier.
        user:
          type: string
          description: Identifier of the shopper who owns the cart.
        shop:
          type: string
          description: Identifier of the shop associated with the cart.
        items:
          type: array
          items:
            $ref: '#/components/schemas/CartItem'
        totalPrice:
          type: number
          description: Total price of all items in the cart.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the cart was created.
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the cart was last updated.
    CartItem:
      type: object
      required:
        - itemType
        - name
        - image
        - price
        - quantity
      properties:
        _id:
          type: string
        itemType:
          type: string
          enum:
            - product
            - food
            - service
        product:
          type: object
          description: Product or variant metadata for the cart item.
          properties:
            _id:
              type: string
            id:
              type: string
            name:
              type: string
            images:
              type: array
              items:
                type: string
                format: uri
            price:
              type: number
            promoPrice:
              type: number
              nullable: true
            sku:
              type: string
            parentProductId:
              type: string
            variantAttributes:
              type: object
              additionalProperties:
                type: string
        food:
          type: object
          description: Food metadata for a food line item.
          properties:
            _id:
              type: string
            id:
              type: string
            name:
              type: string
            images:
              type: array
              items:
                type: string
                format: uri
            price:
              type: number
            promoPrice:
              type:
                - number
                - 'null'
        foodId:
          type: string
          description: Identifier of the food item when `itemType` is `food`.
        variant:
          type: string
          description: Identifier of the variant if the line item is variant-based.
        name:
          type: string
          description: Display name of the line item.
        image:
          type: string
          format: uri
          description: Primary image for the line item.
        price:
          type: number
          description: Unit price of the line item.
        sku:
          type: string
          description: SKU of the line item, if applicable.
        variantAttributes:
          type: object
          description: Attributes for the selected variant.
          additionalProperties:
            type: string
        quantity:
          type: integer
          minimum: 1
          description: Quantity of the line item in the cart.
        selectedAddons:
          type: array
          items:
            $ref: '#/components/schemas/SelectedAddon'
          description: Snapshot of selected add-ons for food items.
    SelectedAddon:
      type: object
      required:
        - addonId
        - name
        - price
        - quantity
      properties:
        addonId:
          type: string
        name:
          type: string
        description:
          type: string
        price:
          type: number
        quantity:
          type: integer
          minimum: 1
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT issued by the Salesive Store API for authenticated shoppers.
    ShopIdHeader:
      type: apiKey
      in: header
      name: x-shop-id
      description: >-
        Optional storefront identifier sent as a header to scope responses to a
        specific shop. Try It requests remember this value once provided.

````