Build a perfect integration
How the four Kustom products connect on one order, where Kustom sits among the systems you already run and what a complete integration does at every stage of the money's life — with a link to the section that builds each one.
One order runs through every Kustom product. A working integration takes the payment. A perfect one also captures when it ships, refunds against the right shipment, tells Kustom when it has the order, learns about changes without polling and matches every payout to an order in your own books. None of that is extra: an authorized order nobody captures is money you never receive.
This page is the map and the standard. Nothing is built here — every stage links to the section that builds it.
Pick your path
Section titled “Pick your path”Most stores connect without writing any code. Start with the path that fits you.
Your store runs on a platform
Close to thirty platforms — WooCommerce, Magento, PrestaShop and OXID among them — ship a maintained Kustom plugin. Installing it is the integration.
You are building the integration
A working checkout in 15 minutes, with every call running for real beside the text on throwaway Playground credentials. The guide then takes it to production.
You are building with a coding agent
Give the agent its own Playground API credentials and the Kustom skill, and it can create orders on its own. Every page has a Markdown version for it to read.
One order, four stages
Section titled “One order, four stages”Each product owns one stage of the money’s life and hands the same order_id to the next.
- in the cartno order yetElements
You express buttons and payment displays on pages you already own. Kustom renders them, and starts the order from an express button.
- at the checkoutthe customer paysCheckout
You create the order, render the snippet, answer callbacks, record the push. Kustom runs the checkout UI and payment methods, and authorizes the amount.
- authorizedthe money is reservedOrder Management
You acknowledge, capture as you ship, refund, cancel, extend. Kustom moves the money on capture.
- capturedthe money moves
- settledin your accountFinance
You reconcile the settlement report against your orders. Kustom pays out on schedule.
Same order_id at every stage, same credential. An integration model, a plugin or a direct build changes who writes the code for a stage, never the stages.
Where Kustom sits in your architecture
Section titled “Where Kustom sits in your architecture”Kustom doesn’t care what your systems are called. It cares that each call reaches it from the system that owns the business event behind it.
The call lives with the event. A shipment triggers the capture, so capture belongs where shipments are known. An approved return triggers the refund. A payout landing triggers reconciliation. The storefront’s job ends when the push is recorded and acknowledged.
That holds whatever’s on your side of it: one system doing everything, a storefront that hands off to a separate OMS, ERP and finance stack, a headless build where your own backend holds the API credentials or a platform with a plugin covering the common cases. Kustom doesn’t need to know which of these you are — only that whichever system owns an event is the one that calls it in.
Two things make any of those work: every system stores the Kustom order_id next to its own
order number, and every order carries that number in merchant_reference1.
Webhooks go to the system that needs to react, so no
system polls another.
What a perfect integration does
Section titled “What a perfect integration does”Each card is a standard, not instructions. The links are where the instructions are.
1Before the checkout
- Express buttons on product and cart pages
- Payment method display before the customer commits
2Taking the payment
- One order per cart, updated — never a second one
- One line per item, with product_url and image_url
- Discounts, gift cards and shipping as their own lines
- Locale, country, currency and your own terms URL
- Delivery options: static, or live from your TMS
- Push and redirect both record the order — push wins
3After the payment
- Acknowledge every order once your record exists
- Capture as you ship, with the lines it covers
- Tracking on the capture, not the order
- Refunds allocated to their capture
- Cancel what you cannot fulfill
- Extend the authorization before it expires
4Getting paid
- merchant_reference1 carries your order number
- Settlement reports by API or SFTP, not by hand
- Bank payment reference joins statement to report
Staying in sync
- Events by webhook, not polling
- Every delivery signature-verified and deduplicated
- Your record is the truth for the business, Kustom's for the money
Running it
- Playground and production never mixed
- Eight go-live cases as the regression suite
- Unknown fields ignored, every enum defaulted, keyed on error_code
- Every Order Management write keyed with Kustom-Idempotency-Key
The checklist
Section titled “The checklist”You have a perfect integration when every line is true. Each one links to the page that proves it.
- Render Checkout snippet
- Confirmation & push
- Update or cancel an order
- Capture an order
- Refunds
- Extend authorization
- Your own data on an order
- Settlements
- Webhooks
- End-to-end test cases
Where the work is
Section titled “Where the work is”Elements
Express buttons and payment displays on pages you already own, before an order exists.
Checkout
The payload, the create call, the snippet, the callbacks and the two ways you learn the customer paid.
Order Management
Acknowledge, capture, ship, refund, cancel and extend — the calls that move the money.
Finance
Payout schedules and the settlement reports you reconcile against.
Partners
The platforms that ship a plugin, and the shipping and accounting systems that connect to Kustom.
API reference
Every field on every endpoint, plus authentication, errors, limits and idempotency.
Related
Section titled “Related”- How Kustom Checkout works — the four calls behind every direct integration
- What an order is — the one object every stage shares
- Order lifecycle — the statuses underneath this page
- Sell to businesses (B2B), Charge a customer later, Age verification and Upsell — features to add to the checkout
- Building with a coding agent — hand this page and its checklist to an agent
This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.