Read and update the Cart of the current session, and start payment.

Queries

Get Cart

QUERYcart
Returns the Cart of the current session, without an id or version. A guest session has an anonymous Cart. null if the session has no Cart yet.
Output:Cart
Request Example:graphql
query GetCart {
  cart {
    id
    lineCount
    lines { sku quantity }
    totals {
      subtotal { formatted }
      grandTotal { formatted }
    }
    availableActions
  }
}
Response Example:json
{
  "data": {
    "cart": {
      "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
      "lineCount": 1,
      "lines": [{ "sku": "CHAIR-OAK-01", "quantity": 2 }],
      "totals": {
        "subtotal": { "formatted": "£178.00" },
        "grandTotal": { "formatted": "£178.00" }
      },
      "availableActions": ["GUEST_CHECKOUT", "CLEAR"]
    }
  }
}

Get Shipping Methods for Cart

QUERYshippingMethodsForCart

Returns the Shipping Methods that can deliver the Cart of the current session. Empty if the session has no Cart or the Cart has no shipping address.

Request Example:graphql
query GetShippingMethodsForCart {
  shippingMethodsForCart {
    id
    name
    price { formatted }
  }
}
Response Example:json
{
  "data": {
    "shippingMethodsForCart": [
      {
        "id": "AQsAAdHT09Xh4k8eihuxsrO1tbcAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "name": "Standard delivery",
        "price": { "formatted": "£4.95" }
      },
      {
        "id": "AQsAAeHj4-Xx8kobixrBwsPFxccAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "name": "Express delivery",
        "price": { "formatted": "£9.95" }
      }
    ]
  }
}

Get payment methods

QUERYpaymentMethods
Returns the payment methods that the project accepts, sorted by key. Lists active payment methods that aren't assigned to a Customer or Business Unit. Empty if the project accepts none.

The list doesn't depend on the Cart, so you can read it at any point in checkout.

Request Example:graphql
query GetPaymentMethods {
  paymentMethods { key label }
}
Response Example:json
{
  "data": {
    "paymentMethods": [
      { "key": "credit-card", "label": "Credit card" },
      { "key": "digital-wallet", "label": "Digital wallet" }
    ]
  }
}

Mutations

Add Line Item to Cart

MUTATIONaddCartLine

Adds a Product Variant to the Cart of the current session. Creates the Cart if the session has none.

A refusal is reported in userErrors, for example UNKNOWN_SKU, NOT_IN_ASSORTMENT, PRICE_NOT_AVAILABLE, or OUT_OF_STOCK.
Arguments
input​

Line to add.

Request Example:graphql
mutation AddCartLine {
  addCartLine(input: {sku: "CUSHION-LINEN-GREY", quantity: 1}) {
    cart {
      id
      lineCount
      lines { sku quantity }
    }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "addCartLine": {
      "cart": {
        "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "lineCount": 1,
        "lines": [{ "sku": "CUSHION-LINEN-GREY", "quantity": 1 }]
      },
      "userErrors": []
    }
  }
}

Add Line Items to Cart

MUTATIONaddCartLines

Adds several Product Variants to the Cart of the current session in one call, for example from a quick-order form. Creates the Cart if the session has none.

All lines are added, or none: if one entry is refused, no entry is added.

Arguments
inputs​
Array of AddCartLineInput​
One entry for each line. A refusal names its entry in field, for example inputs.2.sku or inputs.2.quantity.
Request Example:graphql
mutation AddCartLines {
  addCartLines(
    inputs: [{sku: "CHAIR-OAK-01", quantity: 2}, {sku: "CUSHION-LINEN-GREY", quantity: 1}]
  ) {
    cart {
      id
      lineCount
      lines { sku quantity }
    }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "addCartLines": {
      "cart": {
        "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "lineCount": 2,
        "lines": [
          { "sku": "CHAIR-OAK-01", "quantity": 2 },
          { "sku": "CUSHION-LINEN-GREY", "quantity": 1 }
        ]
      },
      "userErrors": []
    }
  }
}

Change Line Item quantity

MUTATIONupdateCartLineQuantity

Changes the quantity of a line in the Cart of the current session.

Arguments
input​

The line and its new quantity.

Request Example:graphql
mutation UpdateCartLineQuantity {
  updateCartLineQuantity(
    input: {lineId: "AQwDASIjIiMiIkIjoiMiIiIjIiMA8vLz8iIiQiKjIiMiIiIiIgEAAAABAAEAAA", quantity: 2}
  ) {
    cart {
      id
      lines { sku quantity }
    }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "updateCartLineQuantity": {
      "cart": {
        "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "lines": [{ "sku": "CHAIR-OAK-01", "quantity": 2 }]
      },
      "userErrors": []
    }
  }
}

Set Custom Fields on Line Item

MUTATIONupdateCartLineCustomFields
Sets Custom Fields on a line that is already in the Cart of the current session, for example a pickup point chosen later in checkout. To set Custom Fields when you add a line, use addCartLine.
The custom input has the same project-specific shape that addCartLine takes. Only the fields you pass change: a value replaces the field, null clears it, and an omitted field keeps its value. Text, number, boolean, enum, and their set types can be written. Other field types, such as money, references, and localized enums, aren't in the input.
Arguments
input​

The line and the values to set.

Request Example:graphql
# custom and GiftMessageCustom come from a line item Custom Type with the key gift-message.
mutation UpdateCartLineCustomFields {
  updateCartLineCustomFields(
    input: { lineId: "AQwDASIjIiMiIkIjoiMiIiIjIiMA8vLz8iIiQiKjIiMiIiIiIgEAAAABAAEAAA", custom: { message: "Happy birthday!" } }
  ) {
    cart {
      id
      lines { sku custom { __typename ... on GiftMessageCustom { message } } }
    }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "updateCartLineCustomFields": {
      "cart": {
        "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "lines": [
          {
            "sku": "CHAIR-OAK-01",
            "custom": { "__typename": "GiftMessageCustom", "message": "Happy birthday!" }
          }
        ]
      },
      "userErrors": []
    }
  }
}

Remove Line Item from Cart

MUTATIONremoveCartLine

Removes a line from the Cart of the current session.

Arguments
input​

The line to remove.

Request Example:graphql
mutation RemoveCartLine {
  removeCartLine(
    input: {lineId: "AQwDASIjIiMiIkIjoiMiIiIjIiMA8_Py8zMzQzOiMzIzMzMzMwEAAAABAAEAAA"}
  ) {
    cart {
      id
      lineCount
      lines { sku quantity }
    }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "removeCartLine": {
      "cart": {
        "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "lineCount": 1,
        "lines": [{ "sku": "CHAIR-OAK-01", "quantity": 2 }]
      },
      "userErrors": []
    }
  }
}

Empty Cart

MUTATIONclearCart

Removes all lines from the Cart of the current session, including custom lines. Other data on the Cart, such as addresses, stays.

Request Example:graphql
mutation ClearCart {
  clearCart {
    cart {
      id
      lineCount
      lines { id }
    }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "clearCart": {
      "cart": {
        "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "lineCount": 0,
        "lines": []
      },
      "userErrors": []
    }
  }
}

Apply Discount Code

MUTATIONapplyDiscountCode

Applies a discount code to the Cart of the current session.

Leading and trailing spaces are removed, and the rest is matched exactly, including case. A code that doesn't match the Cart is removed again and reported as INVALID_DISCOUNT_CODE, DISCOUNT_CODE_EXPIRED, or DISCOUNT_CODE_NOT_APPLICABLE. A code that is already on the Cart is refused with DISCOUNT_CODE_ALREADY_APPLIED. If the session has no Cart yet, the code is refused with EMPTY_CART.
Arguments
code​
String​

Discount code to apply, as the shopper entered it.

Request Example:graphql
mutation ApplyDiscountCode {
  applyDiscountCode(code: "WELCOME10") {
    cart {
      id
      discounts { code name }
      totals {
        discountTotal { formatted }
      }
    }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "applyDiscountCode": {
      "cart": {
        "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "discounts": [
          { "code": "WELCOME10", "name": "Welcome 10% off" }
        ],
        "totals": { "discountTotal": { "formatted": "£20.20" } }
      },
      "userErrors": []
    }
  }
}

Remove Discount Code

MUTATIONremoveDiscountCode
Remove an entered Discount Code from discountCodes, with every discounts entry it unlocked; a code not on the cart is a no-op, a blank one INVALID_INPUT.
Arguments
code​
String​
Discount code to remove, from AppliedDiscount.code.
Request Example:graphql
mutation RemoveDiscountCode {
  removeDiscountCode(code: "WELCOME10") {
    cart {
      id
      discounts { code name }
      totals {
        discountTotal { formatted }
      }
    }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "removeDiscountCode": {
      "cart": {
        "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "discounts": [],
        "totals": { "discountTotal": null }
      },
      "userErrors": []
    }
  }
}

Set shipping address

MUTATIONsetShippingAddress

Sets the shipping address of the Cart of the current session. Creates the Cart if the session has none.

Refused with SHIPPING_COUNTRY_NOT_SUPPORTED if the project has no tax rate for the country, and with INVALID_COUNTRY if country isn't a valid ISO 3166-1 alpha-2 code.
Arguments
input​

The address to ship to.

Request Example:graphql
mutation SetShippingAddress {
  setShippingAddress(
    input: {name: "Jane Doe", line1: "1 Example Street", city: "London", postalCode: "SW1A 1AA", country: "GB"}
  ) {
    cart {
      id
      shippingAddress { name city country }
    }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "setShippingAddress": {
      "cart": {
        "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "shippingAddress": {
          "name": "Jane Doe",
          "city": "London",
          "country": "GB"
        }
      },
      "userErrors": []
    }
  }
}

Set billing address

MUTATIONsetBillingAddress

Sets the billing address of the Cart of the current session. Creates the Cart if the session has none.

Refused with INVALID_COUNTRY if country isn't a valid ISO 3166-1 alpha-2 code.
Arguments
input​

The address to bill.

Request Example:graphql
mutation SetBillingAddress {
  setBillingAddress(
    input: {name: "Jane Doe", line1: "1 Example Street", city: "London", postalCode: "SW1A 1AA", country: "GB"}
  ) {
    cart {
      id
      billingAddress { name city country }
    }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "setBillingAddress": {
      "cart": {
        "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "billingAddress": {
          "name": "Jane Doe",
          "city": "London",
          "country": "GB"
        }
      },
      "userErrors": []
    }
  }
}

Set Customer email

MUTATIONsetCustomerEmail

Sets the email address under which a guest places the Order, on the Cart of the current session.

For guest sessions only. A signed-in session is refused with FORBIDDEN_ACTION: its Order uses the email address of the Customer account. See Set Customer Email.
Arguments
input​

The guest's email address.

Request Example:graphql
mutation SetCustomerEmail {
  setCustomerEmail(input: {email: "jane.doe@example.com"}) {
    cart { id customerEmail }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "setCustomerEmail": {
      "cart": {
        "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "customerEmail": "jane.doe@example.com"
      },
      "userErrors": []
    }
  }
}

Set purchase order number

MUTATIONsetPurchaseOrderNumber

Sets the purchase order number of the Cart of the current session.

Arguments
purchaseOrderNumber​
String​
If omitted, null, or an empty string, any existing number is removed.
Request Example:graphql
mutation SetPurchaseOrderNumber {
  setPurchaseOrderNumber(purchaseOrderNumber: "PO-2026-0042") {
    cart { id purchaseOrderNumber }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "setPurchaseOrderNumber": {
      "cart": {
        "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "purchaseOrderNumber": "PO-2026-0042"
      },
      "userErrors": []
    }
  }
}

Select Shipping Method for Cart

MUTATIONselectShippingMethod

Sets the Shipping Method of the Cart of the current session.

Refused with EMPTY_CART if the session has no Cart yet, with SHIPPING_ADDRESS_REQUIRED if the Cart has no shipping address, and with UNKNOWN_SHIPPING_METHOD if the Shipping Method doesn't exist or has no rate for the Cart.
Arguments
input​

The Shipping Method to select.

Request Example:graphql
mutation SelectShippingMethod {
  selectShippingMethod(
    input: {shippingMethodId: "AQsAAdHT09Xh4k8eihuxsrO1tbcAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA"}
  ) {
    cart {
      id
      shippingMethod { key name }
    }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "selectShippingMethod": {
      "cart": {
        "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "shippingMethod": {
          "key": "standard",
          "name": "Standard delivery"
        }
      },
      "userErrors": []
    }
  }
}

Remove Shipping Method from Cart

MUTATIONclearShippingMethod

Removes the Shipping Method from the Cart of the current session. Removing it from a Cart without one succeeds and changes nothing.

While a Shipping Method is selected, a shipping address that the method has no rate for is refused with UNKNOWN_SHIPPING_METHOD. To change to such an address, clear the Shipping Method first and select a new one afterwards. An Order can be placed without a Shipping Method, see PlaceOrderInput.shippingMethodId.
Request Example:graphql
mutation ClearShippingMethod {
  clearShippingMethod {
    cart {
      id
      shippingMethod { key name }
      totals {
        shipping { formatted }
      }
    }
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "clearShippingMethod": {
      "cart": {
        "id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "shippingMethod": null,
        "totals": { "shipping": null }
      },
      "userErrors": []
    }
  }
}

Start payment with Checkout

MUTATIONbeginPayment
Starts payment with Checkout for the Cart of the current session. Checkout authorizes the payment and creates the Order.
Call it when the shopper reaches checkout, because the Checkout Session expires. Each call creates a new Checkout Session, so call it again when you remount the flow. Refused with EMPTY_CART if the Cart has no lines.
Request Example:graphql
mutation BeginPayment {
  beginPayment {
    paymentTicket
    projectKey
    region
    mode
    payable { amount currencyCode }
    expiresAt
    userErrors { code message field }
  }
}
Response Example:json
{
  "data": {
    "beginPayment": {
      "paymentTicket": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "projectKey": "example-project",
      "region": "europe-west1.gcp",
      "mode": "PAYMENT_ONLY",
      "payable": { "amount": "186.75", "currencyCode": "GBP" },
      "expiresAt": "2026-09-14T11:15:00.000Z",
      "userErrors": []
    }
  }
}

Output types

Cart

The current session's shopping cart, from which checkout places an Order. See Carts.

A session has one active Cart for each combination of Store, currency, and country. The Cart is created when a mutation first changes it.

id​
ID​

Unique identifier of the Cart.

lineCount​
Int​

Number of lines in the Cart, including custom lines.

lines​
Array of CartLine​

Lines of the Cart, with Product Variant lines first and custom lines last.

discounts​
Array of AppliedDiscount​
Every applied discount, one entry per discount and target, its amount summed over the cart: Product Discounts included, except where a Best Deal rejected them. The non-SHIPPING entries add up to totals.discountTotal.
discountCombination​

How Product Discounts and Cart Discounts were combined on this cart.

discountCodes​
Array of DiscountCodeInfo​

The Discount Codes entered on this cart, and where each stands.

totals​

Totals of the Cart, to display in the cart summary.

shippingAddress​
Shipping address of the Cart. Determines which Shipping Methods are available. null if not set.
billingAddress​
Address the Order is billed to. null if not set.
customerEmail​
String​
Email address of the Customer that the Cart belongs to. A guest sets it with setCustomerEmail. null if not set.
purchaseOrderNumber​
String​
Purchase order number that the buyer assigns to the Cart. Set it with setPurchaseOrderNumber. null if not set.
origin​

Origin of the Cart.

Can be CUSTOMER, MERCHANT, QUOTE, or RECURRING_ORDER​
shippingMethod​
Shipping Method selected for the Cart. null if none is selected.
availableActions​
Array of CartAction​

What the current viewer can do with this Cart, to show or hide the matching controls. Empty if the Cart has no lines.

Can be CHECKOUT, GUEST_CHECKOUT, CLEAR, or REQUEST_QUOTE​
_ctId​
ID​
Platform id of the Cart, for an extension that keys an external system by it, such as an order management system. Read this field instead of parsing id.
Not part of the public API: available to @requires, and removed from the composed schema.

Cart Line

A line in a Cart: a Product Variant and its quantity, or a custom line that the merchant added.

id​
ID​
Unique identifier of the Cart line. Pass it as lineId to change or remove the line.
sku​
String​

SKU of the Product Variant. Empty string for a custom line.

productName​
String​

Name of the Product in the session's locale. For a custom line, the name of the line.

slug​
String​

Slug of the Product in the session's locale. Empty string for a custom line.

image​
First image of the Product Variant. null if the Product Variant has no image, and for a custom line.
quantity​
Int​

Quantity of the Product Variant in the Cart.

isGift​
Boolean​
Whether this is a free Gift Line Item the platform added. Its Portion lists the gift discount that added it, which carries the same id as that discount's entry in discounts.
unitPriceBeforeDiscount​

One unit before any discount: the Line Item's price.

priceMode​

How the Line Item's price was set; null for a custom line.

Can be PLATFORM, EXTERNAL_PRICE, or EXTERNAL_TOTAL​
discountedPrice​
One unit after its Product Discount, and the Product Discount behind it; null when none applies. Kept where a Best Deal rejected it: see rejectedByBestDeal.
portions​
Array of Portion​

The Line Item's units grouped by what one unit costs after Cart Discounts; at least one.

lineTotal​
What this Line Item costs after every discount: its Portions' unitPrice times quantity, added up. On an EXTERNAL_TOTAL Line Item it is the total the external system set instead.
availability​
Stock available for this line. A custom line, or a Product Variant without tracked inventory, has inStock set to true and quantity set to null.

Line Price Mode

How the price of a Line Item was set. See Line Item price mode.
PLATFORM
Selected by the platform from the Product Variant's prices.
EXTERNAL_PRICE
One unit's price was set by an external system. Cart Discounts apply to the Line Item; Product Discounts do not.
EXTERNAL_TOTAL
The Line Item's unit price and total were set by an external system. No discount reduces it, though its total counts toward the price a `TOTAL_PRICE` discount reduces.

Line Item Discounted Price

A Line Item's price after its Product Discount, per unit, and whether a Best Deal rejected it.

value​
productDiscount​
rejectedByBestDeal​
Boolean​
Whether a Best Deal won by Cart Discounts dropped this Product Discount from the Line Item. If so, its Portions start from unitPriceBeforeDiscount, and the Product Discount counts in neither discounts nor discountTotal.

Product Discount Info

The Product Discount behind a discounted price.

id​
ID​
Opaque id of the Product Discount, the same as the AppliedDiscount.id it has in a cart's discounts. Clients never parse it.
key​
String​

The merchant's key for the Product Discount, where one is set.

name​
String​

The Product Discount's name in the session's locale; null where it has none for that locale.

valueType​

How it reduces; null once the Product Discount is deleted.

Can be RELATIVE, ABSOLUTE, FIXED, GIFT_LINE_ITEM, or EXTERNAL​

Portion

Units of one Line Item that cost the same after Cart Discounts: one entry of the platform's discountedPricePerQuantity. Every Line Item has at least one; an EXTERNAL_TOTAL Line Item has exactly one, of every unit at its external unit price.
quantity​
Int​

How many of the Line Item's units are in this Portion.

unitPrice​

What one of these units costs after every discount applied to it.

discounts​
Array of AppliedDiscount​
The Cart Discounts and Direct Discounts that reduced these units, each amount per unit; empty when none did. Product Discounts are never listed here: see the Line Item's discountedPrice.

Price Totals

Money figures of a Cart, Order, or Quote, from the subtotal of the lines to the grand total that the shopper pays.

subtotal​
Every Line Item's unitPriceBeforeDiscount times its quantity, added up, with an EXTERNAL_TOTAL Line Item counted at its lineTotal: before any discount.
discountTotal​
What the applied discounts take off the goods, Product Discounts included and SHIPPING discounts excluded: the sum of the other entries in discounts; null when none. Each lineTotal already reflects it, except for TOTAL_PRICE discounts.
shipping​

What delivery costs, across every shipment, after any SHIPPING discount; null if no Shipping Method is selected.

tax​
Total tax amount, already included in grandTotal. null until tax is calculated, for example before a shipping address is set.
grandTotal​

Total amount the shopper pays, including tax once tax is calculated. Display this as the total, and charge this amount.

Before tax is calculated, this is the total of the lines and shipping after discounts.

grandTotalNet​
Total amount without tax. Equals grandTotal until tax is calculated. Use it in a summary that lists tax on its own line.

Applied Discount

A discount that was applied, and what it took off the thing it is attached to. A discount that matched but was discarded, by a Best Deal or within its Discount Group, is not listed.

id​
ID​
Opaque id of the discount behind this entry, the same in discounts, in every Portion and for the gift Line Item it added, and kept after the discount is deleted: the key to join them on. Clients never parse it.
source​

Where it came from; null once the discount behind it is deleted.

Can be PRODUCT_DISCOUNT, CART_DISCOUNT, DISCOUNT_CODE, or DIRECT_DISCOUNT​
target​

What it applies to; null for Product Discounts and gift discounts, which have no target, and once the discount behind it is deleted.

Can be LINE_ITEMS, BUY_AND_GET, DISCOUNT_BUNDLE, MULTIBUY_LINE_ITEMS, TOTAL_PRICE, or SHIPPING​
valueType​

How it reduces; null once the discount behind it is deleted.

Can be RELATIVE, ABSOLUTE, FIXED, GIFT_LINE_ITEM, or EXTERNAL​
code​
String​
The Discount Code the shopper entered, for removeDiscountCode; set only on DISCOUNT_CODE entries, and null on one once its Discount Code is deleted or no longer unlocks it.
key​
String​

The merchant's key for the discount, where one is set.

name​
String​

The discount's name in the session's locale: the Cart Discount's or Product Discount's, never the Discount Code's. Null where it has none for that locale, and always for a Direct Discount.

discountGroup​

The Discount Group this Cart Discount won within; null when it is in none.

amount​
What it took off, as a positive amount: per unit in a Portion; in a cart's, order's or quote's discounts, summed over everything it reduced.

Discount Source

Where a discount comes from.

PRODUCT_DISCOUNT
A Product Discount: a reduction of the product's price, present before the product reaches the cart.
CART_DISCOUNT
A Cart Discount that applies on its own to every cart it matches.
DISCOUNT_CODE
A Cart Discount unlocked by a Discount Code the shopper entered; the only kind `removeDiscountCode` removes. One code can unlock several Cart Discounts, each its own entry.
DIRECT_DISCOUNT
A Direct Discount: a Cart Discount a seller set on this one cart, order or quote.

Discount Target

What a Cart Discount applies to, named as the Merchant Center's "Apply this effect to" names it.

LINE_ITEMS
Whole Line Items matching the discount's conditions.
BUY_AND_GET
Units discounted once a set of trigger units is in the cart: buy these, get those. A pattern target with a trigger pattern in the platform.
DISCOUNT_BUNDLE
A set of units discounted together, only when the whole set is in the cart. A pattern target without a trigger pattern in the platform.
MULTIBUY_LINE_ITEMS
Some units of matching Line Items, once enough of them are in the cart.
TOTAL_PRICE
The cart's total price; applied after every other Cart Discount.
SHIPPING
The delivery charge, across every shipment; not in `discountTotal`.

Discount Value Type

How a discount reduces: the discount's value type. A display hint; the money is in amount.
RELATIVE
Percentage off the price.
ABSOLUTE
Fixed amount off the price.
FIXED
Fixed final price.
GIFT_LINE_ITEM
Free Product added to the Cart; Cart Discounts only.
EXTERNAL
A reduced price set by an external system; Product Discounts only.

Discount Group

A Discount Group: Cart Discounts of which only the one giving the lowest cart total applies.

key​
String​
name​
String​

The Discount Group's name in the session's locale; null where it has none for that locale.

Discount Combination

How the discounts on this cart or order were combined.

Can be STACKING, or BEST_DEAL​
bestDealWinner​
Which side won the Best Deal; null under STACKING.
Can be PRODUCT_DISCOUNTS, or CART_DISCOUNTS​

Discount Combination Mode

How Product Discounts and Cart Discounts combine, as the project is configured.

STACKING
Both apply: Cart Discounts reduce prices that Product Discounts have already reduced.
BEST_DEAL
Product Discounts and Cart Discounts compete, decided once for the whole cart, and the side giving the lower total applies. Gift, shipping and total-price discounts, and Direct Discounts that opt out of the comparison, apply whichever side wins.

Best Deal Winner

Which side won a Best Deal.

PRODUCT_DISCOUNTS
Product Discounts gave the lower total; the competing Cart Discounts were discarded.
CART_DISCOUNTS
Cart Discounts gave the lower or an equal total; Product Discounts were discarded on the Line Items those Cart Discounts reduced, and kept on the others.

Discount Code Info

Where a Discount Code entered on a cart or order stands.

code​
String​
The code as entered, in canonical form; the value removeDiscountCode takes.
name​
String​

The Discount Code's own name in the session's locale; null where it has none for that locale.

Can be NOT_ACTIVE, NOT_VALID, DOES_NOT_MATCH_CART, MATCHES_CART, MAX_APPLICATION_REACHED, APPLICATION_STOPPED_BY_PREVIOUS_DISCOUNT, or APPLICATION_STOPPED_BY_GROUP_BEST_DEAL​

Discount Code State

Where a Discount Code stands on a cart or order. Mirrors the platform's DiscountCodeState.

NOT_ACTIVE
The code, or every Cart Discount it unlocks, is not active.
NOT_VALID
The code's Cart Discounts are outside their validity dates.
DOES_NOT_MATCH_CART
The code is usable, but neither it nor its Cart Discounts match this cart.
MATCHES_CART
The code matches this cart. Under a Best Deal won by Product Discounts its Cart Discounts are still discarded: check `discountCombination.bestDealWinner`.
MAX_APPLICATION_REACHED
The code's overall or per-customer application limit is reached.
APPLICATION_STOPPED_BY_PREVIOUS_DISCOUNT
A Cart Discount applied earlier stopped further discounts, so this code's Cart Discounts did not apply.
APPLICATION_STOPPED_BY_GROUP_BEST_DEAL
Another Cart Discount in the same Discount Group gave a better deal.

Shipping Method

A delivery option for the Cart, as listed by shippingMethodsForCart. See Shipping Methods.
id​
ID​
Unique identifier of the Shipping Method. Pass it as shippingMethodId to selectShippingMethod.
key​
String​
User-defined unique identifier of the Shipping Method. null if the Shipping Method has no key.
name​
String​

Name of the Shipping Method, localized for the session where a localized name exists.

price​
Price of the Shipping Method for the Cart, with the free-shipping threshold of its rate applied, before shipping discounts. PriceTotals.shipping has the price after them.

Availability

Stock of a Product Variant, from the inventory of the session's supply channel where one is selected.
inStock​
Boolean​

Whether the Product Variant is in stock.

quantity​
Int​
Number of items of the Product Variant that are in stock. null if no quantity is tracked.

Payment Method Option

A payment method the shopper can choose at checkout.

key​
String​
User-defined unique identifier of the payment method. Pass it as PaymentInput.methodKey to pay with this method.
label​
String​

Name of the payment method in the session's locale. Empty string if the payment method has no name in that locale.

Cart Origin

Who created the Cart.

CUSTOMER
Cart was created by the Customer.
MERCHANT
Cart was created by a merchant on behalf of the Customer, for example by a sales representative.
QUOTE
Cart was created for a Quote during the quoting process.
RECURRING_ORDER
Cart was created as part of a Recurring Order.

Cart Action

Action the current viewer can take on a Cart. A value is listed only when the mutation behind it would run for this Cart, so the list can be narrower than what Viewer.permissions allows.
CHECKOUT
Place an Order with `checkout` or `placeOrder`. Offered to a signed-in Customer. In a Business Unit, the Associate also needs permission to create Orders from the Cart.
GUEST_CHECKOUT
Place an Order as a guest with `guestCheckout`. Offered to an anonymous session outside a Business Unit.
CLEAR
Remove all lines with `clearCart`. In a Business Unit, the Associate needs permission to update the Cart.
REQUEST_QUOTE
Request a Quote for the Cart with `requestQuote`. Offered in a Business Unit when the Cart has a shipping address and the Associate has permission to create Quote Requests.

Cart Mutation Result

Returned by every Cart mutation. Check userErrors first: if it is empty, the mutation succeeded.
cart​
Cart​
The Cart after the mutation. null if the mutation was refused before it reached a Cart, or if the session has no Cart yet and the call changed nothing, for example clearCart on a session without a Cart.
userErrors​
Array of UserError​

Reasons the mutation was refused. Empty if it succeeded.

Begin Payment Result

What the Browser SDK needs to start Checkout for the Cart. All fields except userErrors are null if userErrors isn't empty.
paymentTicket​
String​
id of the Checkout Session, to pass as sessionId to the Browser SDK. It's valid for one Cart and one payment. It isn't the session that you use to call this API.
projectKey​
String​
Key of the project, to pass as projectKey to the Browser SDK.
region​
String​
Region where the Checkout application is hosted, to pass as region to the Browser SDK, for example us-central1.gcp.
mode​

Selects the Browser SDK flow to mount for this Checkout Session.

Can be COMPLETE, or PAYMENT_ONLY​
payable​
Amount to pay, equal to PriceTotals.grandTotal when the Checkout Session was created. Display it next to the payment form. Checkout charges the total of the Cart at the time of authorization.
expiresAt​
Date and time (UTC) when the Checkout Session expires. To pay after that, call beginPayment again.
userErrors​
Array of UserError​

Reasons the payment couldn't start. Empty if it started.

CheckoutMode

Checkout mode of a Checkout Session, selected by the session's country and Store.
COMPLETE
Checkout collects the address, the Shipping Method, and the payment. Mount it with the Browser SDK `checkoutFlow`.
PAYMENT_ONLY
Checkout collects only the payment, for a Cart that already has an address and a Shipping Method. Mount it with the Browser SDK `paymentFlow`.

Input types

Add Cart Line Input

A Cart line to add, used by addCartLine and by each entry of addCartLines.
sku​
String​

SKU of the Product Variant to add.

quantity​
Int​
Number of items to add. Must be at least 1, otherwise the line is refused with INVALID_QUANTITY.
Default: 1​
distributionChannelIdOverride​
ID​
id of a distribution Channel to price this line with, instead of the distribution channel of the session. Use it to pick a channel-specific price for one line. If omitted, the line uses the channel selected for the session with PUT /{project}/main/session/distribution-channel.
The Channel must have the ProductDistribution role, be allowed by the Store of the Cart in a store-scoped session, and have a price for the SKU. Otherwise, the line is refused with INVALID_DISTRIBUTION_CHANNEL or PRICE_NOT_AVAILABLE.

Update Cart Line Quantity Input

A quantity change for one Cart line.

lineId​
ID​
id of the Cart line, from CartLine.id. LINE_NOT_FOUND if the line isn't in the Cart.
quantity​
Int​
New quantity of the line. 0 removes the line. A negative value is refused with INVALID_QUANTITY.

Update Cart Line Custom Fields Input

Custom Field values for one Cart line.

lineId​
ID​
id of the Cart line, from CartLine.id. LINE_NOT_FOUND if the line isn't in the Cart.

Remove Cart Line Input

Reference to the Cart line to remove.

lineId​
ID​
id of the Cart line, from CartLine.id. LINE_NOT_FOUND if the line isn't in the Cart.

Set Customer Email Input

Contact address for a guest Order.

email​
String​

Email address of the guest.

Select Shipping Method Input

The Shipping Method choice for the Cart.

shippingMethodId​
ID​
id of the Shipping Method, from shippingMethodsForCart.