> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/adobe-commerce-magento/integration/headless-integration.md).

# Headless Integration

The ESW extension supports GraphQL-based checkout flows for headless Adobe Commerce storefronts.

Use it to request the ESW checkout URL and to return country-specific pricing through standard Adobe Commerce GraphQL requests.

### Set the shopper country for API requests

By default, the extension uses the Adobe Commerce default country from **Stores > Configuration > General > Country Options**.

If the same store supports multiple countries, override the target country in the request header:

`Esw-Country: JP`

Use an ISO 3166-1 alpha-2 country code in the header value.

When this header is present, ESW pricing logic is applied for that country in the GraphQL response.

### Checkout URL query

Use this query to get the ESW redirect checkout URL for a cart:

```graphql
query getEShopWorldCheckout($cartId: String!) {
  eShopWorldCheckout(cartId: $cartId)
}
```

#### Parameters

* `cartId` required. The masked Adobe Commerce cart ID.

#### Response

* `data.eShopWorldCheckout`. The ESW checkout URL for the cart.

### Shipping method behavior

Matching ESW shipping methods are not returned directly through GraphQL for display in the storefront.

Applicable shipping methods are added during pre-order processing and shown on the ESW checkout page.

### Product restriction behavior

[Global Product Restriction](/adobe-commerce-magento/additional-features/global-product-restriction.md) is also supported in headless GraphQL flows.

The same restriction logic applies in these cases:

#### Add a restricted product to cart

If a shopper tries to add a restricted product through GraphQL, the request returns a restriction message and the product is not added.

#### Query a cart that already contains a restricted product

If a product becomes restricted after it was added to the cart, later GraphQL cart queries return a message showing that the cart contains a restricted product.

#### Request checkout URL for a restricted cart

If a shopper requests the ESW checkout URL while the cart contains a restricted product, the restriction message is returned and checkout is blocked.

### Expected result

After setup is complete:

* headless storefronts can request the ESW checkout URL through GraphQL
* GraphQL pricing can be resolved for a specific country with the `Esw-Country` header
* product restriction behavior stays consistent across storefront and headless flows


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developer.esw.com/adobe-commerce-magento/integration/headless-integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.