GraphQL types that many Core Subgraph queries and mutations share.

Scalars

Scalars that represent dates, URLs, and arbitrary JSON values.

DateTime

Date and time in ISO 8601 format, in UTC, for example 2026-09-14T10:15:00.000Z.
Example:json
"2026-09-14T10:15:00.000Z"

Date

Calendar date without a time, in ISO 8601 format YYYY-MM-DD, for example 1990-04-12.
Example:json
"1990-04-12"

Url

Absolute URL, for example https://images.example.com/oak-dining-chair.jpg.
Example:json
"https://images.example.com/oak-dining-chair.jpg"

JSON

Any JSON value, for example {"material": "oak"}. Used only by the raw field of the generated <ProductType>Attributes types, whose shape follows the project's own Product Type.
Example:json
{ "material": "oak" }

Monetary values

Monetary amounts, ready for display in the session's locale.

Money

Monetary amount. Display formatted, and calculate with amount and currencyCode, never with formatted.
amount​
String​
Decimal amount as a string, for example 89.00. Keeps the full precision of the stored amount, so a high-precision price can have more fraction digits than its currency.
currencyCode​
String​
formatted​
String​
Amount formatted for the session's locale, with the standard number of fraction digits of the currency, for example £89.00.
Example:json
{ "amount": "89.00", "currencyCode": "GBP", "formatted": "£89.00" }

Addresses

Postal addresses on Carts and Orders, and the input to set them.

Address

Address as stored on a Cart, an Order, or a Delivery.

An Address has no id. Inputs that refer to a stored address take the id of a SavedAddress, which is the editable address book entry.
name​
String​

Name of the recipient. Contains the first and last name, or the company name if neither is set.

line1​
String​

Street name and street number.

line2​
String​

Further information on the street address.

city​
String​

Name of the city. Empty string if not set.

state​
String​
Name of the state, for example Colorado. Tax rates are selected by state, not region, so in a country with state tax rates an address without state is taxed at the country rate.
region​
String​

Name of the region, for locales that use one. Not used to select a tax rate.

postalCode​
String​

Postal code. Empty string if not set.

country​
String​
Example:json
{
  "name": "Jane Doe",
  "line1": "1 Example Street",
  "line2": null,
  "city": "London",
  "state": null,
  "region": null,
  "postalCode": "SW1A 1AA",
  "country": "GB"
}

AddressInput

Address to set with setShippingAddress or setBillingAddress, or to check out with guestCheckout.
name​
String​

Name of the recipient.

line1​
String​

Street name and street number.

line2​
String​

Further information on the street address.

city​
String​

Name of the city.

state​
String​
Name of the state, for example Colorado. Required for the address to be taxed at a state rate. See Address.state.
region​
String​

Name of the region, for locales that use one.

postalCode​
String​

Postal code.

country​
String​
Two-digit country code as per ISO 3166-1 alpha-2, in upper case, for example GB. A value that isn't a valid code returns INVALID_COUNTRY. A country that the project has no tax rate for returns SHIPPING_COUNTRY_NOT_SUPPORTED.
Example:json
{
  "name": "Jane Doe",
  "line1": "1 Example Street",
  "city": "London",
  "postalCode": "SW1A 1AA",
  "country": "GB"
}

Images

Images of Products and Cart lines.

Image

Image of a Product, Product Variant, or Cart line.

url​
Url​

URL of the image in its original size.

alt​
String​
Alternative text for the image, taken from the image label. null if the image has no label.
width​
Int​
Width of the original image in pixels. null if the dimensions are unknown.
height​
Int​
Height of the original image in pixels. null if the dimensions are unknown.
Example:json
{
  "url": "https://images.example.com/oak-dining-chair.jpg",
  "alt": "Oak Dining Chair",
  "width": 1200,
  "height": 1200
}

Pagination

Types for paging through and sorting lists.

PageInfo

Paging state returned with each page of a cursor-paginated list.

hasNextPage​
Boolean​

Whether more items follow the current page.

hasPreviousPage​
Boolean​

Whether items precede the current page.

startCursor​
String​
Cursor of the first item on the page. null if the page is empty.
endCursor​
String​
Cursor of the last item on the page. Pass it as after to fetch the next page. null if the page is empty.
Example:json
{
  "hasNextPage": true,
  "hasPreviousPage": false,
  "startCursor": "AW9nZ3NkdDsw",
  "endCursor": "AW9nZ3NkdDsxOQ=="
}

SortDirection

Direction in which to sort a list.

ASC
Ascending order.
DESC
Descending order.

Session

The context of the current session, such as Store, locale, currency, and the signed-in Customer.

Get session context

QUERYviewer
Returns the Viewer of the current session. Read it again after you change the Store, locale, or currency of the session.
Output:Viewer
Request Example:graphql
query GetViewer {
  viewer {
    store { key name }
    locale
    currency
    audience
    customer { id firstName }
    checkoutMode
  }
}
Response Example:json
{
  "data": {
    "viewer": {
      "store": { "key": "uk-store", "name": "UK Store" },
      "locale": "en-GB",
      "currency": "GBP",
      "audience": "B2C",
      "customer": {
        "id": "AQMAAURFREVERERFpEVERERFREUAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
        "firstName": "Jane"
      },
      "checkoutMode": "COMPLETE"
    }
  }
}

Viewer

Context of the current session. Queries and mutations return data for this context.

store​
Store selected for the session. null if the session has no Store, which is a valid state.
locale​
String​
Locale of the session, as an IETF language tag, for example en-GB. Localized values in responses use this locale.
country​
String​
Country of the session, as an ISO 3166-1 alpha-2 code, for example GB.
currency​
String​
Default currency of the session, as an ISO 4217 code, for example GBP. Each Cart and Order has its own currency.
Selecting a Store doesn't change the currency. If the Store has no prices in this currency, Product prices are null and addCartLine returns PRICE_NOT_AVAILABLE. Change it with PATCH /{project}/main/session to any value of PresentmentOptions.currencies.
audience​

Audience of the session.

Can be B2C, or B2B​
customer​
Customer who is signed in. null for a guest session.
businessUnit​
Business Unit selected for the session. null for a B2C session.
permissions​

Permissions of the viewer in the selected Business Unit: all permissions of the Associate Roles the viewer holds there.

Use it to show or hide navigation and empty states. For a specific resource, its availableActions field is authoritative and can allow less. Empty if no Business Unit is selected.
Can be ACCEPT_MY_QUOTES, ACCEPT_OTHERS_QUOTES, ADD_CHILD_UNITS, CREATE_APPROVAL_RULES, CREATE_MY_CARTS, CREATE_MY_ORDERS_FROM_MY_CARTS, CREATE_MY_ORDERS_FROM_MY_QUOTES, CREATE_MY_PAYMENT_METHODS, CREATE_MY_QUOTE_REQUESTS_FROM_MY_CARTS, CREATE_MY_SHOPPING_LISTS, CREATE_ORDERS_FROM_OTHERS_CARTS, CREATE_ORDERS_FROM_OTHERS_QUOTES, CREATE_OTHERS_CARTS, CREATE_OTHERS_PAYMENT_METHODS, CREATE_OTHERS_SHOPPING_LISTS, CREATE_QUOTE_REQUESTS_FROM_OTHERS_CARTS, DECLINE_MY_QUOTES, DECLINE_OTHERS_QUOTES, DELETE_MY_CARTS, DELETE_MY_PAYMENT_METHODS, DELETE_MY_SHOPPING_LISTS, DELETE_OTHERS_CARTS, DELETE_OTHERS_PAYMENT_METHODS, DELETE_OTHERS_SHOPPING_LISTS, REASSIGN_MY_QUOTES, REASSIGN_OTHERS_QUOTES, RENEGOTIATE_MY_QUOTES, RENEGOTIATE_OTHERS_QUOTES, UPDATE_APPROVAL_FLOWS, UPDATE_APPROVAL_RULES, UPDATE_ASSOCIATES, UPDATE_BUSINESS_UNIT_DETAILS, UPDATE_MY_CARTS, UPDATE_MY_ORDERS, UPDATE_MY_PAYMENT_METHODS, UPDATE_MY_QUOTE_REQUESTS, UPDATE_MY_SHOPPING_LISTS, UPDATE_OTHERS_CARTS, UPDATE_OTHERS_ORDERS, UPDATE_OTHERS_PAYMENT_METHODS, UPDATE_OTHERS_QUOTE_REQUESTS, UPDATE_OTHERS_SHOPPING_LISTS, UPDATE_PARENT_UNIT, VIEW_MY_CARTS, VIEW_MY_ORDERS, VIEW_MY_PAYMENT_METHODS, VIEW_MY_QUOTE_REQUESTS, VIEW_MY_QUOTES, VIEW_MY_SHOPPING_LISTS, VIEW_OTHERS_CARTS, VIEW_OTHERS_ORDERS, VIEW_OTHERS_PAYMENT_METHODS, VIEW_OTHERS_QUOTE_REQUESTS, VIEW_OTHERS_QUOTES, VIEW_OTHERS_SHOPPING_LISTS, or UNKNOWN​
presentmentOptions​

Languages, countries, and currencies the session can switch to.

checkoutMode​
Checkout mode for the session's country and Store. beginPayment returns the same mode.
null if no Checkout configuration of the project matches the session. In that case, beginPayment can't start a payment.
Can be COMPLETE, or PAYMENT_ONLY​
Example:json
{
  "store": {
    "key": "uk-store",
    "name": "UK Store",
    "countries": ["GB"],
    "languages": ["en-GB"]
  },
  "locale": "en-GB",
  "country": "GB",
  "currency": "GBP",
  "audience": "B2C",
  "customer": null,
  "businessUnit": null,
  "permissions": [],
  "presentmentOptions": {
    "languages": ["en-GB", "de-DE"],
    "countries": ["GB", "DE"],
    "currencies": ["GBP", "EUR"]
  },
  "checkoutMode": "COMPLETE"
}

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`.

Store

Store that scopes a session's catalog, channels, and Cart.
Select a Store with PUT /{project}/main/session/scope, in a guest, signed-in, or Business Unit session. A Business Unit session can only select a Store of its Business Unit. Selecting a Store aligns the session's country and locale with what the Store serves, sets the session's distribution and supply channels from the Store, and limits the catalog to the Store's assortment. The Cart is created in the Store, so adding a Product that the Store doesn't sell returns NOT_IN_ASSORTMENT. A Store has no currency of its own, so the session currency stays unchanged.
key​
String​

User-defined unique identifier of the Store.

name​
String​
Name of the Store in the session's locale. Contains the key if the Store has no name in that locale.
countries​
Array of String​

Countries the Store serves, as ISO 3166-1 alpha-2 codes. Empty if the Store doesn't restrict countries. When a Store is selected, the session's country is aligned with this list.

languages​
Array of String​
Languages the Store publishes content in, as IETF language tags, for example en-GB. Empty if the Store doesn't restrict languages.
Example:json
{
  "key": "uk-store",
  "name": "UK Store",
  "countries": ["GB"],
  "languages": ["en-GB"]
}

PresentmentOptions

Values for a language, country, or currency selector. The values the session currently uses are in Viewer.locale and Viewer.currency. Change them with PATCH /{project}/main/session, which issues a new session token and accepts only values from these lists.
languages​
Array of String​

Languages of the project, as IETF language tags.

countries​
Array of String​

Countries of the project, as ISO 3166-1 alpha-2 codes.

currencies​
Array of String​
Currencies of the project, as ISO 4217 codes. Not limited to the currencies that the active Store has prices in. See Viewer.currency for what happens without a price.
Example:json
{
  "languages": ["en-GB", "de-DE"],
  "countries": ["GB", "DE"],
  "currencies": ["GBP", "EUR"]
}

Audience

Business model that a session serves.

B2C
Business-to-consumer. The session has no Business Unit selected.
B2B
Business-to-business. The session has a Business Unit selected.

Object identification

Objects with a global ID, which you can fetch again with the node query.

Get object by ID

QUERYnode
Fetches an object again by its id. Returns null if the identifier is unknown or malformed, or the object isn't visible to the current session.
Arguments
id​
ID​
Global identifier of the object, as returned in its id field.
Output:Node
Request Example:graphql
query GetNode {
  node(id: "AQAAAREQERAREUEQoRAREREQERAAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA") {
    __typename
    id
    ... on Product {
      productName
      price { formatted }
    }
  }
}
Response Example:json
{
  "data": {
    "node": {
      "__typename": "Product",
      "id": "AQAAAREQERAREUEQoRAREREQERAAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
      "productName": "Oak Dining Chair",
      "price": { "formatted": "£89.00" }
    }
  }
}

Node

Object that the node query can fetch again by its id.
id​
ID​

Globally unique identifier of the object. Treat it as an opaque string and don't parse it.

Errors

Errors that mutations return in their userErrors list.

UserError

Refusal of a mutation that the caller can correct or act on. Check the userErrors list of every mutation result before you read its resource field.

Top-level GraphQL errors are used for transport errors and unexpected failures.

code​

Kind of error. Handle each case in your client by this code.

Can be OUT_OF_STOCK, NOT_IN_ASSORTMENT, PRICE_NOT_AVAILABLE, INVALID_QUANTITY, LINE_NOT_FOUND, UNKNOWN_SKU, EMPTY_CART, UNKNOWN_SHIPPING_METHOD, UNKNOWN_PAYMENT_METHOD, SHIPPING_ADDRESS_REQUIRED, SHIPPING_COUNTRY_NOT_SUPPORTED, INVALID_COUNTRY, INVALID_DISTRIBUTION_CHANNEL, LINE_ITEM_HOOK_FAILED, INVALID_INPUT, FORBIDDEN_ACTION, NOT_AUTHORIZED, BUSINESS_UNIT_REQUIRED, INVALID_DISCOUNT_CODE, DISCOUNT_CODE_EXPIRED, DISCOUNT_CODE_NOT_APPLICABLE, DISCOUNT_CODE_ALREADY_APPLIED, ORDER_NOT_FOUND, RETURN_NOT_ALLOWED, ORDER_NOT_CANCELLABLE, CART_NOT_EMPTY, QUOTE_NOT_FOUND, QUOTE_NOT_ACTIONABLE, QUOTE_EXPIRED, QUOTE_CART_HAS_DISCOUNT_CODES, QUOTE_REQUEST_NOT_FOUND, QUOTE_REQUEST_NOT_ACTIONABLE, APPROVAL_NOT_PENDING, APPROVAL_REASON_REQUIRED, APPROVAL_RULE_NOT_FOUND, ASSOCIATE_ROLE_NOT_FOUND, CONDITION_NOT_SUPPORTED, APPROVER_TIERS_REQUIRED, LIST_NOT_FOUND, CUSTOMER_NOT_FOUND, BUSINESS_UNIT_KEY_EXISTS, ADDRESS_NOT_FOUND, INVALID_CURRENT_PASSWORD, or EMAIL_ALREADY_IN_USE​
message​
String​
Description of the error that you can display or log. To localize the error, map from code instead. Don't parse the message: platform identifiers and permission names are removed from it, and its structure isn't stable.
field​
String​
Dotted path to the input value that caused the error. The path starts with the argument name of the mutation, followed by nested input fields and list indices. For example, input.postalCode on setShippingAddress, inputs.2.sku on addCartLines, or orderId on cancelOrder.
null if no input value is at fault, for example for a missing permission, the state of the resource, or a missing precondition such as SHIPPING_ADDRESS_REQUIRED.
correlationId​
String​

Correlation ID of the request that returned the error. Include it in a support request to identify the request across all services it reached.

If you send an X-Correlation-ID header, this is usually the value you sent. Otherwise, it's the ID generated for the request. All entries of one userErrors list have the same value. null for an error raised outside a request.
Example:json
{
  "code": "UNKNOWN_SHIPPING_METHOD",
  "message": "That shipping method isn't available for this cart",
  "field": "input.shippingMethodId",
  "correlationId": "9b2f4c1e-6d3a-4f8b-a1c5-2e7d9f0b3a64"
}

UserErrorCode

Each UserError has one of the following codes, grouped here by area.

Cart

CodeDescriptionReturned by
OUT_OF_STOCKA line of the Cart is out of stock.checkout, guestCheckout, placeOrder
NOT_IN_ASSORTMENTThe Store doesn't sell this Product.addCartLine, addCartLines
PRICE_NOT_AVAILABLEThe Store sells this Product but has no price for it in the session's currency, country, or distribution channel. Another currency or distribution channel may make it available.addCartLine, addCartLines
INVALID_QUANTITYThe quantity isn't allowed, for example because it's zero or negative.addCartLine, addCartLines, updateCartLineQuantity, addShoppingListLine, addToShoppingList, changeShoppingListLineQuantity, requestReturn
LINE_NOT_FOUNDNo line with this ID exists on the Cart, Shopping List, or Order.updateCartLineQuantity, removeCartLine, changeShoppingListLineQuantity, removeShoppingListLine, requestReturn
UNKNOWN_SKUNo published Product has this SKU.addCartLine, addCartLines, addShoppingListLine, addToShoppingList
INVALID_DISTRIBUTION_CHANNELThe distribution channel given for the line can't select a price for it, because the channel doesn't exist, the ID isn't valid, or the channel doesn't have the ProductDistribution role. See AddCartLineInput.distributionChannelIdOverride.addCartLine, addCartLines
LINE_ITEM_HOOK_FAILEDThe project's line item extension returned an error for this line, so nothing was added to the Cart. The message doesn't carry the extension's own error.addCartLine, addCartLines
EMPTY_CARTThe session has no Cart, or the Cart has no line items.applyDiscountCode, selectShippingMethod, checkout, guestCheckout, placeOrder, beginPayment, requestQuote

Discount codes

CodeDescriptionReturned by
INVALID_DISCOUNT_CODEThe discount code doesn't exist, isn't active, or isn't valid.applyDiscountCode
DISCOUNT_CODE_EXPIREDThe discount code is outside its validity period.applyDiscountCode
DISCOUNT_CODE_NOT_APPLICABLEThe discount code exists but can't be applied to this Cart, for example because it doesn't match the Cart or has reached its maximum number of applications.applyDiscountCode
DISCOUNT_CODE_ALREADY_APPLIEDThe discount code is already on the Cart.applyDiscountCode

Checkout

CodeDescriptionReturned by
UNKNOWN_SHIPPING_METHODThe Shipping Method doesn't exist, the ID isn't valid, or the Shipping Method has no rate for the Cart's shipping address.selectShippingMethod, checkout, guestCheckout, placeOrder
UNKNOWN_PAYMENT_METHODPaymentInput.methodKey names a payment method that the project doesn't accept. The accepted methods can change during checkout, so read paymentMethods again and retry.checkout, guestCheckout, placeOrder
SHIPPING_ADDRESS_REQUIREDThe Cart has no shipping address. Set the shipping address before you select a Shipping Method or request a Quote.selectShippingMethod, requestQuote
SHIPPING_COUNTRY_NOT_SUPPORTEDThe project has no tax rate for the country of the address, so the address can't be used on a Cart. addAddress and updateAddress return this code for a country that isn't a valid country code.setShippingAddress, checkout, guestCheckout, placeOrder, addAddress, updateAddress
INVALID_COUNTRYThe country isn't a valid two-letter ISO 3166-1 alpha-2 code in upper case, such as GB.setShippingAddress, setBillingAddress, guestCheckout

Orders

CodeDescriptionReturned by
ORDER_NOT_FOUNDNo Order with this ID is visible to the current session.reorder, requestReturn, cancelOrder, approveOrder, rejectOrder
RETURN_NOT_ALLOWEDThe Order can't be returned in its current state, or a quantity exceeds what can still be returned.requestReturn
ORDER_NOT_CANCELLABLEThe Order can't be cancelled in its current state, for example because it's complete or already cancelled.cancelOrder
CART_NOT_EMPTYThe active Cart already has items. To add the items to it, retry reorder with into: ACTIVE_CART, or clear the Cart first.reorder

Account

CodeDescriptionReturned by
ADDRESS_NOT_FOUNDNo saved address with this ID exists, or no ID was given and the Cart has no shipping address to use.updateAddress, removeAddress, setDefaultAddress, updateBusinessUnitAddress, removeBusinessUnitAddress, checkout, placeOrder
INVALID_CURRENT_PASSWORDThe current password is incorrect.changePassword
EMAIL_ALREADY_IN_USEAnother Customer already uses this email address.register, changeEmail

Shopping Lists

CodeDescriptionReturned by
LIST_NOT_FOUNDNo Shopping List with this ID is visible to the current session.updateShoppingList, addShoppingListLine, addToShoppingList, changeShoppingListLineQuantity, removeShoppingListLine, deleteShoppingList

Business Units

CodeDescriptionReturned by
BUSINESS_UNIT_REQUIREDThe operation requires a selected Business Unit and Store, and the session is missing one of them.Any mutation scoped to a Business Unit, for example placeOrder and requestQuote
BUSINESS_UNIT_KEY_EXISTSA Business Unit with this key already exists.createBusinessUnit
CUSTOMER_NOT_FOUNDNo Customer in the project has this email address. You can only add an Associate who already has a Customer account.addAssociate
ASSOCIATE_ROLE_NOT_FOUNDNo Associate Role with this key exists in the project. field points to the entry.addAssociate, updateAssociateRoles, createApprovalRule, updateApprovalRule

Quotes

CodeDescriptionReturned by
QUOTE_NOT_FOUNDNo Quote with this ID is visible to the current session, because it doesn't exist or belongs to a Business Unit that the session hasn't selected.acceptQuote, declineQuote, renegotiateQuote
QUOTE_NOT_ACTIONABLEThe state of the Quote doesn't allow the action. Only a PENDING Quote can be accepted, declined, or renegotiated. A missing permission returns FORBIDDEN_ACTION, and an expired Quote returns QUOTE_EXPIRED.acceptQuote, declineQuote, renegotiateQuote
QUOTE_EXPIREDThe Quote is past its expiresAt, so it can no longer be accepted, declined, or renegotiated. Its quoteState is still PENDING, and its availableActions is empty.acceptQuote, declineQuote, renegotiateQuote
QUOTE_CART_HAS_DISCOUNT_CODESThe Cart has discount codes, and a Quote can't be requested for a Cart with discount codes. Remove the codes and try again. The Cart is unchanged.requestQuote
QUOTE_REQUEST_NOT_FOUNDNo Quote Request with this ID is visible to the current session, because it doesn't exist or belongs to a Business Unit that the session hasn't selected.cancelQuoteRequest
QUOTE_REQUEST_NOT_ACTIONABLEThe state of the Quote Request doesn't allow the action. Only a SUBMITTED Quote Request can be cancelled.cancelQuoteRequest

Approvals

CodeDescriptionReturned by
APPROVAL_NOT_PENDINGThe approval can't be approved or rejected, for example because it's no longer pending.approveOrder, rejectOrder
APPROVAL_REASON_REQUIREDRejecting an Order requires a reason, and none was given.rejectOrder
APPROVAL_RULE_NOT_FOUNDNo Approval Rule with this ID is visible to the current session.updateApprovalRule, setApprovalRuleActive
CONDITION_NOT_SUPPORTEDThe approval condition can't be expressed with ApprovalConditionInput, the conditions list is empty, or you replaced the conditions of an Approval Rule whose conditionsFullyTyped is false. field names the condition, message says what is supported, and the stored Approval Rule is unchanged.createApprovalRule, updateApprovalRule
APPROVER_TIERS_REQUIREDThe Approval Rule has no approver tiers, a tier without approver groups, or a group without Associate Roles. Such a rule would block every matching Order, because nobody could approve it.createApprovalRule, updateApprovalRule

General

CodeDescriptionReturned by
INVALID_INPUTThe request contains an invalid value that no more specific code covers, for example a blank ID. message describes the problem.Any mutation
FORBIDDEN_ACTIONThe viewer doesn't have the permission for this action.Any mutation
NOT_AUTHORIZEDThe operation requires a signed-in Customer, and the session has none. createBusinessUnit also returns it when the session lacks permission in the parent Business Unit, with field set to input.parentUnitKey.Any mutation that requires a signed-in Customer