API reference

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.

Checkout

4

Checkout Callback

6

Customer Tokens

3

Hosted Payment Page

4

Elements

9

Shipping Service Callback

6

Order Management

15

In-Person Payments

13

Settlements

8

Checkout Configuration

20

Elements Partner

9

Native Partner Onboarding

5

Five things are true of all of them, whichever you pick: the credential to send, how a request and a response are written, what an error body means, what will be refused and how to make a retry safe. Read those once and they hold everywhere.

APIs

Checkout API

Create, read, update, and abort Checkout orders/checkout/v3/orders

4 operations

• POST
  Create an order/
• POST
  Update an order/{order_id}
• GET
  Get order details/{order_id}
• POST
  Abort an order/{order_id}/abort

Checkout Callback API

Callbacks Kustom makes to merchant URLs

6 operations

• POST
  Address update/merchant_urls.address_update
• POST
  Country change/merchant_urls.country_change
• POST
  Shipping option update/merchant_urls.shipping_option_update
• POST
  Order validation/merchant_urls.validation
• POST
  Upsell recommendations/merchant_urls.upsell
• POST
  Upsell validation/merchant_urls.upsell_validation

Customer Tokens API

Read tokens, create orders, and manage token status/customer-token/v1/tokens

3 operations

• GET
  Read a customer token/{customerToken}
• PATCH
  Update a customer token's status/{customerToken}/status
• POST
  Charge a customer token to create an order/{customerToken}/order

Hosted Payment Page API

Create and distribute hosted payment sessions/hpp/v1/sessions

4 operations

• POST
  Create an HPP session/
• GET
  Get details of an HPP session/{session_id}
• DELETE
  Disable an HPP session/{session_id}
• POST
  Distribute an HPP session/{session_id}/distribution

Elements API

Configure Elements clients and allowed origins/elements/v1/clients

9 operations

• GET
  Get client/{clientId}
• PUT
  Update a client/{clientId}
• DELETE
  Delete a client/{clientId}
• PUT
  Add/modify express config/{clientId}/express
• PATCH
  Patch express config/{clientId}/express
• PUT
  Update allowed origins/{clientId}/allowed-origins
• GET
  List clients for a merchant/
• POST
  Create a client/
• PATCH
  Add allowed origins/{clientId}/add-allowed-origins

Shipping Service Callback API

Authentication, shipping options, and shipment reservations

6 operations

• POST
  Get an authorization token/auth
• POST
  List shipping options/shippingoptions
• POST
  Select shipping option/shipment
• GET
  Get shipment status/shipment/{shipment_id}
• PUT
  Update the shipping option/shipment/{shipment_id}
• POST
  Confirm shipment reservation/shipment/{shipment_id}/confirm

Order Management API

Capture, refund, acknowledge, and amend orders/ordermanagement/v1/orders

15 operations

• Orders
• POST
  Add shipping information/{order_id}/shipping-info
• POST
  Release an authorization/{order_id}/release-remaining-authorization
• POST
  Extend the authorization time/{order_id}/extend-authorization-time
• POST
  Cancel an order/{order_id}/cancel
• POST
  Acknowledge a Kustom checkout order/{order_id}/acknowledge
• PATCH
  Update merchant references/{order_id}/merchant-references
• PATCH
  Update customer addresses/{order_id}/customer-details
• PATCH
  Update the order amount and order lines/{order_id}/authorization
• GET
  Get order details/{order_id}
• Refunds
• POST
  Refund an order/{order_id}/refunds
• GET
  Get refund details/{order_id}/refunds/{refund_id}
• Captures
• GET
  List all order captures/{order_id}/captures
• POST
  Capture an order/{order_id}/captures
• POST
  Add shipping information/{order_id}/captures/{capture_id}/shipping-info
• GET
  Get capture details/{order_id}/captures/{capture_id}

In-Person Payments API

Enrollments, devices, locations, and terminal sessions/ipp/v1

13 operations

• Sessions
• PUT
  Cancel session/sessions/{session_id}/cancel
• POST
  Create session/sessions
• GET
  Get session/sessions/{session_id}
• Devices
• PUT
  Update device/devices/{id}
• DELETE
  Deregister device/devices/{id}
• GET
  List devices/devices
• Enrollments
• GET
  List enrollments/enrollments
• POST
  Create enrollment/enrollments
• DELETE
  Delete enrollment/enrollments/{enrollment_id}
• Testing
• POST
  Simulate card tap/dev/sessions/{sessionId}/simulate-tap
• POST
  Create simulated device/dev/devices
• Locations
• GET
  List locations/locations
• GET
  Get location/locations/{id}

Settlements API

Payouts, transactions, and settlement reports

8 operations

• GET
  Payout summary/payouts/summary
• GET
  Payout details/payouts/{payment_reference}
• GET
  List all payouts/payouts
• GET
  Get a payouts summary (CSV)/reports/payout-with-transactions
• GET
  Get a payouts summary (PDF)/reports/payout
• GET
  List transactions in a payout/transactions
• GET
  Get a payouts summary with transactions (CSV)/reports/payouts-summary-with-transactions
• GET
  Get a payouts summary with transactions (PDF)/reports/payouts-summary

Partner APIs

Checkout Configuration API

Configure Checkout on behalf of merchants/v1/config

20 operations

• Upsell Configuration
• GET
  List all active upsell configuration rows for a merchant/upsell
• PUT
  Upsert upsell configuration for a merchant and one or more countries/upsell
• DELETE
  Soft-delete upsell configuration for a merchant and optional country/upsell
• GET
  Get resolved upsell configuration for a merchant and country/country/{country}/upsell
• Sign In With
• GET
  List all active sign in with rows for a merchant/signInWith
• PUT
  Upsert sign in with for a merchant and one or more countries/signInWith
• DELETE
  Soft-delete sign in with for a merchant and optional country/signInWith
• GET
  Get resolved sign in with for a merchant and country/country/{country}/signInWith
• Express Checkout Payment Methods
• GET
  List all active express checkout payment methods rows for a merchant/expressCheckoutPaymentMethods
• PUT
  Upsert express checkout payment methods for a merchant and one or more countries/expressCheckoutPaymentMethods
• DELETE
  Soft-delete express checkout payment methods for a merchant and optional country/expressCheckoutPaymentMethods
• GET
  Get resolved express checkout payment methods for a merchant and country/country/{country}/expressCheckoutPaymentMethods
• Checkout Styling
• GET
  List all active checkout styling rows for a merchant/checkoutStyling
• PUT
  Upsert checkout styling for a merchant and one or more countries/checkoutStyling
• DELETE
  Soft-delete checkout styling for a merchant and optional country/checkoutStyling
• GET
  Get resolved checkout styling for a merchant and country/country/{country}/checkoutStyling
• Analytics
• GET
  List all active analytics rows for a merchant/analytics
• PUT
  Upsert analytics configuration for a merchant and one or more countries/analytics
• DELETE
  Soft-delete analytics configuration for a merchant and optional country/analytics
• GET
  Get resolved analytics configuration for a merchant and country/country/{country}/analytics

Elements Partner API

Manage Elements clients for platform merchants/elements/v1/clients

9 operations

• GET
  Get client/{clientId}
• PUT
  Update a client/{clientId}
• DELETE
  Delete a client/{clientId}
• PUT
  Add/modify express config/{clientId}/express
• PATCH
  Patch express config/{clientId}/express
• PUT
  Update allowed origins/{clientId}/allowed-origins
• GET
  List clients for a merchant/
• POST
  Create a client/
• PATCH
  Add allowed origins/{clientId}/add-allowed-origins

Native Partner Onboarding API

Onboard merchants and request credentials/accountmanagement/v1/merchants

5 operations

• Merchants
• POST
  Create a merchant/
• GET
  Get merchant details/{merchantId}
• Credentials
• POST
  Request merchant credentials/{merchantId}/credentials-request
• Widget
• POST
  Generate onboarding widget URL/{merchantId}/widget-url-request
• Store Information
• PATCH
  Update store homepage URL/{merchantId}/store-information/stores/{storeId}

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 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), 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 — before any call in this reference will work
• What an order is — the object nearly every one of these APIs acts on
• Webhooks — how Kustom calls you, rather than the other way round