Handling line items on a basket

This article will guide you through how to handle line items on your basket, using our headless API. The Postman collection will be used for all examples.

In order to show changes to the basket immediately, you have the option of enabling a mini basket view in all of the following requests. Find out more in the Available views section.

Prerequisites

• accessToken from Connect flow.
• basketId from Creating a basket.

Adding a line item to a basket

Additional Prerequisites

• productCatalogId from Get product catalogs. (string)
• priceGroupId either from your basket or from Get price groups. (string)
• cultureCode, e.g en-US (string)
• Product sku (string)
• quantity of the product being added (integer)

Optional properties

• AddToExistingOrderLine, by default is set to true. If you set it to false, a new order line will be added. (boolean)
• A valid product VariantSku , if the product being added is a variant (string)
• A list of customProperties with key (string) and value (string) pairs that would be added to the line item.
• A custom price (decimal)

Create Orderline

Open the Create Orderline request.

Provide the mandatory path variable basketId together with the required and optional request body properties.

Request:

    
    
        curl -D- -X POST {base_url}/api/v1/baskets/{basketId}/lines \
            -H 'Authorization: Bearer <ACCESS_TOKEN>' 
            -H 'Content-Type: application/json' \
            -d '{
                    "Quantity": {quantity},
                    "Sku": {sku},
                    "VariantSku": {variantSku},
                    "PriceGroupId": {priceGroupId},
                    "ProductCatalogId": {productCatalogId},
                    "CultureCode": {cultureCode},
                    "customProperties":  [
                        {
                            "key" : {propKey},
                            "value": {propValue}
                        }
                    ]
                }'
    
    

Custom Price

By default, Ucommerce calculates the price of the order line based on price of the product. In some cases, you might want to specify a custom price to be used instead. This is done by specifying it in the payload with the price optional property. Note that this is only allowed if the access_token is granted the transactions:custom:price scope.

    
    
        curl -D- -X POST {base_url}/api/v1/baskets/{basketId}/lines \
            -H 'Authorization: Bearer <ACCESS_TOKEN>'
            -H 'Content-Type: application/json' \
            -d '{
                    "Quantity": {quantity},
                    "Price": {price},
                    "Sku": {sku},
                    "VariantSku": {variantSku},
                    "PriceGroupId": {priceGroupId},
                    "ProductCatalogId": {productCatalogId},
                    "CultureCode": {cultureCode}
                }'
    
    

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 has access to price setters, you are potentially open to price interception. We recommend not to use the transactions:custom:price scope outside of internal applications.

Deleting a line item from a basket

Sometimes it can be an advantage to completely delete a line from a basket. You can both do that with the combination of sku and varaint sku and the id of the line item. If you have the sku and variant sku on more than one line, you can delete one of the lines with its lineId by using it as a path variable.

Additional Prerequisites

• priceGroupId either from your basket or from Get price groups. (string)
• cultureCode, e.g. en-US (string)
• sku (string) OR lineId

Optional properties

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

Open the Delete Orderline request.

Provide the mandatory path variable - basketId, and the optional lineId, together with the required request body properties.

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

Updating a line item on a basket

During checkout, it can be handy to modify a line item on a basket. You can modify a line item by its id. Currently, we support modifying the following properties:

• Quantity
• Price
• VatRate

Note: When modifying the price or the VAT rate, your access_token needs the scope transactions:custom:price. If you modify the price and VAT rate, Ucommerce will not edit those values in the future.

Additional Prerequisites

• lineId
• priceGroupId either from your basket or from Get price groups. (string)
• cultureCode, e.g. en-US (string)

Optional properties

• quantity (integer)
• price (decimal)
• vatRate (decimal)

Open the Update Basket Oder Line request.

Provide mandatory path variables - basketId and lineId, together with the optional request body properties.

Note: The provided price is the price of the whole line item, without tax.

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

Possible errors that may occur

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

See Handling failures for more info.