# API reference

Endpoints, request fields, response schemas and generated examples for every Kustom API.

Every operation of every Kustom API is listed on this page, under the API it belongs to.
Each has a permanent URL, linkable request and response fields, and examples generated from
the OpenAPI specification.

Five things are true of all of them, whichever you pick: [the credential to
send](/api/authentication/), [how a request and a response are
written](/api/requests-and-responses/), [what an error body means](/api/errors/), [what will
be refused](/api/limits/) and [how to make a retry safe](/order-management/idempotency-and-retries/).
Read those once and they hold everywhere.

## APIs

### Checkout API

Create, read, update, and abort Checkout orders. Overview: [/api/checkout.md](/api/checkout.md)

- `POST /checkout/v3/orders` — [Create an order](/api/checkout/create-order-merchant.md)
- `POST /checkout/v3/orders/{order_id}` — [Update an order](/api/checkout/update-order-merchant.md)
- `GET /checkout/v3/orders/{order_id}` — [Get order details](/api/checkout/read-order-merchant.md)
- `POST /checkout/v3/orders/{order_id}/abort` — [Abort an order](/api/checkout/abort-order.md)

### Checkout Callback API

Callbacks Kustom makes to merchant URLs. Overview: [/api/checkout/callbacks.md](/api/checkout/callbacks.md)

- `POST /merchant_urls.address_update` — [Address update](/api/checkout/callbacks/update-address.md)
- `POST /merchant_urls.country_change` — [Country change](/api/checkout/callbacks/country-change.md)
- `POST /merchant_urls.shipping_option_update` — [Shipping option update](/api/checkout/callbacks/update-shipping-option.md)
- `POST /merchant_urls.validation` — [Order validation](/api/checkout/callbacks/validate.md)
- `POST /merchant_urls.upsell` — [Upsell recommendations](/api/checkout/callbacks/upsell.md)
- `POST /merchant_urls.upsell_validation` — [Upsell validation](/api/checkout/callbacks/upsell-validation.md)

### Customer Tokens API

Read tokens, create orders, and manage token status. Overview: [/api/customer-tokens.md](/api/customer-tokens.md)

- `GET /customer-token/v1/tokens/{customerToken}` — [Read a customer token](/api/customer-tokens/read-token.md)
- `PATCH /customer-token/v1/tokens/{customerToken}/status` — [Update a customer token's status](/api/customer-tokens/update-token-status.md)
- `POST /customer-token/v1/tokens/{customerToken}/order` — [Charge a customer token to create an order](/api/customer-tokens/charge-token.md)

### Hosted Payment Page API

Create and distribute hosted payment sessions. Overview: [/api/hosted-payment-page.md](/api/hosted-payment-page.md)

- `POST /hpp/v1/sessions` — [Create an HPP session](/api/hosted-payment-page/create-hpp-session.md)
- `GET /hpp/v1/sessions/{session_id}` — [Get details of an HPP session](/api/hosted-payment-page/get-session-by-id.md)
- `DELETE /hpp/v1/sessions/{session_id}` — [Disable an HPP session](/api/hosted-payment-page/disable-hpp-session.md)
- `POST /hpp/v1/sessions/{session_id}/distribution` — [Distribute an HPP session](/api/hosted-payment-page/distribute-hpp-session.md)

### Elements API

Configure Elements clients and allowed origins. Overview: [/api/elements.md](/api/elements.md)

- `GET /elements/v1/clients/{clientId}` — [Get client](/api/elements/get-client.md)
- `PUT /elements/v1/clients/{clientId}` — [Update a client](/api/elements/update-client.md)
- `DELETE /elements/v1/clients/{clientId}` — [Delete a client](/api/elements/delete-client.md)
- `PUT /elements/v1/clients/{clientId}/express` — [Add/modify express config](/api/elements/add-or-update-express.md)
- `PATCH /elements/v1/clients/{clientId}/express` — [Patch express config](/api/elements/patch-express.md)
- `PUT /elements/v1/clients/{clientId}/allowed-origins` — [Update allowed origins](/api/elements/update-allowed-origins.md)
- `GET /elements/v1/clients/` — [List clients for a merchant](/api/elements/get-all-clients.md)
- `POST /elements/v1/clients/` — [Create a client](/api/elements/create-client.md)
- `PATCH /elements/v1/clients/{clientId}/add-allowed-origins` — [Add allowed origins](/api/elements/add-allowed-origins.md)

### Shipping Service Callback API

Authentication, shipping options, and shipment reservations. Overview: [/api/shipping-service-callback.md](/api/shipping-service-callback.md)

- `POST /auth` — [Get an authorization token](/api/shipping-service-callback/auth.md)
- `POST /shippingoptions` — [List shipping options](/api/shipping-service-callback/shippingoptions.md)
- `POST /shipment` — [Select shipping option](/api/shipping-service-callback/postshipment.md)
- `GET /shipment/{shipment_id}` — [Get shipment status](/api/shipping-service-callback/getshipment.md)
- `PUT /shipment/{shipment_id}` — [Update the shipping option](/api/shipping-service-callback/putshipment.md)
- `POST /shipment/{shipment_id}/confirm` — [Confirm shipment reservation](/api/shipping-service-callback/shipmentconfirm.md)

### Order Management API

Capture, refund, acknowledge, and amend orders. Overview: [/api/order-management.md](/api/order-management.md)

- `POST /ordermanagement/v1/orders/{order_id}/shipping-info` — [Add shipping information](/api/order-management/append-order-shipping-info.md)
- `POST /ordermanagement/v1/orders/{order_id}/release-remaining-authorization` — [Release an authorization](/api/order-management/release-remaining-authorization.md)
- `POST /ordermanagement/v1/orders/{order_id}/extend-authorization-time` — [Extend the authorization time](/api/order-management/extend-authorization-time.md)
- `POST /ordermanagement/v1/orders/{order_id}/cancel` — [Cancel an order](/api/order-management/cancel-order.md)
- `POST /ordermanagement/v1/orders/{order_id}/acknowledge` — [Acknowledge a Kustom checkout order](/api/order-management/acknowledge-order.md)
- `PATCH /ordermanagement/v1/orders/{order_id}/merchant-references` — [Update merchant references](/api/order-management/update-merchant-references.md)
- `PATCH /ordermanagement/v1/orders/{order_id}/customer-details` — [Update customer addresses](/api/order-management/update-consumer-details.md)
- `PATCH /ordermanagement/v1/orders/{order_id}/authorization` — [Update the order amount and order lines](/api/order-management/update-authorization.md)
- `GET /ordermanagement/v1/orders/{order_id}` — [Get order details](/api/order-management/get-order.md)
- `POST /ordermanagement/v1/orders/{order_id}/refunds` — [Refund an order](/api/order-management/refund-order.md)
- `GET /ordermanagement/v1/orders/{order_id}/refunds/{refund_id}` — [Get refund details](/api/order-management/get-refund.md)
- `GET /ordermanagement/v1/orders/{order_id}/captures` — [List all order captures](/api/order-management/get-captures.md)
- `POST /ordermanagement/v1/orders/{order_id}/captures` — [Capture an order](/api/order-management/capture-order.md)
- `POST /ordermanagement/v1/orders/{order_id}/captures/{capture_id}/shipping-info` — [Add shipping information](/api/order-management/append-shipping-info.md)
- `GET /ordermanagement/v1/orders/{order_id}/captures/{capture_id}` — [Get capture details](/api/order-management/get-capture.md)

### In-Person Payments API

Enrollments, devices, locations, and terminal sessions. Overview: [/api/in-person-payments.md](/api/in-person-payments.md)

- `PUT /ipp/v1/sessions/{session_id}/cancel` — [Cancel session](/api/in-person-payments/cancel-session.md)
- `POST /ipp/v1/sessions` — [Create session](/api/in-person-payments/create-session.md)
- `GET /ipp/v1/sessions/{session_id}` — [Get session](/api/in-person-payments/get-session.md)
- `PUT /ipp/v1/devices/{id}` — [Update device](/api/in-person-payments/update-device.md)
- `DELETE /ipp/v1/devices/{id}` — [Deregister device](/api/in-person-payments/deregister-device.md)
- `GET /ipp/v1/devices` — [List devices](/api/in-person-payments/list-devices.md)
- `GET /ipp/v1/enrollments` — [List enrollments](/api/in-person-payments/list-enrollments.md)
- `POST /ipp/v1/enrollments` — [Create enrollment](/api/in-person-payments/create-enrollment.md)
- `DELETE /ipp/v1/enrollments/{enrollment_id}` — [Delete enrollment](/api/in-person-payments/delete-enrollments.md)
- `POST /ipp/v1/dev/sessions/{sessionId}/simulate-tap` — [Simulate card tap](/api/in-person-payments/simulate-card-tap.md)
- `POST /ipp/v1/dev/devices` — [Create simulated device](/api/in-person-payments/create-simulated-device.md)
- `GET /ipp/v1/locations` — [List locations](/api/in-person-payments/list-locations.md)
- `GET /ipp/v1/locations/{id}` — [Get location](/api/in-person-payments/get-location.md)

### Settlements API

Payouts, transactions, and settlement reports. Overview: [/api/settlements.md](/api/settlements.md)

- `GET /payouts/summary` — [Payout summary](/api/settlements/get-payout-summary.md)
- `GET /payouts/{payment_reference}` — [Payout details](/api/settlements/get-payout.md)
- `GET /payouts` — [List all payouts](/api/settlements/get-payouts.md)
- `GET /reports/payout-with-transactions` — [Get a payouts summary (CSV)](/api/settlements/get-payout-report-with-transactions.md)
- `GET /reports/payout` — [Get a payouts summary (PDF)](/api/settlements/payout.md)
- `GET /transactions` — [List transactions in a payout](/api/settlements/get-transactions.md)
- `GET /reports/payouts-summary-with-transactions` — [Get a payouts summary with transactions (CSV)](/api/settlements/get-payouts-summary-report-with-transactions.md)
- `GET /reports/payouts-summary` — [Get a payouts summary with transactions (PDF)](/api/settlements/payouts-summary.md)

## Partner APIs

### Checkout Configuration API

Configure Checkout on behalf of merchants. Overview: [/api/partners/checkout-configuration.md](/api/partners/checkout-configuration.md)

- `GET /v1/config/upsell` — [List all active upsell configuration rows for a merchant](/api/partners/checkout-configuration/get-config-value-list.md)
- `PUT /v1/config/upsell` — [Upsert upsell configuration for a merchant and one or more countries](/api/partners/checkout-configuration/upsert.md)
- `DELETE /v1/config/upsell` — [Soft-delete upsell configuration for a merchant and optional country](/api/partners/checkout-configuration/delete.md)
- `GET /v1/config/country/{country}/upsell` — [Get resolved upsell configuration for a merchant and country](/api/partners/checkout-configuration/get-config-value.md)
- `GET /v1/config/signInWith` — [List all active sign in with rows for a merchant](/api/partners/checkout-configuration/get-config-value-list-1.md)
- `PUT /v1/config/signInWith` — [Upsert sign in with for a merchant and one or more countries](/api/partners/checkout-configuration/upsert-1.md)
- `DELETE /v1/config/signInWith` — [Soft-delete sign in with for a merchant and optional country](/api/partners/checkout-configuration/delete-1.md)
- `GET /v1/config/country/{country}/signInWith` — [Get resolved sign in with for a merchant and country](/api/partners/checkout-configuration/get-config-value-1.md)
- `GET /v1/config/expressCheckoutPaymentMethods` — [List all active express checkout payment methods rows for a merchant](/api/partners/checkout-configuration/get-config-value-list-2.md)
- `PUT /v1/config/expressCheckoutPaymentMethods` — [Upsert express checkout payment methods for a merchant and one or more countries](/api/partners/checkout-configuration/upsert-2.md)
- `DELETE /v1/config/expressCheckoutPaymentMethods` — [Soft-delete express checkout payment methods for a merchant and optional country](/api/partners/checkout-configuration/delete-2.md)
- `GET /v1/config/country/{country}/expressCheckoutPaymentMethods` — [Get resolved express checkout payment methods for a merchant and country](/api/partners/checkout-configuration/get-config-value-2.md)
- `GET /v1/config/checkoutStyling` — [List all active checkout styling rows for a merchant](/api/partners/checkout-configuration/get-config-value-list-3.md)
- `PUT /v1/config/checkoutStyling` — [Upsert checkout styling for a merchant and one or more countries](/api/partners/checkout-configuration/upsert-3.md)
- `DELETE /v1/config/checkoutStyling` — [Soft-delete checkout styling for a merchant and optional country](/api/partners/checkout-configuration/delete-3.md)
- `GET /v1/config/country/{country}/checkoutStyling` — [Get resolved checkout styling for a merchant and country](/api/partners/checkout-configuration/get-config-value-3.md)
- `GET /v1/config/analytics` — [List all active analytics rows for a merchant](/api/partners/checkout-configuration/get-config-value-list-4.md)
- `PUT /v1/config/analytics` — [Upsert analytics configuration for a merchant and one or more countries](/api/partners/checkout-configuration/upsert-4.md)
- `DELETE /v1/config/analytics` — [Soft-delete analytics configuration for a merchant and optional country](/api/partners/checkout-configuration/delete-4.md)
- `GET /v1/config/country/{country}/analytics` — [Get resolved analytics configuration for a merchant and country](/api/partners/checkout-configuration/get-config-value-4.md)

### Elements Partner API

Manage Elements clients for platform merchants. Overview: [/api/partners/elements.md](/api/partners/elements.md)

- `GET /elements/v1/clients/{clientId}` — [Get client](/api/partners/elements/get-client.md)
- `PUT /elements/v1/clients/{clientId}` — [Update a client](/api/partners/elements/update-client.md)
- `DELETE /elements/v1/clients/{clientId}` — [Delete a client](/api/partners/elements/delete-client.md)
- `PUT /elements/v1/clients/{clientId}/express` — [Add/modify express config](/api/partners/elements/add-or-update-express.md)
- `PATCH /elements/v1/clients/{clientId}/express` — [Patch express config](/api/partners/elements/patch-express.md)
- `PUT /elements/v1/clients/{clientId}/allowed-origins` — [Update allowed origins](/api/partners/elements/update-allowed-origins.md)
- `GET /elements/v1/clients/` — [List clients for a merchant](/api/partners/elements/get-all-clients.md)
- `POST /elements/v1/clients/` — [Create a client](/api/partners/elements/create-client.md)
- `PATCH /elements/v1/clients/{clientId}/add-allowed-origins` — [Add allowed origins](/api/partners/elements/add-allowed-origins.md)

### Native Partner Onboarding API

Onboard merchants and request credentials. Overview: [/api/partners/native-onboarding.md](/api/partners/native-onboarding.md)

- `POST /accountmanagement/v1/merchants/` — [Create a merchant](/api/partners/native-onboarding/create-merchant.md)
- `GET /accountmanagement/v1/merchants/{merchantId}` — [Get merchant details](/api/partners/native-onboarding/get-merchant-details.md)
- `POST /accountmanagement/v1/merchants/{merchantId}/credentials-request` — [Request merchant credentials](/api/partners/native-onboarding/create-merchant-credentials.md)
- `POST /accountmanagement/v1/merchants/{merchantId}/widget-url-request` — [Generate onboarding widget URL](/api/partners/native-onboarding/create-widget-url.md)
- `PATCH /accountmanagement/v1/merchants/{merchantId}/store-information/stores/{storeId}` — [Update store homepage URL](/api/partners/native-onboarding/update-home-page-url.md)

## Hosts and base paths

Every API is served from one host per environment, and the path decides which API you reach.

| Environment | Host |
| --- | --- |
| Playground (testing) | `https://api.playground.kustom.co` |
| Production | `https://api.kustom.co` |

| API | Base path |
| --- | --- |
| Checkout | `/checkout/v3/orders` |
| Checkout callback | your own URLs |
| Order Management | `/ordermanagement/v1/orders` |
| Settlements | `/settlements/v1` |
| Hosted Payment Page | `/hpp/v1/sessions` |
| Customer Token | `/customer-token/v1/tokens` |
| In-Person Payments | `/ipp/v1` |
| Elements | `/elements/v1/clients` |
| Shipping Service Callback | your own URLs |
| Native partner onboarding | `/accountmanagement/v1/merchants` |
| Checkout configuration | `/config/checkout/v1/config` |

Credentials are environment-specific and never interchangeable. See
[Authentication and environments](/api/authentication/) for how to get them. Every API in the
first table takes the same API credentials, sent as HTTP Basic auth. The partner APIs are the
exception: onboarding uses an OAuth 2.0 bearer token from Kustom's authorization server
([getting one](/partners/onboarding-api/)), and checkout configuration takes partner
credentials rather than a merchant's.

**Give each system its own credentials.** One pair works everywhere, but a Merchant ID can
carry several, and separate ones cost nothing: your store's checkout, the job that imports
settlements and a support tool each get their own. Then you can rotate or revoke one without
breaking the others, and a leak exposes only what that one system does.

## Related

- [Getting a credential and picking an environment](/api/authentication/) — before any call in this reference will work
- [What an order is](/basics/what-an-order-is/) — the object nearly every one of these APIs acts on
- [Webhooks](/basics/conventions/webhooks/) — how Kustom calls you, rather than the other way round