GraphQL types that many Core Subgraph queries and mutations share.
Scalars
Scalars that represent dates, URLs, and arbitrary JSON values.
DateTime
2026-09-14T10:15:00.000Z."2026-09-14T10:15:00.000Z"
Date
YYYY-MM-DD, for example
1990-04-12."1990-04-12"
Url
https://images.example.com/oak-dining-chair.jpg."https://images.example.com/oak-dining-chair.jpg"
JSON
{"material": "oak"}. Used only by the raw field of
the generated <ProductType>Attributes types, whose shape follows the project's own
Product Type.{ "material": "oak" }
Monetary values
Monetary amounts, ready for display in the session's locale.
Money
formatted, and calculate with amount and
currencyCode, never with formatted.amountString | 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. |
currencyCodeString | Currency code compliant to ISO 4217, for
example GBP. |
formattedString | Amount formatted for the session's locale, with the standard number of fraction
digits of the currency, for example £89.00. |
{ "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.
id. Inputs that refer to a stored address take the id of a
SavedAddress, which is the editable address book entry.nameString | Name of the recipient. Contains the first and last name, or the company name if neither is set. |
line1String | Street name and street number. |
line2String | Further information on the street address. |
cityString | Name of the city. Empty string if not set. |
stateString | 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. |
regionString | Name of the region, for locales that use one. Not used to select a tax rate. |
postalCodeString | Postal code. Empty string if not set. |
countryString | Two-digit country code as per ISO 3166-1
alpha-2, for example GB. |
{
"name": "Jane Doe",
"line1": "1 Example Street",
"line2": null,
"city": "London",
"state": null,
"region": null,
"postalCode": "SW1A 1AA",
"country": "GB"
}
AddressInput
setShippingAddress or setBillingAddress, or to check out
with guestCheckout.nameString | Name of the recipient. |
line1String | Street name and street number. |
line2String | Further information on the street address. |
cityString | Name of the city. |
stateString | Name of the state, for example Colorado. Required for the address to be taxed at
a state rate. See Address.state. |
regionString | Name of the region, for locales that use one. |
postalCodeString | Postal code. |
countryString | 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. |
{
"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.
urlUrl | URL of the image in its original size. |
altString | Alternative text for the image, taken from the image label. null if the image
has no label. |
widthInt | Width of the original image in pixels. null if the dimensions are unknown. |
heightInt | Height of the original image in pixels. null if the dimensions are unknown. |
{
"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.
hasNextPageBoolean | Whether more items follow the current page. |
hasPreviousPageBoolean | Whether items precede the current page. |
startCursorString | Cursor of the first item on the page. null if the page is empty. |
endCursorString | Cursor of the last item on the page. Pass it as after to fetch the next page.
null if the page is empty. |
{
"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
Viewer of the current session. Read it again after you change the
Store, locale, or currency of the session.query GetViewer {
viewer {
store { key name }
locale
currency
audience
customer { id firstName }
checkoutMode
}
}
{
"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. |
localeString | Locale of the session, as an IETF language tag, for example en-GB. Localized
values in responses use this locale. |
countryString | Country of the session, as an ISO 3166-1 alpha-2 code, for example GB. |
currencyString | 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 beB2C, 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. |
permissionsArray of AssociatePermission | 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
Can be availableActions field is authoritative and can allow less. Empty if no Business
Unit is selected.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.COMPLETE, or PAYMENT_ONLY |
{
"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
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
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.keyString | User-defined unique identifier of the Store. |
nameString | Name of the Store in the session's locale. Contains the key if the Store has no
name in that locale. |
countriesArray 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. |
languagesArray of String | Languages the Store publishes content in, as IETF language tags, for example
en-GB. Empty if the Store doesn't restrict languages. |
{
"key": "uk-store",
"name": "UK Store",
"countries": ["GB"],
"languages": ["en-GB"]
}
PresentmentOptions
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.languagesArray of String | Languages of the project, as IETF language tags. |
countriesArray of String | Countries of the project, as ISO 3166-1 alpha-2 codes. |
currenciesArray 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. |
{
"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
node query.Get object by ID
id. Returns null if the identifier is unknown
or malformed, or the object isn't visible to the current session.| Arguments | |
|---|---|
idID | Global identifier of the object, as returned in its id field. |
query GetNode {
node(id: "AQAAAREQERAREUEQoRAREREQERAAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA") {
__typename
id
... on Product {
productName
price { formatted }
}
}
}
{
"data": {
"node": {
"__typename": "Product",
"id": "AQAAAREQERAREUEQoRAREREQERAAAAABAAAAAAABAAEAAAAAAAEAAAABAAEAAA",
"productName": "Oak Dining Chair",
"price": { "formatted": "£89.00" }
}
}
}
Node
node query can fetch again by its id.idID | Globally unique identifier of the object. Treat it as an opaque string and don't parse it. |
Errors
userErrors list.UserError
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 beOUT_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 |
messageString | 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. |
fieldString | 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. |
correlationIdString | 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. |
{
"code": "UNKNOWN_SHIPPING_METHOD",
"message": "That shipping method isn't available for this cart",
"field": "input.shippingMethodId",
"correlationId": "9b2f4c1e-6d3a-4f8b-a1c5-2e7d9f0b3a64"
}
UserErrorCode
UserError has one of the following codes, grouped here by area.Cart
| Code | Description | Returned by |
|---|---|---|
OUT_OF_STOCK | A line of the Cart is out of stock. | checkout, guestCheckout, placeOrder |
NOT_IN_ASSORTMENT | The Store doesn't sell this Product. | addCartLine, addCartLines |
PRICE_NOT_AVAILABLE | The 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_QUANTITY | The quantity isn't allowed, for example because it's zero or negative. | addCartLine, addCartLines, updateCartLineQuantity, addShoppingListLine, addToShoppingList, changeShoppingListLineQuantity, requestReturn |
LINE_NOT_FOUND | No line with this ID exists on the Cart, Shopping List, or Order. | updateCartLineQuantity, removeCartLine, changeShoppingListLineQuantity, removeShoppingListLine, requestReturn |
UNKNOWN_SKU | No published Product has this SKU. | addCartLine, addCartLines, addShoppingListLine, addToShoppingList |
INVALID_DISTRIBUTION_CHANNEL | The 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_FAILED | The 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_CART | The session has no Cart, or the Cart has no line items. | applyDiscountCode, selectShippingMethod, checkout, guestCheckout, placeOrder, beginPayment, requestQuote |
Discount codes
| Code | Description | Returned by |
|---|---|---|
INVALID_DISCOUNT_CODE | The discount code doesn't exist, isn't active, or isn't valid. | applyDiscountCode |
DISCOUNT_CODE_EXPIRED | The discount code is outside its validity period. | applyDiscountCode |
DISCOUNT_CODE_NOT_APPLICABLE | The 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_APPLIED | The discount code is already on the Cart. | applyDiscountCode |
Checkout
| Code | Description | Returned by |
|---|---|---|
UNKNOWN_SHIPPING_METHOD | The 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_METHOD | PaymentInput.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_REQUIRED | The Cart has no shipping address. Set the shipping address before you select a Shipping Method or request a Quote. | selectShippingMethod, requestQuote |
SHIPPING_COUNTRY_NOT_SUPPORTED | The 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_COUNTRY | The country isn't a valid two-letter ISO 3166-1 alpha-2 code in upper case, such as GB. | setShippingAddress, setBillingAddress, guestCheckout |
Orders
| Code | Description | Returned by |
|---|---|---|
ORDER_NOT_FOUND | No Order with this ID is visible to the current session. | reorder, requestReturn, cancelOrder, approveOrder, rejectOrder |
RETURN_NOT_ALLOWED | The Order can't be returned in its current state, or a quantity exceeds what can still be returned. | requestReturn |
ORDER_NOT_CANCELLABLE | The Order can't be cancelled in its current state, for example because it's complete or already cancelled. | cancelOrder |
CART_NOT_EMPTY | The active Cart already has items. To add the items to it, retry reorder with into: ACTIVE_CART, or clear the Cart first. | reorder |
Account
| Code | Description | Returned by |
|---|---|---|
ADDRESS_NOT_FOUND | No 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_PASSWORD | The current password is incorrect. | changePassword |
EMAIL_ALREADY_IN_USE | Another Customer already uses this email address. | register, changeEmail |
Shopping Lists
| Code | Description | Returned by |
|---|---|---|
LIST_NOT_FOUND | No Shopping List with this ID is visible to the current session. | updateShoppingList, addShoppingListLine, addToShoppingList, changeShoppingListLineQuantity, removeShoppingListLine, deleteShoppingList |
Business Units
| Code | Description | Returned by |
|---|---|---|
BUSINESS_UNIT_REQUIRED | The 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_EXISTS | A Business Unit with this key already exists. | createBusinessUnit |
CUSTOMER_NOT_FOUND | No Customer in the project has this email address. You can only add an Associate who already has a Customer account. | addAssociate |
ASSOCIATE_ROLE_NOT_FOUND | No Associate Role with this key exists in the project. field points to the entry. | addAssociate, updateAssociateRoles, createApprovalRule, updateApprovalRule |
Quotes
| Code | Description | Returned by |
|---|---|---|
QUOTE_NOT_FOUND | No 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_ACTIONABLE | The 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_EXPIRED | The 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_CODES | The 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_FOUND | No 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_ACTIONABLE | The state of the Quote Request doesn't allow the action. Only a SUBMITTED Quote Request can be cancelled. | cancelQuoteRequest |
Approvals
| Code | Description | Returned by |
|---|---|---|
APPROVAL_NOT_PENDING | The approval can't be approved or rejected, for example because it's no longer pending. | approveOrder, rejectOrder |
APPROVAL_REASON_REQUIRED | Rejecting an Order requires a reason, and none was given. | rejectOrder |
APPROVAL_RULE_NOT_FOUND | No Approval Rule with this ID is visible to the current session. | updateApprovalRule, setApprovalRuleActive |
CONDITION_NOT_SUPPORTED | The 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_REQUIRED | The 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
| Code | Description | Returned by |
|---|---|---|
INVALID_INPUT | The request contains an invalid value that no more specific code covers, for example a blank ID. message describes the problem. | Any mutation |
FORBIDDEN_ACTION | The viewer doesn't have the permission for this action. | Any mutation |
NOT_AUTHORIZED | The 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 |