Skip to content

X-Purchase Cart

X-Purchase-Cart provides high performance API for shopping cart.

Key features

  • Working with shopping cart;
  • Auto evaluating taxes and prices;
  • Multi-Laguage;
  • Multi-Currency;
  • Lazy resolving;

QueryRoot

List of queries:

# Endpoint Arguments Return
1 cart storeId cartName userId cultureName currencyCode cartType Shopping cart
2 carts storeId cartName userId cultureName currencyCode cartType sort skip take Paginated shopping cart list

Cart

{
    cart (storeId: "Electronics"
        cartName: "default"
        userId: "d97ee2c7-e29d-440a-a43a-388eb5586087"
        cultureName: "en-Us"
        currencyCode: "USD"
        cartType: "cart")
    {
        id
        name
        hasPhysicalProducts
        status
        storeId
        isAnonymous
        comment
        taxPercentRate
        taxType
        addresses { countryName regionName city addressType }
        dynamicProperties { name value valueType }
        shipments { shipmentMethodCode shipmentMethodOption }
        availableShippingMethods { code optionName optionDescription }
        discounts { amount description }
        currency { code symbol }
        payments { paymentGatewayCode }
        availablePaymentMethods { code paymentMethodType }
        items { id sku }
        coupons { code isAppliedSuccessfully }
        itemsCount
        itemsQuantity
        type
    }
}

[!TIP] See also CartType schema for better understanding of possible fields in request.

Carts connection

With this connection you can get all user's carts/whishlists. 

{
    carts (storeId: "Electronics"
        userId: "d97ee2c7-e29d-440a-a43a-388eb5586087"
        cultureName: "en-Us"
        currencyCode: "USD"
        cartType: "cart"
        take: 5
        skip: 0)
    {
        items
        {
            id
            name
            hasPhysicalProducts
            status
            storeId
            isAnonymous
        }
        pageInfo
        {
            startCursor
            endCursor
            hasNextPage
            hasPreviousPage
        }
    }
}

Queriable objects

CartType

CartType schema structure

CartType Addresses field

Field Cart.Addresses in CartType is a functional enabler. Currently it does not participate in any internal business logic and it is separated from Cart.Billing.Addresses and Cart.Shipping.Addresses. Feel free to add your own business logic to it. Address type structure can be found here.

Mutations

Every mutation contains base arguments for working with cart context: - storeId - Id of current store - cartName - Cart name - userId - Id of current user - currencyCode - Currency code (e.g. "USD") - cultureName - Culture name of current language (e.g. "en-Us") - cartType - Type of cart ("cart" or "whishlist")

Mutation list:

# Endpoint Arguments Description
1 addItem !productId !quantity price comment Add item to cart.
2 clearCart - Remove items from cart.
3 changeComment comment Update cart comment.
4 changeCartItemPrice !productId !price Change cart item price.
5 changeCartItemQuantity !lineItemId !quantity Change cart item quantity.
6 changeCartItemComment !lineItemId comment Change cart item comment.
7 removeCartItem !lineItemId Remove cart item from cart.
8 addCoupon !couponCode Add coupon to cart.
9 removeCoupon couponCode Remove coupon from cart. If coupon not passed clear all coupons from cart.
10 removeShipment shipmentId Remove shipment from cart.
11 addOrUpdateCartShipment !shipment(type) Add or update shipment for cart.
12 addOrUpdateCartPayment !payment(type) Add or update payment for cart.
13 validateCoupon !coupon Validate coupon, return result.
14 mergeCart !secondCartId Merge two carts into one.
15 removeCart !cartId Remove cart.
16 clearShipments - Clear cart shipments.
17 clearPayments - Clear cart payments.
18 updateCartDynamicProperties !dynamicProperties Updates dynamic properties in cart.
19 updateCartItemDynamicProperties !lineItemId !dynamicProperties Updates dynamic properties in cart items.
20 updateCartShipmentDynamicProperties !shipmentId !dynamicProperties Updates dynamic properties in cart shipment.
21 updateCartPaymentDynamicProperties !paymentId !dynamicProperties Updates dynamic properties in cart payment.
22 addCartAddress !address(type) Add address for cart or update it by type
23 addWishlistBulkItem !listIds !productId Add product to few wish lists.
24 refreshCart Refresh the contents of a shopping cart without making any modifications to the items in it.

[!NOTE] In arguments column we only show additional arguments. if they are marked with an exclamation mark, they are required.

AddItem

This mutation validates item and add it to cart, recalculate promotion rewards and taxes then save cart.

Query

mutation ($command:InputAddItemType!)
{
    addItem(command: $command)
    {
        name
        items
        {
            id
            sku
        }
        itemsCount
        itemsQuantity
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "productId": "9cbd8f316e254a679ba34a900fccb076",
        "quantity": 1,
        "dynamicProperties": [
            {
                "name": "ItemProperty",
                "value": "test value"
            }
        ]
    }
}

RefreshCart

This mutation loads the cart from its persistent storage, then immediately saves it back without any modifications. This effectively triggers any relevant price updates and clears any warnings that may have been present.

Query

mutation ($command:RefreshCartType!)
{
    refreshCart(command: $command)
    {
        itemsCount
        itemsQuantity
    }
}

Variables

{
  "command": {
    "storeId": "B2B-store",
    "userId": "39e3f3c5-7dd3-40ce-b48b-99549c1cd702",
    "cartId": "d77a2584-6b45-4b34-818a-9302ec15da5d"
  }
}

ClearCart

This mutation removes all items from cart, reset promotion rewards based on amount of items and save cart.

Query

mutation ($command:InputClearCartType!)
{
    clearCart(command: $command)
    {
        name
        items
        {
            id
            sku
        }
        itemsCount
        itemsQuantity
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart"
    }
}

ChangeComment

This mutation changes cart comment.

Query

mutation ($command:InputChangeCommentType!)
{
    сhangeComment(command: $command)
    {
        name
        comment
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "comment": "Hi, Virto! :)"
    }
}

ChangeCartItemPrice

This mutation changes cart item price.

Query

mutation ($command:InputChangeCartItemPriceType!)
{
    changeCartItemPrice(command: $command)
    {
        id
        items
        {
            sku
            productId
            listPrice
            listPriceWithTax
            salePrice
            salePriceWithTax
        }
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "productId": "9cbd8f316e254a679ba34a900fccb076",
        "price": 777
    }
}

ChangeCartItemQuantity

This mutation changes cart item quantity.

Query

mutation ($command:InputChangeCartItemQuantityType!)
{
    changeCartItemQuantity(command: $command)
    {
        id
        items
        {
            sku
            productId
            quantity
        }
        itemsCount
        itemsQuantity
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "lineItemId": "9cbd8f316e254a679ba34a900fccb076",
        "quantity": 7
    }
}

ChangeCartItemComment

This mutation changes cart item comment.

Query

mutation ($command:InputChangeCartItemCommentType!)
{
    changeCartItemComment(command: $command)
    {
        id
        items
        {
            sku
            productId
            comment
        }
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "lineItemId": "9cbd8f316e254a679ba34a900fccb076",
        "comment": "nice product"
    }
}

RemoveCartItem

This mutation removes item from cart.

Query

mutation ($command:InputRemoveItemType!)
{
    removeCartItem(command: $command)
    {
        id
        items
        {
            sku
            productId
        }
        itemsCount
        itemsQuantity
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "lineItemId": "9cbd8f316e254a679ba34a900fccb076",
    }
}

AddCoupon

This mutation checks and adds coupon to cart.

Query

mutation ($command:InputAddCouponType!)
{
    addCoupon(command: $command)
    {
        name
        coupons
        {
            code
            isAppliedSuccessfully
        }
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "couponCode": "freeItemsCouponCode",
    }
}

RemoveCoupon

This mutation removes coupon from cart.

Query

mutation ($command:InputRemoveCouponType!)
{
    removeCoupon(command: $command)
    {
        name
        coupons
        {
            code
            isAppliedSuccessfully
        }
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "couponCode": "freeItemsCouponCode",
    }
}

RemoveShipment

This mutation removes shipment from cart.

Query

mutation ($command:InputRemoveShipmentType!)
{
    removeShipment(command: $command)
    {
        name
        availableShippingMethods
        {
          code
          optionName
          optionDescription
        }
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "shipmentId": "7777-7777-7777-7777",
    }
}

AddOrUpdateCartShipment

This mutation adds or updates shipment of cart. This mutation supports partial update, all fields in command.shipment and command.shipment.deliveryAddress are optional.

Query

mutation ($command:InputAddOrUpdateCartShipmentType!)
{
    addOrUpdateCartShipment(command: $command)
    {
        name
        availableShippingMethods
        {
          code
          optionName
          optionDescription
        }
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "shipment": {
            "fulfillmentCenterId": "7777-7777-7777-7777",
            "height": 7,
            "shipmentMethodCode": "code",
            "currency": "USD",
            "price": 98,
            "dynamicProperties": [
                {
                    "name": "ShipmentProperty",
                    "value": "test value"
                }
            ]
        },
    }
}

[!TIP] To see all possible parametrs for shipment object look here...

AddOrUpdateCartPayment

This mutation adds or updates payment of cart. This mutation supports partial update, all fields in command.payment and command.payment.billingAddress are optional.

Query

mutation ($command:InputAddOrUpdateCartPaymentType!)
{
    addOrUpdateCartPayment(command: $command)
    {
        name
        availablePaymentMethods
        {
          code
          name
          paymentMethodType
        }
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "payment": {
            "outerId": "7777-7777-7777-7777",
            "paymentGatewayCode": "code",
            "currency": "USD",
            "price": 98,
            "amount": 55,
            "dynamicProperties": [
                {
                    "name": "PaymentProperty",
                    "value": "test value"
                }
            ]
        },
    }
}

[!TIP] To see all possible parametrs for payment object look here...

ValidateCoupon

This mutation validates coupon.

Query

mutation ($command:InputValidateCouponType!)
{
    validateCoupon(command: $command)
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "coupon": "freeItemsCouponCode"
    }
}

MergeCart

This mutation merges two carts. You can use it to merge anonymous cart with user cart after authorization.

Query

mutation ($command:InputMergeCartType!)
{
    mergeCart(command: $command)
    {
        id
        isAnonymous
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "secondCartId": "7777-7777-7777-7777",
    }
}

RemoveCart

This mutation removes cart.

Query

mutation ($command:InputRemoveCartType!)
{
    removeCart(command: $command)
}

Variables

{
    "command": {
        "cartId": "7777-7777-7777-7777"
    }
}

ClearShipments

This mutation removes all shipments from cart.

Query

mutation ($command:InputClearShipmentsType!)
{
    clearShipments(command: $command)
    {
        name
        availableShippingMethods
        {
          code
          optionName
          optionDescription
        }
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart"
    }
}

ClearPayments

This mutation removes all payments from cart.

Query

mutation ($command:InputClearPaymentsType!)
{
    clearPayments(command: $command)
    {
        name
        availablePaymentMethods
        {
          code
          name
          paymentMethodType
        }
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart"
    }
}

UpdateCartDynamicProperties

This mutation updates dynamic properties in cart

Query

mutation ($command: InputUpdateCartDynamicPropertiesType!)
{
    updateCartDynamicProperties(command: $command)
    {
        dynamicProperties
        {
            name
            value
            valueType
            dictionaryItem
            {
                label
                name
                id
            }
        }
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "dynamicProperties": [
            {
                "name": "Example string property",
                "value": "12345678"
            },
            {
                "name": "Example multilanguage property",
                "locale":"de-DE",
                "value": "hallo welt"
            },
            {
                "name": "Example dictionary property",
                "value": "578fadeb1d2a40b3b08b1daf8db09463"
            }
        ]
      }
    }
}

UpdateCartItemDynamicProperties

This mutation updates dynamic properties in cart item

Query

mutation ($command: InputUpdateCartItemDynamicPropertiesType!)
{
    updateCartItemDynamicProperties(command: $command)
    {
        items
        {
            id
            dynamicProperties
            {
                name
                value
                valueType
                dictionaryItem
                {
                    label
                    name
                    id
                }
            }
        }
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "lineItemId": "dab09410-aa1a-4daf-8a32-4e41abee77b8",
        "dynamicProperties": [
            {
                "name": "Example string property",
                "value": "12345678"
            },
            {
                "name": "Example multilanguage property",
                "locale":"de-DE",
                "value": "hallo welt"
            },
            {
                "name": "Example dictionary property",
                "value": "578fadeb1d2a40b3b08b1daf8db09463"
            }
        ]
      }
    }
}

UpdateCartShipmentDynamicProperties

This mutation updates dynamic properties in cart shipment

Query

mutation ($command: InputUpdateCartItemDynamicPropertiesType!)
{
    updateCartShipmentDynamicProperties(command: $command)
    {
        items
        {
            id
            dynamicProperties
            {
                name
                value
                valueType
                dictionaryItem
                {
                    label
                    name
                    id
                }
            }
        }
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "shipmentId": "79b8f095-9740-4353-998b-e1c4dd577ee6",
        "dynamicProperties": [
            {
                "name": "Example string property",
                "value": "12345678"
            },
            {
                "name": "Example multilanguage property",
                "locale":"de-DE",
                "value": "hallo welt"
            },
            {
                "name": "Example dictionary property",
                "value": "578fadeb1d2a40b3b08b1daf8db09463"
            }
        ]
      }
    }
}

UpdateCartPaymentDynamicProperties

This mutation updates dynamic properties in cart payment

Query

mutation ($command: InputUpdateCartItemDynamicPropertiesType!)
{
    updateCartPaymentDynamicProperties(command: $command)
    {
        items
        {
            id
            dynamicProperties
            {
                name
                value
                valueType
                dictionaryItem
                {
                    label
                    name
                    id
                }
            }
        }
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "paymentId": "0859f1e8-16e8-4924-808b-47e03560085d",
        "dynamicProperties": [
            {
                "name": "Example string property",
                "value": "12345678"
            },
            {
                "name": "Example multilanguage property",
                "locale":"de-DE",
                "value": "hallo welt"
            },
            {
                "name": "Example dictionary property",
                "value": "578fadeb1d2a40b3b08b1daf8db09463"
            }
        ]
      }
    }
}

AddCartAddress

This mutation adds a new address to cart or updates an existing one by addressType. This mutation supports partial update, all fields in command.address are optional.

Query

mutation addOrUpdateCartAddress ($command: InputAddOrUpdateCartAddressType!) {
    addOrUpdateCartAddress (command: $command) {
        addresses {
            addressType
            city
            countryCode
            countryName
            email
            firstName
            id
            lastName
            line1
            line2
            middleName
            name
            organization
            phone
            postalCode
            regionId
            regionName
            zip
        }
    }
}

Variables

{
    "command": {
        "storeId": "Electronics",
        "cartName": "default",
        "userId": "b57d06db-1638-4d37-9734-fd01a9bc59aa",
        "cultureName": "en-US",
        "currencyCode": "USD",
        "cartType": "cart",
        "address": {
          "city": "City name",
          "countryCode": "CountryCode",
          "countryName": "Country name",
          "email": "[email protected]",
          "firstName": "recipient name",
          "middleName": "recipient name",
          "lastName": "recipient name",
          "line1": "example address line 1",
          "line2": "example address line 1",
          "organization": "Organizatoin name",
          "phone": "77777-77777",
          "postalCode": "12345",
          "regionId": "RegionCode",
          "regionName": "Region name",
          "zip": "123",
          "addressType": 3
        }
    }
}

AddWishListBulkItem

This mutation adds a product to few wish lists.

Query

mutation addWishlistBulkItem ($command: InputAddWishlistBulkItemType!) {
    addWishlistBulkItem (command: $command) {    
         wishlists {          
          name
          id
          items {
            id
            quantity
            product {
              name
            }
          }
        }
    }
}

Variables

{
    "command": {
       "listIds": ["ce682f58-3bbd-42e5-a576-08c82a86ca11", "1b249c7a-5b7b-434d-a9b5-56a67ff993fe"],
       "productId" : "92e671024a8648de97dedcd488f58455"
    }
}
Last update: December 8, 2023