Working with the cart

Overiew

Any online store would be useless if it wasn't shoppable. Hence we need a cart where we can collect items which we want to buy.

Implicitly, a cart is associated with your sw-context-token header.

Create a new cart

To create a new one, make sure to set a context token header. If you want to, you can also pass a name to identify the cart later on.

// POST /store-api/v3/checkout/cart
{
"name": "my-cart"
}

Response

{
"name": "my-cart",
"token": "nqVMbLr8Q1Vs5jFdz4xk4vkSXAEKiOMt",
"price": {
"netPrice": 0,
"totalPrice": 0,
"calculatedTaxes": [],
"taxRules": [],
"positionPrice": 0,
"taxStatus": "gross",
"apiAlias": "cart_price"
},
"lineItems": [],
"errors": [],
"deliveries": [],
"transactions": [
{
"amount": {
"unitPrice": 0,
"quantity": 1,
"totalPrice": 0,
"calculatedTaxes": [],
"taxRules": [],
"referencePrice": null,
"listPrice": null,
"apiAlias": "calculated_price"
},
"paymentMethodId": "35ce6af5a12a49708740a38bbbdf517e",
"apiAlias": "cart_transaction"
}
],
"modified": false,
"customerComment": null,
"affiliateCode": null,
"campaignCode": null,
"extensions": {
"cart-promotions": {
"addedCodes": [],
"blockedPromotionIds": [],
"apiAlias": "shopware_core_checkout_promotion_cart_extension_cart_extension"
}
},
"apiAlias": "cart"
}

If you want to delete your cart, you can sent a DELETE request to the same endpoint.

Adding new items to the cart

The api POST /store-api/v3/checkout/cart/line-item can be used to add multiple new line items.

Product

// POST /store-api/v3/checkout/cart/line-item
{
"items": [
{
"type": "product",
"referencedId": "<productId>"
},
{
"type": "product",
"referencedId": "<productId>",
"quantity": 2
}
]
}

You can set following properties on a product line item: referencedId, payload and quantity. When the Line Item is wrong miss-configured, the cart will add an error. This error is in the error key in the response.

Promotion

// POST /store-api/v3/checkout/cart/line-item
{
"items": [
{
"type": "promotion",
"referencedId": "<promotionCode>"
}
]
}

Error-Handling

When you pass invalid line item configuration to the API the cart calculation process will remove the line items again and add errors to the cart. This errors are ~~~~in the error key in the cart response. An example for an invalid referencedId would be look like this:

"errors": {
"product-not-foundfc2376912354406d80dd8887fc30ffa8": {
"id": "fc2376912354406d80dd8887fc30ffa8",
"message": "The product %s could not be found",
"code": 0,
"line": 166,
"key": "product-not-foundfc2376912354406d80dd8887fc30ffa8",
"level": 10,
"messageKey": "product-not-found"
}
}

Updating items in the cart

Use the PATCH /store-api/v3/checkout/cart/line-item endpoint to update line items in to cart.

// PATCH /store-api/v3/checkout/cart/line-item
{
"items": [
{
"id": "<id>",
"quantity": <quantity>,
"referencedId": "<newReferenceId>"
}
]
}

Deleting items in the cart

The api DELETE /store-api/v3/checkout/cart/line-item can be used to remove line items to the cart

// DELETE /store-api/v3/checkout/cart/line-item
{
"ids": [
"<id>"
]
}

Creating an order from the cart

The endpoint /store-api/v3/checkout/order can be used to create an order from the cart. You will need items in the cart and you need to be logged in.

// POST /store-api/v3/checkout/order
{
"includes": {
"order": ["orderNumber", "price", "lineItems"],
"order_line_item": ["label", "price"]
}
}
{
"orderNumber": "10060",
"price": {
"netPrice": 557.94,
"totalPrice": 597,
"calculatedTaxes": [
{
"tax": 39.06,
"taxRate": 7,
"price": 597,
"apiAlias": "cart_tax_calculated"
}
],
"taxRules": [
{
"taxRate": 7,
"percentage": 100,
"apiAlias": "cart_tax_rule"
}
],
"positionPrice": 597,
"taxStatus": "gross",
"apiAlias": "cart_price"
},
"lineItems": [
{
"label": "Aerodynamic Bronze Prawn Crystals",
"price": {
"unitPrice": 597,
"quantity": 1,
"totalPrice": 597,
"calculatedTaxes": [
{
"tax": 39.06,
"taxRate": 7,
"price": 597,
"apiAlias": "cart_tax_calculated"
}
],
"taxRules": [
{
"taxRate": 7,
"percentage": 100,
"apiAlias": "cart_tax_rule"
}
],
"referencePrice": null,
"listPrice": null,
"apiAlias": "calculated_price"
},
"apiAlias": "order_line_item"
}
],
"customerComment": "comment",
"affiliateCode": "affiliate code",
"campaignCode": "campaign code",
"apiAlias": "order"
}

Depending on your requirements, you might need additional data from the order. You can control what gets passed using the includes parameter in the request body. Some interesting fields:

order.deliveries

Shopware's data model is capable of representing multiple deliveries or shipments within a single order. Each delivery can have a different set of items, shipping method and delivery dates. However, in our current version, Shopware doesn't support creation of multiple deliveries out of the box, so most likely, you'll just be using order.deliveries[0] .

order.transactions

A transaction represents a payment for an order. It contains a payment method, an amount and a state. An order can have multiple payments (for example, if a payment fails, you can switch methods and create a second transaction with an alternative payment method).

order.addresses

An order can have multipel associated addresses (e.g. for shipping or deliverie/s). Those will be passed in the addresses association. You can map them using their references in the order, such as order.billingMethodId or order.deliveries[*].shippingOrderAddressId .

order.lineItems

This field contains all line items of the order. Line items may not only be products, but also discounts or virtual items, like bundles. Line items are stored as copies of their corresponding products, so when a product is deleted in your store, the line items from older orders remain available.

All the above also applies to the /order endpoint, which simply lists orders for the current customer.

Payment methods

The endpoint /store-api/v3/payment-method can be used to list all payment methods of the sales channel. With the parameter onlyAvailable you can restrict the result to only valid payments methods (some payment methods can be generally available, but dynamically disabled based on the cart configuration or other parameters)

Additionally, the api basic parameters (filter, aggregations, etc.) can be used to restrict the result.

// POST /store-api/v3/payment-method
{
"includes": {
"payment_method": ["name", "description", "active"]
}
}
[
{
"name": "Cash on delivery",
"description": "Payment upon receipt of goods.",
"active": true,
"apiAlias": "payment_method"
},
{
"name": "Paid in advance",
"description": "Pay in advance and get your order afterwards",
"active": true,
"apiAlias": "payment_method"
}
]

Shipping methods

The endpoint /store-api/v3/shipping-method can be used to list all payment methods of the sales channel. With the parameter onlyAvailable you can restrict the result to only valid shipping methods. The same logic as for payment methods applies in here.

Also here, the api basic parameters (filter, aggregations, etc.) can be used to restrict the result.

// POST /store-api/v3/shipping-method
{
"includes": {
"shipping_method": ["name", "active", "deliveryTime"],
"delivery_time": ["name", "unit"]
}
}
[
{
"name": "Express",
"active": true,
"deliveryTime": {
"name": "1-3 days",
"unit": "day",
"apiAlias": "delivery_time"
},
"apiAlias": "shipping_method"
}
]