Read and update the Cart of the current session, and start payment.
Queries
Get Cart
id or version. A guest
session has an anonymous Cart. null if the session has no Cart yet.query GetCart {
cart {
id
lineCount
lines { sku quantity }
totals {
subtotal { formatted }
grandTotal { formatted }
}
availableActions
}
}
{
"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
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.
query GetShippingMethodsForCart {
shippingMethodsForCart {
id
name
price { formatted }
}
}
{
"data": {
"shippingMethodsForCart": [
{
"id": "AQsAAdHT09Xh4k8eihuxsrO1tbcAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"name": "Standard delivery",
"price": { "formatted": "£4.95" }
},
{
"id": "AQsAAeHj4-Xx8kobixrBwsPFxccAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"name": "Express delivery",
"price": { "formatted": "£9.95" }
}
]
}
}
Get payment methods
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.
query GetPaymentMethods {
paymentMethods { key label }
}
{
"data": {
"paymentMethods": [
{ "key": "credit-card", "label": "Credit card" },
{ "key": "digital-wallet", "label": "Digital wallet" }
]
}
}
Mutations
Add Line Item to Cart
Adds a Product Variant to the Cart of the current session. Creates the Cart if the session has none.
userErrors, for example UNKNOWN_SKU,
NOT_IN_ASSORTMENT, PRICE_NOT_AVAILABLE, or OUT_OF_STOCK.| Arguments | |
|---|---|
input | Line to add. |
mutation AddCartLine {
addCartLine(input: {sku: "CUSHION-LINEN-GREY", quantity: 1}) {
cart {
id
lineCount
lines { sku quantity }
}
userErrors { code message field }
}
}
{
"data": {
"addCartLine": {
"cart": {
"id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"lineCount": 1,
"lines": [{ "sku": "CUSHION-LINEN-GREY", "quantity": 1 }]
},
"userErrors": []
}
}
}
Add Line Items to Cart
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 | |
|---|---|
inputsArray of AddCartLineInput | One entry for each line. A refusal names its entry in field, for example
inputs.2.sku or inputs.2.quantity. |
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 }
}
}
{
"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
Changes the quantity of a line in the Cart of the current session.
| Arguments | |
|---|---|
input | The line and its new quantity. |
mutation UpdateCartLineQuantity {
updateCartLineQuantity(
input: {lineId: "AQwDASIjIiMiIkIjoiMiIiIjIiMA8vLz8iIiQiKjIiMiIiIiIgEAAAABAAEAAA", quantity: 2}
) {
cart {
id
lines { sku quantity }
}
userErrors { code message field }
}
}
{
"data": {
"updateCartLineQuantity": {
"cart": {
"id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"lines": [{ "sku": "CHAIR-OAK-01", "quantity": 2 }]
},
"userErrors": []
}
}
}
Set Custom Fields on Line Item
addCartLine.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 | |
|---|---|
The line and the values to set. | |
# 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 }
}
}
{
"data": {
"updateCartLineCustomFields": {
"cart": {
"id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"lines": [
{
"sku": "CHAIR-OAK-01",
"custom": { "__typename": "GiftMessageCustom", "message": "Happy birthday!" }
}
]
},
"userErrors": []
}
}
}
Remove Line Item from Cart
Removes a line from the Cart of the current session.
| Arguments | |
|---|---|
input | The line to remove. |
mutation RemoveCartLine {
removeCartLine(
input: {lineId: "AQwDASIjIiMiIkIjoiMiIiIjIiMA8_Py8zMzQzOiMzIzMzMzMwEAAAABAAEAAA"}
) {
cart {
id
lineCount
lines { sku quantity }
}
userErrors { code message field }
}
}
{
"data": {
"removeCartLine": {
"cart": {
"id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"lineCount": 1,
"lines": [{ "sku": "CHAIR-OAK-01", "quantity": 2 }]
},
"userErrors": []
}
}
}
Empty Cart
Removes all lines from the Cart of the current session, including custom lines. Other data on the Cart, such as addresses, stays.
mutation ClearCart {
clearCart {
cart {
id
lineCount
lines { id }
}
userErrors { code message field }
}
}
{
"data": {
"clearCart": {
"cart": {
"id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"lineCount": 0,
"lines": []
},
"userErrors": []
}
}
}
Apply Discount Code
Applies a discount code to the Cart of the current session.
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 | |
|---|---|
codeString | Discount code to apply, as the shopper entered it. |
mutation ApplyDiscountCode {
applyDiscountCode(code: "WELCOME10") {
cart {
id
discounts { code name }
totals {
discountTotal { formatted }
}
}
userErrors { code message field }
}
}
{
"data": {
"applyDiscountCode": {
"cart": {
"id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"discounts": [
{ "code": "WELCOME10", "name": "Welcome 10% off" }
],
"totals": { "discountTotal": { "formatted": "£20.20" } }
},
"userErrors": []
}
}
}
Remove Discount Code
discountCodes, with every discounts entry it unlocked; a code not on the cart is a no-op, a blank one INVALID_INPUT.| Arguments | |
|---|---|
codeString | Discount code to remove, from AppliedDiscount.code. |
mutation RemoveDiscountCode {
removeDiscountCode(code: "WELCOME10") {
cart {
id
discounts { code name }
totals {
discountTotal { formatted }
}
}
userErrors { code message field }
}
}
{
"data": {
"removeDiscountCode": {
"cart": {
"id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"discounts": [],
"totals": { "discountTotal": null }
},
"userErrors": []
}
}
}
Set shipping address
Sets the shipping address of the Cart of the current session. Creates the Cart if the session has none.
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. |
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 }
}
}
{
"data": {
"setShippingAddress": {
"cart": {
"id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"shippingAddress": {
"name": "Jane Doe",
"city": "London",
"country": "GB"
}
},
"userErrors": []
}
}
}
Set billing address
Sets the billing address of the Cart of the current session. Creates the Cart if the session has none.
INVALID_COUNTRY if country isn't a valid ISO 3166-1 alpha-2
code.| Arguments | |
|---|---|
input | The address to bill. |
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 }
}
}
{
"data": {
"setBillingAddress": {
"cart": {
"id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"billingAddress": {
"name": "Jane Doe",
"city": "London",
"country": "GB"
}
},
"userErrors": []
}
}
}
Set Customer email
Sets the email address under which a guest places the Order, on the Cart of the current session.
FORBIDDEN_ACTION:
its Order uses the email address of the Customer account. See Set Customer
Email.| Arguments | |
|---|---|
input | The guest's email address. |
mutation SetCustomerEmail {
setCustomerEmail(input: {email: "jane.doe@example.com"}) {
cart { id customerEmail }
userErrors { code message field }
}
}
{
"data": {
"setCustomerEmail": {
"cart": {
"id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"customerEmail": "jane.doe@example.com"
},
"userErrors": []
}
}
}
Set purchase order number
Sets the purchase order number of the Cart of the current session.
| Arguments | |
|---|---|
purchaseOrderNumberString | If omitted, null, or an empty string, any existing number is removed. |
mutation SetPurchaseOrderNumber {
setPurchaseOrderNumber(purchaseOrderNumber: "PO-2026-0042") {
cart { id purchaseOrderNumber }
userErrors { code message field }
}
}
{
"data": {
"setPurchaseOrderNumber": {
"cart": {
"id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"purchaseOrderNumber": "PO-2026-0042"
},
"userErrors": []
}
}
}
Select Shipping Method for Cart
Sets the Shipping Method of the Cart of the current session.
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. |
mutation SelectShippingMethod {
selectShippingMethod(
input: {shippingMethodId: "AQsAAdHT09Xh4k8eihuxsrO1tbcAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA"}
) {
cart {
id
shippingMethod { key name }
}
userErrors { code message field }
}
}
{
"data": {
"selectShippingMethod": {
"cart": {
"id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"shippingMethod": {
"key": "standard",
"name": "Standard delivery"
}
},
"userErrors": []
}
}
}
Remove Shipping Method from Cart
Removes the Shipping Method from the Cart of the current session. Removing it from a Cart without one succeeds and changes nothing.
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.mutation ClearShippingMethod {
clearShippingMethod {
cart {
id
shippingMethod { key name }
totals {
shipping { formatted }
}
}
userErrors { code message field }
}
}
{
"data": {
"clearShippingMethod": {
"cart": {
"id": "AQEAASIjIiMiIkIjoiMiIiIjIiMAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"shippingMethod": null,
"totals": { "shipping": null }
},
"userErrors": []
}
}
}
Start payment with Checkout
EMPTY_CART if the Cart has no lines.mutation BeginPayment {
beginPayment {
paymentTicket
projectKey
region
mode
payable { amount currencyCode }
expiresAt
userErrors { code message field }
}
}
{
"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
A session has one active Cart for each combination of Store, currency, and country. The Cart is created when a mutation first changes it.
idID | Unique identifier of the Cart. |
lineCountInt | Number of lines in the Cart, including custom lines. |
linesArray of CartLine | Lines of the Cart, with Product Variant lines first and custom lines last. |
discountsArray 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. |
discountCodesArray 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. |
customerEmailString | Email address of the Customer that the Cart belongs to. A guest sets it with
setCustomerEmail. null if not set. |
purchaseOrderNumberString | Purchase order number that the buyer assigns to the Cart. Set it with
setPurchaseOrderNumber. null if not set. |
origin | Origin of the Cart. Can beCUSTOMER, MERCHANT, QUOTE, or RECURRING_ORDER |
shippingMethod | Shipping Method selected for the Cart. null if none is selected. |
availableActionsArray 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 beCHECKOUT, GUEST_CHECKOUT, CLEAR, or REQUEST_QUOTE |
_ctIdID | 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.
idID | Unique identifier of the Cart line. Pass it as lineId to change or remove the
line. |
skuString | SKU of the Product Variant. Empty string for a custom line. |
productNameString | Name of the Product in the session's locale. For a custom line, the name of the line. |
slugString | 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. |
quantityInt | Quantity of the Product Variant in the Cart. |
isGiftBoolean | 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 bePLATFORM, 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. |
portionsArray 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
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 | |
rejectedByBestDealBoolean | 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.
idID | Opaque id of the Product Discount, the same as the AppliedDiscount.id it has in a cart's discounts. Clients never parse it. |
keyString | The merchant's key for the Product Discount, where one is set. |
nameString | 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 beRELATIVE, ABSOLUTE, FIXED, GIFT_LINE_ITEM, or EXTERNAL |
Portion
discountedPricePerQuantity. Every Line Item has at least one; an EXTERNAL_TOTAL Line Item has exactly one, of every unit at its external unit price.quantityInt | 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. |
discountsArray 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.
idID | 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 bePRODUCT_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 beLINE_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 beRELATIVE, ABSOLUTE, FIXED, GIFT_LINE_ITEM, or EXTERNAL |
codeString | 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. |
keyString | The merchant's key for the discount, where one is set. |
nameString | 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
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.
keyString | |
nameString | 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.
mode | Can be STACKING, or BEST_DEAL |
bestDealWinner | Which side won the Best Deal; null under Can be STACKING.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.
codeString | The code as entered, in canonical form; the value removeDiscountCode takes. |
nameString | The Discount Code's own name in the session's locale; null where it has none for that locale. |
state | 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
shippingMethodsForCart. See Shipping
Methods.idID | Unique identifier of the Shipping Method. Pass it as shippingMethodId to
selectShippingMethod. |
keyString | User-defined unique identifier of the Shipping Method. null if the Shipping
Method has no key. |
nameString | 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
inStockBoolean | Whether the Product Variant is in stock. |
quantityInt | 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.
keyString | User-defined unique identifier of the payment method. Pass it as
PaymentInput.methodKey to pay with this method. |
labelString | 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
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
userErrors first: if it is empty, the
mutation succeeded.Begin Payment Result
userErrors are null if
userErrors isn't empty.paymentTicketString | 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. |
projectKeyString | Key of the project, to pass as projectKey to the Browser SDK. |
regionString | 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 beCOMPLETE, 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. |
userErrorsArray of UserError | Reasons the payment couldn't start. Empty if it started. |
CheckoutMode
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
addCartLine and by each entry of addCartLines.skuString | SKU of the Product Variant to add. |
quantityInt | Number of items to add. Must be at least Default: 1, otherwise the line is refused with
INVALID_QUANTITY.1 |
distributionChannelIdOverrideID | 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.
lineIdID | id of the Cart line, from CartLine.id. LINE_NOT_FOUND if the line isn't
in the Cart. |
quantityInt | 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.
lineIdID | 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.
lineIdID | 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.
emailString | Email address of the guest. |
Select Shipping Method Input
The Shipping Method choice for the Cart.
shippingMethodIdID | id of the Shipping Method, from shippingMethodsForCart. |