Skip to content

Cart V2 API ​

Use the Cart V2 API for new integrations. Cart V2 works with V2 products. It supports variant groups, SKUs, selling units, pre-orders, and bookings.

The V2 endpoints use these authentication rules:

  • An authenticated customer sends the Authorization: Bearer JWT_TOKEN header.
  • A guest customer sends the X-Session-Id header. Use Generate Cart Session ID to get a session ID.
  • Every request must have the X-MerchantApiKey header.
  • If a request has no token and no session ID, the API returns 400: "Please log in or start a guest session to continue."

Endpoints ​

EndpointMethodPath
List cart itemsGET/v2/carts/items
Add item to cartPOST/v2/carts/add
Replace booking timePATCH/v2/carts/booking/{cartItemId}
Increase item quantityPATCH/v2/carts/item/increment/quantity/{cartId}
Decrease item quantityPATCH/v2/carts/item/decrement/quantity/{cartId}
Remove itemPATCH/v2/carts/remove/{cartItemId}
Clear cartDELETE/v2/carts/clear
CheckoutPOST/v2/carts/checkout
Guest checkoutPOST/v2/carts/guest/checkout

Simple endpoints ​

These endpoints need only the headers. They have no request body.

EndpointPath parameterResponse dataResponse message
List cart itemsArray of cart itemsSuccess
Increase item quantitycartId (ID of the cart item)nullItem quantity increased
Decrease item quantitycartId (ID of the cart item)nullItem quantity decreased
Remove itemcartItemIdnullItem removed from cart
Clear cartnullCart cleared successfully

Example:

javascript
fetch('https://api.shopsynch.com/v2/carts/items', {
  method: 'GET',
  headers: {
    'X-Session-Id': 'GUEST_SESSION_ID',
    'X-MerchantApiKey': 'MERCHANT_API_KEY'
  }
})
  .then(response => response.json())
  .then(data => console.log(data));

Cart item (V2) ​

The list endpoint returns an array of cart items in the data field. The add and replace-booking endpoints return one cart item.

FieldTypeDescription
idstringID of the cart item.
productIdstringID of the product.
variantGroupIdstring or nullID of the selected variant group.
skuIdstring or nullID of the selected SKU.
customerIdstring or nullID of the customer.
sessionIdstring or nullGuest session ID.
cartBasketIdstringID of the cart basket that holds the item.
name, imagestringProduct name and image URL.
price, newPrice, discountnumberUnit price, unit price after discount, and discount.
productTypestringProduct type, for example SIMPLE or VARIABLE.
attributesobjectAttributes of the selected SKU.
skustring or nullStock keeping unit.
quantityInStockintegerQuantity that is available.
quantityintegerQuantity in the cart.
selectedUnitKey, selectedUnitLabelstring or nullSelling unit that the customer selects.
selectedUnitQuantity, unitMultiplierFromBase, baseQuantity, pricePerBaseUnitnumber or nullUnit values.
tenantIdstringID of the store.
availabilityModestringAvailability mode of the product.
scheduledDatedate or nullDate of a pre-order.
bookingDate, bookingStartTime, bookingResourceIddate, time, string or nullBooking details.
serviceLocationobject or nullLocation for a service.

Common errors ​

StatusMessage
400Please log in or start a guest session to continue.
400The requested quantity is more than what we have in stock. Only N items are available.
404The specified item could not be found in your cart.

Next steps ​

Build with joy