# Common types

## GraphQL partial SDLs

This is a graphql reference page. In the llms.txt variant, those components link to the shared partial SDL key list instead of trying to resolve inline GraphQL reference content.

Fetch all available partial SDL keys first:

```text
GET https://docs.commercetools.com/apis/rest/content/by-id?id=ctp:gql-il:returnTypesList
```

Then fetch the one or more relevant partial SDL with a key from that list by calling the same endpoint with a schema ID:

```text
GET https://docs.commercetools.com/apis/rest/content/by-id?id=ctp:gql-il:schema:<key>
```

The response body is a JSON object keyed by the requested content ID. For example, the key-list request returns a `ctp:gql-il:returnTypesList` field and a schema request returns a `ctp:gql-il:schema:<key>` field.

**GraphQL types that many Core Subgraph queries and mutations share.**

### Scalars

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

#### DateTime

[fetch SDL for type DateTime](#graphql-partial-sdls).

#### Date

[fetch SDL for type Date](#graphql-partial-sdls).

#### Url

[fetch SDL for type Url](#graphql-partial-sdls).

#### JSON

[fetch SDL for type JSON](#graphql-partial-sdls).

### Monetary values

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

#### Money

[fetch SDL for type Money](#graphql-partial-sdls).

### Addresses

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

#### Address

[fetch SDL for type Address](#graphql-partial-sdls).

#### AddressInput

[fetch SDL for type AddressInput](#graphql-partial-sdls).

### Images

Images of Products and Cart lines.

#### Image

[fetch SDL for type Image](#graphql-partial-sdls).

### Pagination

Types for paging through and sorting lists.

#### PageInfo

[fetch SDL for type PageInfo](#graphql-partial-sdls).

#### SortDirection

[fetch SDL for type SortDirection](#graphql-partial-sdls).

### Session

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

#### Get session context

[fetch SDL for query viewer](#graphql-partial-sdls).

#### Viewer

[fetch SDL for type Viewer](#graphql-partial-sdls).

#### Store

[fetch SDL for type Store](#graphql-partial-sdls).

#### PresentmentOptions

[fetch SDL for type PresentmentOptions](#graphql-partial-sdls).

#### Audience

[fetch SDL for type Audience](#graphql-partial-sdls).

### Object identification

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

#### Get object by ID

[fetch SDL for query node](#graphql-partial-sdls).

#### Node

[fetch SDL for type Node](#graphql-partial-sdls).

### Errors

Errors that mutations return in their `userErrors` list.

#### UserError

[fetch SDL for type UserError](#graphql-partial-sdls).

#### UserErrorCode

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

## Related pages

- [Area overview page with navigation](/commerce-integration-layer.md)
- [Next page: Catalog](/commerce-integration-layer/experience/catalog.md)
- [Search documentation and API specs](/search.md)