Cart endpoint

Article Version

1.0.0 or newer

Table of contents

The cart endpoint is used for various cart operations like adding line items to the cart, removing them, change their quantity and placing an order.

Create an empty cart

POST  /storefront-api/checkout/cart
Response: If successful, the x-sw-context-token will be returned and the x-sw-context-token header will be set. Include this token as an HTTP header for all future requests.

Get a cart

GET  /storefront-api/checkout/cart

Header: x-sw-context-token is required

Response: If successful, the calculated cart will be returned. 

Add product to cart

POST  /storefront-api/checkout/cart/product/{id}

Header: x-sw-context-token is required

Parameter:

NameTypeNotesRequired
quantityintDefault: 1 
payloadarray  

Header: x-sw-context-token is required

Response: If successful, the calculated cart will be returned.

Add line item to cart

POST  /storefront-api/checkout/cart/line-item/{id}

Header: x-sw-context-token is requiredParameter:

NameTypeNotesRequired
typestring 
payloadarray  
quantityintDefault: 1 
stackablebooleanDefault: false, if set to true, quantity cannot be changed 
removablebooleanDefault: false, if set to true, line items cannot be removed from cart 
priorityintOrder in which the line items will be processed and calculated. The default is 100. Lower priority comes first. 
labelstring  
descriptionstring  
coverIduuidUUID of a media entity 

Header: x-sw-context-token is required

Response: If successful, the calculated cart will be returned.

Remove line item from cart

DELETE  /storefront-api/checkout/cart/line-item/{id}

Header: x-sw-context-token is required

Response: If successful, the calculated cart will be returned.

Update line item quantity

PATCH  /storefront-api/checkout/cart/line-item/{id}/quantity/{quantity}

Header: x-sw-context-token is required

Response: If successful, the calculated cart will be returned.

Update line item

PATCH  /storefront-api/checkout/cart/line-item/{id}

Header: x-sw-context-token is required

Parameter:

NameTypeNotesRequired
payloadarray  
quantityintDefault: 1 
stackablebooleanDefault: false, if set to true, quantity cannot be changed 
removablebooleanDefault: false, if set to true, line items cannot be removed from the cart 
priorityintOrder in which the line items will be processed and calculated. The default is 100. Lower priority comes first. 
labelstring  
descriptionstring  
coverIduuidUUID of a media entity 

Response: If successful, the calculated cart will be returned.

Create an order

POST  /storefront-api/checkout/order

Header: x-sw-context-token is required

Response: If successful, the order will be returned.

Create a guest order

POST  /storefront-api/checkout/guest-order

Header: x-sw-context-token is required

Parameter: For the parameter, please have a look at thecustomer registration. The guest parameter is always set to true. 

Response: If successful, the order will be returned.

Start the payment process for an order

POST  /storefront-api/checkout/pay/order/{orderId}

Header: x-sw-context-token is required

Parameter: If finishUrl is set, the customer will be redirected to this URL after the payment process is completed. 

Response: The response depends on the type of the payment processor used. A payment processor can define if the user needs to be redirected to an external payment gateway. If that's the case, you get a response which includes a paymentUrl. This is the URL of the external payment gateway where you have to redirect the user to. If the payment process is completed or the payment processor use an external payment gateway, you will receive an empty response.

GET  /storefront-api/checkout/guest-order/{id}

Parameter: The accessCode parameter is required and will be returned when a guest order is placed.

Response: If successful, the order will be returned.

Full example


const accessKey = '{insert your storefront access key}';
const baseUrl = '{insert your url}';

let customer = {
    firstName: 'Max',
    lastName: 'Mustermann',
    email: 'max.mustermann@example.com',
    billingStreet: 'Buchenweg 5',
    billingZipcode: '33602',
    billingCity: 'Bielefeld'
};
let headers = {
    "Content-Type": "application/json",
    "X-SW-Access-Key": accessKey
};

function initCart() {
    const init = { method: 'POST', headers };
    return fetch(baseUrl + '/storefront-api/checkout/cart', init)
        .then((resp) => resp.json())
        .then(({ 'x-sw-context-token': contextToken }) => {
            headers['x-sw-context-token'] = contextToken;
        });
}

function getCart() {
    const init = { method: 'GET', headers };
    return fetch(baseUrl + '/storefront-api/checkout/cart', init)
        .then((resp) => resp.json());
}

function addProductToCart(productId) {
    const url = `${baseUrl}/storefront-api/checkout/cart/product/${productId}`;
    return fetch(url, { method: 'POST', headers })
        .then((resp) => resp.text());
}

function getProducts() {
    return fetch(baseUrl + '/storefront-api/product', { headers })
        .then((resp) => resp.json())
        .then(({ data }) => data)
}

function changeLineItemQuantity(key, quantity) {
    const url = `${baseUrl}/storefront-api/checkout/cart/line-item/${key}/quantity/${quantity}`;
    return fetch(url, { method: 'PATCH', headers })
        .then((resp) => resp.json());
}

function getCountry(iso3) {
    const url = `${baseUrl}/storefront-api/sales-channel/countries?filter[iso3]=${iso3}`;
    return fetch(url, { method: 'GET', headers })
        .then((resp) => resp.json())
        .then(({ data }) => data[0]);
}

function guestOrder(customer) {
    const url = `${baseUrl}/storefront-api/checkout/guest-order`;
    const body = JSON.stringify(customer);
    return fetch(url, { method: 'POST', headers, body })
        .then((resp) => resp.json())
        .then(({ data }) => data);
}

function getGuestOrder(orderId, accessCode) {
    const url = new URL(`${baseUrl}/storefront-api/checkout/guest-order/${orderId}`);
    url.searchParams.append('accessCode', accessCode);

    return fetch(url, { method: 'GET', headers })
        .then((resp) => resp.json())
        .then(({ data }) => data);
}

async function checkoutExample() {
    await initCart();
    console.log('Cart', await getCart());

    const [p1, p2] = await getProducts();
    await addProductToCart(p1.id);
    await addProductToCart(p2.id);
    let cart = await getCart();
    console.log('Cart', cart);

    const lineItem = cart.data.lineItems[0];
    await changeLineItemQuantity(lineItem.key, 2);
    console.log('Cart', await getCart());

    const country = await getCountry('deu');

    customer['billingCountry'] = country.id;
    const order = await guestOrder(customer);
    console.log('Order', order);

    console.log('Order by access code', await getGuestOrder(order.id, order.deepLinkCode))
}

checkoutExample().then(() => {
    console.log('Checkout completed');
});