Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
How-tos
How-tos
  • Introduction
  • Product discovery
    • Product listing page
    • Product page
  • Placing orders
    • Shopping cart
      • Creating a shopping cart
      • Adding products to cart
      • Updating cart quantities
      • Removing products from cart
      • Displaying the cart summary
    • Checkout
      • Adding the customer
      • Adding a billing address
      • Adding a shipping address
      • Selecting a shipping method
      • Selecting a payment method
      • Adding a payment source
      • Adding a gift card or coupon
      • Placing the order
    • Subscriptions
      • Configuring a subscription model
      • Selecting the source order
      • Generating the subscriptions
      • Updating the subscriptions
    • Payments
      • Adyen
        • Adding the payment source
        • Sending back the payment details
        • Configuring the notification webhooks
        • Reusing the payment source
      • Axerve
        • Adding the payment source
        • Updating the payment intent
      • Braintree
        • Adding the payment source
        • Sending back the payment method nonce
        • Accepting local payments
        • Reusing the payment source
      • Checkout.com
        • Adding the payment source
        • Getting the payment details
        • Refreshing pending transactions
        • Reusing the payment source
      • Klarna
        • Adding the payment source
        • Sending back the authorization token
        • Reusing the payment source
      • PayPal
        • Adding the payment source
        • Preparing the payment for execution
      • Stripe
        • Adding the payment source
        • Refreshing the payment source
        • Reusing the payment source
      • Manual payments
        • Adding a wire transfer payment source
      • External payments
        • Adding the payment source
        • Reusing the payment source
    • Auto-capture
      • Enabling the auto-capture
      • Limiting the auto-capture amount
  • inventory
    • Inventory strategies
      • No split
      • Split shipments
      • Split by line items
      • Ship from first available (or primary)
      • Ship from primary
  • FAQ
    • Environments and initial setup
    • Authentication and access tokens
On this page
  • Problem
  • Solution
  • Examples
  • Additional notes
  • More to read
  1. Placing orders
  2. Shopping cart

Adding products to cart

How to add new items to your shopping cart

PreviousCreating a shopping cartNextUpdating cart quantities

Last updated 2 months ago

Problem

You want to implement the "add to cart" function on a product page. You have the order ID and either the new item ID or SKU code.

Solution

Adding a product (SKU) to a shopping cart means creating a new line item for an order. To do that, send a POST request to the /api/line_items endpoint, specifying the order and the SKU relationships.

Examples

Add an SKU to a shopping cart by ID

The following request adds the SKU identified by the "xYZkjABcde" ID to the order identified by the "yzkWXfgHQS" ID:

curl -g -X POST \
  'http://yourdomain.commercelayer.io/api/line_items' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "line_items",
      "attributes": {
        "quantity": 1,
        "name": "Grey T-Shirt XL",
        "image_url": "https://img.yourdomain.com/skus/TSHIRTB5B5B5XL.png",
        "_update_quantity": true
      },
      "relationships": {
        "order": {
          "data": {
            "type": "orders",
            "id": "yzkWXfgHQS"
          }
        },
        "item": {
          "data": {
            "type": "skus",
            "id": "xYZkjABcde"
          }
        }
      }
    }
  }'
{
  "data": {
    "id": "aBmNkPQRst",
    "type": "line_items",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/line_items/aBmNkPQRst"
    },
    "attributes": {
      "sku_code": "TSHIRTB5B5B5XL",
      "quantity": 2,
      "currency_code": "EUR",
      "unit_amount_cents": 12900,
      "unit_amount_float": 129.0,
      "formatted_unit_amount": "129,00€",
      "options_amount_cents": 0,
      "options_amount_float": 0.0,
      "formatted_options_amount": "0,00€",
      "total_amount_cents": 25800,
      "total_amount_float": 258.0,
      "formatted_total_amount": "258,00€",
      "name": "Grey T-Shirt XL",
      "image_url": "https://img.yourdomain.com/skus/TSHIRTB5B5B5XL.png",
      "tax_rate": null,
      "tax_breakdown": {},
      "item_type": "skus",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "metadata": {}
    },
    "relationships": {
      "order": {
        "links": {...}
      },
      "item": {
        "links": {...}
      },
      "line_item_options": {
        "links": {...}
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

If the quantity of the added item results higher than the available one in stock, the API responds with a 422 Unprocessable Entity error:

{
  "errors": [
    {
      "title": "is out of stock",
      "detail": "quantity - is out of stock",
      "code": "VALIDATION_ERROR",
      "source": {
        "pointer": "/data/attributes/quantity"
      },
      "status": "422",
      "meta": {
        "error": "out_of_stock"
      }
    }
  ]
}

Add an SKU to a shopping cart by code

The following request adds the SKU identified by the "TSHIRTB5B5B5XL" code to the order identified by the "yzkWXfgHQS" ID:

curl -g -X POST \
  'http://yourdomain.commercelayer.io/api/line_items' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "line_items",
      "attributes": {
        "quantity": 1,
        "sku_code": "TSHIRTB5B5B5XL",
        "name": "Grey T-Shirt XL",
        "image_url": "https://img.yourdomain.com/skus/TSHIRTB5B5B5XL.png",
        "_update_quantity": true
      },
      "relationships": {
        "order": {
          "data": {
            "type": "orders",
            "id": "yzkWXfgHQS"
          }
        }
      }
    }
  }'

On success, the API responds with a 201 Created status code, returning the created line item object:

{
  "data": {
    "id": "aBmNkPQRst",
    "type": "line_items",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/line_items/aBmNkPQRst"
    },
    "attributes": {
      "sku_code": "TSHIRTB5B5B5XL",
      "quantity": 2,
      "currency_code": "EUR",
      "unit_amount_cents": 12900,
      "unit_amount_float": 129.0,
      "formatted_unit_amount": "129,00€",
      "options_amount_cents": 0,
      "options_amount_float": 0.0,
      "formatted_options_amount": "0,00€",
      "total_amount_cents": 25800,
      "total_amount_float": 258.0,
      "formatted_total_amount": "258,00€",
      "name": "Grey T-Shirt XL",
      "image_url": "https://img.yourdomain.com/skus/TSHIRTB5B5B5XL.png",
      "tax_rate": null,
      "tax_breakdown": {},
      "item_type": "skus",
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "metadata": {}
    },
    "relationships": {
      "order": {
        "links": {...}
      },
      "item": {
        "links": {...}
      },
      "line_item_options": {
        "links": {...}
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

If the quantity of the added item results higher than the available one in stock, the API responds with a 422 Unprocessable Entity error:

{
  "errors": [
    {
      "title": "is out of stock",
      "detail": "quantity - is out of stock",
      "code": "VALIDATION_ERROR",
      "source": {
        "pointer": "/data/attributes/quantity"
      },
      "status": "422",
      "meta": {
        "error": "out_of_stock"
      }
    }
  ]
}

Additional notes

The _update_quantity param

Specifying "_update_quantity": true (or "_update_quantity": 1) in the request body lets you update the existing line item quantity (if any) instead of creating a new line item for the same SKU. That means:

  • if the item is already present in the shopping cart, its line item quantity attribute is updated

  • if the item is not present in the shopping cart a new line item is created and its quantity attribute is set to the quantity value

If you send the POST request without the "_update_quantity": true (or "_update_quantity": 1) param a new line item is always created, even if the line item SKU is already present in the shopping cart.

The name and image_url fields

Disabling the order's auto-refresh

By default, orders that are still editable are automatically refreshed each time they get updated and/or one of the related line items gets created, updated, or destroyed. This automatically triggers several actions that are calculated in sequence for each of the order's line items, resulting in a pretty intensive computation. This may lead to concurrent request issues and/or timeout errors, making the automatic refresh not ideal, especially when you have to deal with cart containing a large number of line items (e.g. B2B).

More to read

On success, the API responds with a 201 Created status code, returning the created (or ) line item object:

When creating a new line item, the only required attribute is quantity. Anyway, we recommend always populating the name and image_url fields (like in the examples above) in order to show the desired name and image in the and order management. When empty, Commerce Layer will try to populate name and image_url from the associated SKU fields.

If you are concerned about pure performance and prefer to get a refreshed snapshot of the order just before it rather than in real time, we strongly recommend disabling the order when needed.

See our documentation if you need more information on how to .

updated
cart summary
create a line item
placing
A sample product page with "add to cart" button
auto-refresh option