> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core-api-reference/2026-05/readme.md).

# Introduction

A detailed reference for all Commerce Layer core API resources — version 2026-05

Commerce Layer is a flexible commerce API built for developers. This is the complete resource reference for API version `2026-05`, which brings a redesigned payment foundation.

{% hint style="info" %}
This space covers the latest `2026-05` API version exclusively. The previous `2017-08` version is still available, but it's deprecated and will eventually be removed — see the related [API reference](https://docs.commercelayer.io/core-api-reference/) if you're still integrating against it.
{% endhint %}

## What's in this reference <a href="#reference-structure" id="reference-structure"></a>

For each resource you'll find:

* The **object** page — a complete list of fields, attributes, and relationships returned by the API.
* One page for each supported **CRUD** operation — with request arguments, required and optional fields, and a `curl` example showing both the request and response.

## Differences from the previous version <a href="#previous-version-diff" id="previous-version-diff"></a>

The `2026-05` API introduces a redesigned payment infrastructure changing the payment model and some response conventions. The main differences from the previous version are:

* Payment is driven by [payment sessions](/core-api-reference/2026-05/payment_sessions.md) rather than [payment options](/core-api-reference/payment_options.md). An order can have **multiple sessions**, each covering a portion of the order total (split payment).
* All gateway configurations are modeled as typed [payment settings](/core-api-reference/2026-05/payment_settings.md) resources (one for [Adyen](/core-api-reference/2026-05/payment_setting_adyens.md), [Braintree](/core-api-reference/2026-05/payment_setting_braintrees.md), [Checkout.com](/core-api-reference/2026-05/payment_setting_checkout_coms.md), [PayPal](/core-api-reference/2026-05/payment_setting_paypals.md), [Stripe](/core-api-reference/2026-05/payment_setting_stripes.md), [gift cards](/core-api-reference/2026-05/payment_setting_gift_cards.md), [manual gateways](/core-api-reference/2026-05/payment_setting_manuals.md), [external gateways](/core-api-reference/2026-05/payment_setting_externals.md)).
* **Vaulted instruments** are supported via [payment wallets](/core-api-reference/2026-05/payment_wallets.md), enabling faster checkout with stored payment methods.
* A [session](/core-api-reference/2026-05/payment_sessions.md#payment-instrument)'s payment instrument attribute summarizes what the customer actually paid with (e.g. card brand and last digits, or the PayPal account) directly in the response, without needing to query the payment provider.
* [Payment rules](/core-api-reference/2026-05/payment_rules.md#payment-setting-rules) allow conditional availability of payment settings per market.
* [Returns](/core-api-reference/2026-05/returns.md#refunding-from-a-return) are refunded by creating [payment refunds](/core-api-reference/2026-05/payment_refunds.md#return-initiated-refunds) against the order's payment sessions, rather than through the previous version's refund flow.
* [Order subscriptions](/core-api-reference/2026-05/order_subscriptions.md#payment-sessions) capture the payment wallet or setting derived from the source order's payment session — on each automatic run, [recurring order copies](/core-api-reference/2026-05/recurring_order_copies.md#payment-sessions) use it to create and authorize a new payment session on the target order. Manually triggering subscription generation via [order copies](/core-api-reference/2026-05/order_copies.md#payment-sessions) instead is only supported for orders still on the previous version's payment flow.
* [Order editing](/core-api-reference/2026-05/orders.md#order-editing) does not automatically adjust payment — any authorization, void, or refund required after an edit must be created manually against the order's payment sessions.
* The gateway options for [payment sessions](/core-api-reference/2026-05/payment_sessions.md#gateway-options), [payment transactions](/core-api-reference/2026-05/payment_transactions.md#gateway-options), [payment links](/core-api-reference/2026-05/payment_links.md#gateway-options), and [payment wallets](/core-api-reference/2026-05/payment_wallets.md#gateway-options) let you forward gateway-specific parameters straight into the payment gateway request, overriding fields the API would otherwise compute — the reconciliation reference and the amount can never be overridden this way, regardless of what's passed. It can only be set using integration API credentials — sales channels cannot supply it.
* **Meta information** provided in the response JSON has changed — resource-level meta now contains only the API version that was active when this resource was created, while all other meta information has been moved into the document-level `meta` object.

{% hint style="info" %}
Requests that omit the API version segment path in the endpoint URL now resolve to the **latest available API version** (currently `2026-05`). Since the latest version is always backward-compatible with the most recent previous version's behavior (currently `2017-08`), this is not a breaking change and no action is needed (unless you're still integrating against an even older version).
{% endhint %}

You can find below a full breakdown of the changes by resource:

<details>

<summary><strong>What's new</strong></summary>

The following resources are exclusive to this version and not available in previous versions:

<table><thead><tr><th width="260">Resource</th><th>Description</th><th width="150">API reference</th></tr></thead><tbody><tr><td><strong><code>payment_sessions</code></strong></td><td>The central payment intent object — tracks the full authorize → capture → refund lifecycle.</td><td><a href="/core-api-reference/2026-05/payment_sessions.md">Learn more</a></td></tr><tr><td><strong><code>payment_settings</code></strong></td><td>The read-only polymorphic base for gateway configurations — determines how payment sessions are processed.</td><td><a href="/core-api-reference/2026-05/payment_settings.md">Learn more</a></td></tr><tr><td><strong><code>payment_transactions</code></strong></td><td>The polymorphic base for every payment action — models each authorization, capture, void, and refund.</td><td><a href="/core-api-reference/2026-05/payment_transactions.md">Learn more</a></td></tr><tr><td><strong><code>payment_authorizations</code></strong></td><td>The first transaction in a session's lifecycle — reserves funds on the customer's payment instrument.</td><td><a href="/core-api-reference/2026-05/payment_authorizations.md">Learn more</a></td></tr><tr><td><strong><code>payment_captures</code></strong></td><td>A transaction against an authorization — collects previously reserved funds, in full or in part.</td><td><a href="/core-api-reference/2026-05/payment_captures.md">Learn more</a></td></tr><tr><td><strong><code>payment_voids</code></strong></td><td>A transaction against an authorization — cancels it and releases the reserved funds before capture.</td><td><a href="/core-api-reference/2026-05/payment_voids.md">Learn more</a></td></tr><tr><td><strong><code>payment_refunds</code></strong></td><td>A transaction against a capture — returns previously captured funds to the customer, in full or in part.</td><td><a href="/core-api-reference/2026-05/payment_refunds.md">Learn more</a></td></tr><tr><td><strong><code>payment_links</code></strong></td><td>A shareable payment URL for collecting a payment outside checkout — optionally tied to an order, or created as a standalone request.</td><td><a href="/core-api-reference/2026-05/payment_links.md">Learn more</a></td></tr><tr><td><strong><code>payment_wallets</code></strong></td><td>A vaulted payment instrument — enables faster checkout by reusing saved payment details across sessions.</td><td><a href="/core-api-reference/2026-05/payment_wallets.md">Learn more</a></td></tr><tr><td><strong><code>payment_rules</code></strong></td><td>Conditional logic scoped to a market — controls payment coverage requirements and available payment settings.</td><td><a href="/core-api-reference/2026-05/payment_rules.md">Learn more</a></td></tr><tr><td><strong><code>payment_setting_adyens</code></strong></td><td>The Adyen-specific payment setting — holds the credentials needed to process payments through Adyen.</td><td><a href="/core-api-reference/2026-05/payment_setting_adyens.md">Learn more</a></td></tr><tr><td><strong><code>payment_setting_braintrees</code></strong></td><td>The Braintree-specific payment setting — holds the credentials needed to process payments through Braintree.</td><td><a href="/core-api-reference/2026-05/payment_setting_braintrees.md">Learn more</a></td></tr><tr><td><strong><code>payment_setting_checkout_coms</code></strong></td><td>The Checkout.com-specific payment setting — holds the credentials needed to process payments through Checkout.com.</td><td><a href="/core-api-reference/2026-05/payment_setting_checkout_coms.md">Learn more</a></td></tr><tr><td><strong><code>payment_setting_externals</code></strong></td><td>The custom gateway payment setting — integrates any external provider through a webhook-based contract.</td><td><a href="/core-api-reference/2026-05/payment_setting_externals.md">Learn more</a></td></tr><tr><td><strong><code>payment_setting_gift_cards</code></strong></td><td>The gift card payment setting — redeems a code and deducts the payment amount from its balance.</td><td><a href="/core-api-reference/2026-05/payment_setting_gift_cards.md">Learn more</a></td></tr><tr><td><strong><code>payment_setting_manuals</code></strong></td><td>The manual payment setting — processes out-of-band methods like wire transfers with no external gateway calls.</td><td><a href="/core-api-reference/2026-05/payment_setting_manuals.md">Learn more</a></td></tr><tr><td><strong><code>payment_setting_paypals</code></strong></td><td>The PayPal-specific payment setting — holds the credentials needed to process payments through PayPal.</td><td><a href="/core-api-reference/2026-05/payment_setting_paypals.md">Learn more</a></td></tr><tr><td><strong><code>payment_setting_stripes</code></strong></td><td>The Stripe-specific payment setting — holds the credentials needed to process payments through Stripe.</td><td><a href="/core-api-reference/2026-05/payment_setting_stripes.md">Learn more</a></td></tr></tbody></table>

</details>

<details>

<summary><strong>What's deprecated</strong></summary>

The following resources are still available when requesting this version, but they are deprecated — calls to them keep working, though every response carries a warning, and they will eventually be removed in a future version:

<table><thead><tr><th width="260">Resource</th><th>Description</th><th width="150">API reference</th></tr></thead><tbody><tr><td><strong><code>payment_gateways</code></strong></td><td>The polymorphic base for gateway configurations — used to represent whichever payment provider was configured for a market.</td><td><a href="/core-api-reference/payment_gateways.md">Learn more</a></td></tr><tr><td><strong><code>payment_methods</code></strong></td><td>The payment method offered in a market or store — used to price and list the available ways to pay before order placement.</td><td><a href="/core-api-reference/payment_methods.md">Learn more</a></td></tr><tr><td><strong><code>payment_options</code></strong></td><td>Extra data attached to an order's payment — used to pass custom information through to the payment gateway at payment creation.</td><td><a href="/core-api-reference/payment_options.md">Learn more</a></td></tr><tr><td><strong><code>transactions</code></strong></td><td>The polymorphic base for every payment action — used to track authorization, capture, void, and refund events across an order's lifecycle.</td><td><a href="/core-api-reference/transactions.md">Learn more</a></td></tr><tr><td><strong><code>authorizations</code></strong></td><td>The first transaction in an order's payment flow — used to reserve funds and move the order to `authorized` status.</td><td><a href="/core-api-reference/authorizations.md">Learn more</a></td></tr><tr><td><strong><code>captures</code></strong></td><td>A transaction against an approved order — used to collect previously authorized funds and mark the order as `paid`.</td><td><a href="/core-api-reference/captures.md">Learn more</a></td></tr><tr><td><strong><code>voids</code></strong></td><td>A transaction against a pending order — used to cancel it before capture, moving the order's payment status to `voided`.</td><td><a href="/core-api-reference/voids.md">Learn more</a></td></tr><tr><td><strong><code>refunds</code></strong></td><td>A transaction against a capture — used to return previously captured funds to the customer, in full or in part.</td><td><a href="/core-api-reference/refunds.md">Learn more</a></td></tr><tr><td><strong><code>customer_payment_sources</code></strong></td><td>The link between a customer and a saved card — used to let logged-in customers reuse stored payment methods at checkout.</td><td><a href="/core-api-reference/customer_payment_sources.md">Learn more</a></td></tr><tr><td><strong><code>wire_transfers</code></strong></td><td>A manual payment source for wire transfers — used to record out-of-band payments that were always automatically authorized.</td><td><a href="/core-api-reference/wire_transfers.md">Learn more</a></td></tr><tr><td><strong><code>manual_gateways</code></strong></td><td>The gateway configuration for manual payments — used to accept wire transfers, cash, and other non-integrated payment options.</td><td><a href="/core-api-reference/manual_gateways.md">Learn more</a></td></tr><tr><td><strong><code>adyen_gateways</code></strong></td><td>The gateway configuration for Adyen — used to process PSD2-compliant, SCA/3DS2 payments through Adyen's SDK.</td><td><a href="/core-api-reference/adyen_gateways.md">Learn more</a></td></tr><tr><td><strong><code>adyen_payments</code></strong></td><td>A payment source tied to an Adyen gateway — used to process a payment through Adyen.</td><td><a href="/core-api-reference/adyen_payments.md">Learn more</a></td></tr><tr><td><strong><code>axerve_gateways</code></strong></td><td>The gateway configuration for Axerve — used to process PSD2-compliant, SCA/3DS2 payments through Axerve's Lightbox.</td><td><a href="/core-api-reference/axerve_gateways.md">Learn more</a></td></tr><tr><td><strong><code>axerve_payments</code></strong></td><td>A payment source tied to an Axerve gateway — used to process a payment through Axerve.</td><td><a href="/core-api-reference/axerve_payments.md">Learn more</a></td></tr><tr><td><strong><code>braintree_gateways</code></strong></td><td>The gateway configuration for Braintree — used to process PSD2-compliant, SCA/3DS2 payments through Braintree's SDK.</td><td><a href="/core-api-reference/braintree_gateways.md">Learn more</a></td></tr><tr><td><strong><code>braintree_payments</code></strong></td><td>A payment source tied to a Braintree gateway — used to process a payment through Braintree.</td><td><a href="/core-api-reference/braintree_payments.md">Learn more</a></td></tr><tr><td><strong><code>checkout_com_gateways</code></strong></td><td>The gateway configuration for Checkout.com — used to process PSD2-compliant, SCA/3DS2 payments through Checkout.com's SDK.</td><td><a href="/core-api-reference/checkout_com_gateways.md">Learn more</a></td></tr><tr><td><strong><code>checkout_com_payments</code></strong></td><td>A payment source tied to a Checkout.com gateway — used to process a payment through Checkout.com.</td><td><a href="/core-api-reference/checkout_com_payments.md">Learn more</a></td></tr><tr><td><strong><code>external_gateways</code></strong></td><td>The gateway configuration for custom providers — used to integrate any payment service not available out-of-the-box.</td><td><a href="/core-api-reference/external_gateways.md">Learn more</a></td></tr><tr><td><strong><code>external_payments</code></strong></td><td>A payment source tied to an external gateway — used to process a payment through a custom integration.</td><td><a href="/core-api-reference/external_payments.md">Learn more</a></td></tr><tr><td><strong><code>klarna_gateways</code></strong></td><td>The gateway configuration for Klarna — used to process PSD2-compliant, SCA/3DS2 payments through Klarna's SDK.</td><td><a href="/core-api-reference/klarna_gateways.md">Learn more</a></td></tr><tr><td><strong><code>klarna_payments</code></strong></td><td>A payment source tied to a Klarna gateway — used to process a payment through Klarna.</td><td><a href="/core-api-reference/klarna_payments.md">Learn more</a></td></tr><tr><td><strong><code>paypal_gateways</code></strong></td><td>The gateway configuration for PayPal — used to process payments through PayPal.</td><td><a href="/core-api-reference/paypal_gateways.md">Learn more</a></td></tr><tr><td><strong><code>paypal_payments</code></strong></td><td>A payment source tied to a PayPal gateway — used to process a payment through PayPal.</td><td><a href="/core-api-reference/paypal_payments.md">Learn more</a></td></tr><tr><td><strong><code>satispay_gateways</code></strong></td><td>The gateway configuration for Satispay — used to process PSD2-compliant, SCA/3DS2 payments through Satispay.</td><td><a href="/core-api-reference/satispay_gateways.md">Learn more</a></td></tr><tr><td><strong><code>satispay_payments</code></strong></td><td>A payment source tied to a Satispay gateway — used to process a payment through Satispay.</td><td><a href="/core-api-reference/satispay_payments.md">Learn more</a></td></tr><tr><td><strong><code>stripe_gateways</code></strong></td><td>The gateway configuration for Stripe — used to process PSD2-compliant, SCA/3DS2 payments through Stripe's SDK.</td><td><a href="/core-api-reference/stripe_gateways.md">Learn more</a></td></tr><tr><td><strong><code>stripe_payments</code></strong></td><td>A payment source tied to a Stripe gateway — used to process a payment through Stripe.</td><td><a href="/core-api-reference/stripe_payments.md">Learn more</a></td></tr><tr><td><strong><code>order_validation_rules</code></strong></td><td>Validation rules scoped to a market — used to enforce conditions, such as required billing info, before order placement.</td><td><a href="/core-api-reference/order_validation_rules.md">Learn more</a></td></tr><tr><td><strong><code>billing_info_validation_rules</code></strong></td><td>An order validation rule subtype — used to make billing info required for a specific market.</td><td><a href="/core-api-reference/billing_info_validation_rules.md">Learn more</a></td></tr><tr><td><strong><code>shipment_line_items</code></strong></td><td>The shipment-scoped view of a stock line item — used to represent a SKU's quantity within a specific shipment.</td><td></td></tr></tbody></table>

</details>


---

# 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://docs.commercelayer.io/core-api-reference/2026-05/readme.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.