# Cart / Order Line Items

You can enable a mini cart view in the following requests to show changes to the cart immediately. Find out more in the [Views for Cart modifying operations](/readme/headless/reference/views-for-cart-modifying-operations.md)

## Prerequisites

* `access_token` from [Headless API Authentication](/readme/headless/headless-api-authentication.md)
* `cartId` from [Cart](/readme/headless/reference/cart.md#create-a-cart)

## Add Line Item to a Cart

### Parameters

* `catalogId` from [Catalogs](/readme/headless/reference/catalogs.md)
* `priceGroupId` from [Price Groups](/readme/headless/reference/price-groups.md) (string)
* `cultureCode`, e.g. `en-US` (string)
* `sku` (string)
* `quantity` (integer)

### Optional Parameters

* `addToExistingOrderline` (default: `true`). 
  * If `false`, a new order line will be added even if the SKU is already in the Cart. (boolean)
* `variantSku` used alongside `sku` to identify a product variant. (string)
* `customProperties` a list of `key` (string) and `value` (string) pairs
* `price` custom unit price for the line item (decimal)

### Request

```bash
curl -D- -X POST <base_url>/api/v1/carts/<cartId>/lines \
    -H 'Authorization: Bearer <ACCESS_TOKEN>'
    -H 'Content-Type: application/json' \
    -d '{
            "quantity": <quantity>,
            "sku": <sku>,
            "variantSku": <variantSku>,
            "priceGroupId": <priceGroupId>,
            "catalogId": <productCatalogId>,
            "cultureCode": <cultureCode>,
            "price" : <price>
            "customProperties":  [
                {
                    "key" : <propKey>,
                    "value": <propValue>
                }
            ]
        }'
```

### Custom Price

By default, Ucommerce calculates the price of the order line based on the product's price. To use a custom price instead, this can be specified in the `price` parameter.

{% hint style="warning" %}
**Note:** Due to risks associated with explicitly setting a product price, we recommend not to use custom price operations in publicly available applications and/or endpoints. Additionally, if the client can access price setters, you are potentially open to price interception. We recommend not to use the `transactions:custom:price` scope outside of internal applications.
{% endhint %}

## Delete Line Item from a Cart

A Line Item can be removed by either ID or SKU (and Variant SKU in case of a variant).

### Parameters

* `priceGroupId` from the Cart or from [Price Groups](/readme/headless/reference/price-groups.md)
* `cultureCode`, e.g. `en-US` (string)
* `sku` (string) or `lineId` (string)

### Optional Parameters

* `variantSku`, if the product being removed is a variant (string)

### Request

```bash
curl -D- -X DELETE <base_url>/api/v1/carts/<cartId>/lines/<lineId> \
    -H 'Authorization: Bearer <ACCESS_TOKEN>'
    -H 'Content-Type: application/json' \
    -d '{
            "PriceGroupId": <priceGroupId>,
            "CultureCode": <cultureCode>
        }'
```

## Update Line Item on a Cart

The following properties can be updated on a Line Item during checkout:

* Quantity
* Price
* TaxRate

{% hint style="info" %}
**Note:** When modifying the price or the tax rate, your access\_token needs the scope `transactions:custom:price`. If you modify the price and tax rate, Ucommerce will not edit those values in the future.
{% endhint %}

### Parameters

* `lineId` (string)
* `priceGroupId` [Price Groups](/readme/headless/reference/price-groups.md)
* `cultureCode`, e.g. `en-US` (string)

### Optional Parameters

* `quantity` (integer)
* `price` (decimal)
* `taxRate` (decimal)

```bash
curl -D- -X PATCH <base_url>/api/v1/carts/<cartId>/lines/<lineId>?PriceGroupId=<id>&CultureCode=<culture> \
    -H 'Authorization: Bearer <ACCESS_TOKEN>'
    -H 'Content-Type: application/json' \
    -d '{
            "Quantity": <quantity>,
            "Price": <price>,
            "TaxRate": <taxRate>           
        }'
```

### Error Handling

| Error              | Description                                                                                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BadRequest (400)   | The product does not exist; Price Group does not exist; Order Line does not exist; Mismatch between Cart and Price Group's currency; pipeline execution fails. |
| Unauthorized (401) | The token is expired.                                                                                                                                          |
| Forbidden (403)    | The token does not have access to this endpoint.                                                                                                               |
| NotFound (404)     | Cart does not exist.                                                                                                                                           |

Error Response Example

```json
{
"errors":
    [
        {
            "error-description": "Cart does not exist..",
            "error": "NotFound"
        }
    ]
}
```

## Related Articles

{% content-ref url="/pages/OKRcu1Dp3gn5Y38w55HD" %}
[Error Handling](/readme/headless/error-handling.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.ucommerce.net/readme/headless/reference/cart-order-line-items.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.