Add Agentic Checkout to a Custom Store

Draw the existing successful purchase first

Before choosing a protocol, follow one ordinary customer order through your store. Identify the catalog service, price calculation, inventory or license rule, payment integration, order record and delivery service. These responsibilities already exist somewhere, even if they currently sit inside one application.

Cedar Research is our fictional custom store. It sells a downloadable report for an illustrative $29 with a personal-use license. Sam asks an assistant to buy the latest edition for no more than $35. The agent route must select the right item, obtain the real total, respect the authority and return usable access. The example is synthetic and does not claim a tested integration.

The architectural aim is one set of business rules reached through more than one interface. A human website and an agent API can present different experiences while using the same authoritative pricing and order services. If each interface calculates its own terms, support eventually has to explain why two customers bought apparently identical items under inconsistent rules.

Expose a purchasable offer with stable identity

The agent needs an item it can identify precisely. Publish the report edition, format, license and relevant delivery restrictions. Preserve a stable product identifier from discovery into checkout. A natural-language title is useful for selection but should not be the sole key used to commit the purchase.

Keep the offer's important commercial facts machine-readable through the supported route. That does not mean inventing a universal catalog schema. Use the contract you actually implement and ensure that its values come from the authoritative catalog. A product description can explain the license, while the checkout service enforces the corresponding rule.

Do not promise unlimited availability or a fixed price if the underlying service can change those facts. Establish how discovery data is refreshed and how checkout recalculates current terms. A cached offer should lead to validation, not a bypass of the merchant's current restrictions.

Choose the route by the intended buyer interaction

A commerce-channel integration can require a defined checkout contract and separate onboarding. ACP's merchant specification describes sessions and order notifications for its supported route. UCP describes discoverable commerce capabilities and related architecture. Choose the interface that your intended channel actually supports. [1] [2]

For a paid API or digital resource, x402 offers an HTTP-oriented payment flow. Coinbase describes the buyer seeing the price, paying and obtaining access within the resource request flow, with facilitator verification and settlement. That can fit request-based digital delivery without a conventional card form. It does not define every retail order or support policy. [3]

A referral into your existing checkout is another viable route when the surface supports it. Do not force an API purchase if the product needs customer interaction the chosen protocol or channel does not support. Evaluate the exact experience the customer receives and be precise when describing it publicly.

Keep the adapter small and the business services authoritative

The adapter should authenticate the caller, validate the request against the selected contract and invoke controlled business operations. It translates the result into the supported response. It should not contain a second catalog, guess a tax amount or grant a license based on the model's narrative.

The price service calculates the current total. The inventory or entitlement service checks what can be committed. The payment adapter performs the supported financial operation and verifies its result. The order service joins those outcomes and supplies a retrievable record. The delivery service grants the purchased output against that order.

You can implement those boundaries in one application initially. The important point is a clear responsibility and controlled transition, not a requirement to deploy a large number of microservices. Future account or product features can then use the same business operations without rewriting every editorial or customer-facing page.

Make checkout changes explicit

A checkout session holds a proposed purchase under current terms. Return useful information about the selected item, total and any missing input through the actual schema. If the customer changes the license or delivery choice, recalculate the terms and report the resulting state.

For Cedar, a $29 item plus an illustrative $2 applicable addition gives a $31 total. That fits Sam's $35 limit. A changed total of $36 requires a new authority decision under the supported mechanism. A change to a subscription may require a different decision even if its first payment remains $29.

Define expiry and reservation behavior in the merchant's rules. If the old quote is no longer valid, return a clear path to current terms. Do not accept a stale amount merely because the assistant retained it in its context. The server remains responsible for what the store actually commits.

Enforce authority at the completion boundary

The existence of an authenticated agent does not establish the buyer's permission for every item. The completion path needs the applicable authority and supported credential context for the current purchase. Keep these checks in deterministic code and protected services rather than asking the model to decide if a vague conversation “sounds approved.”

Use the provider or protocol's actual credential mechanism. Keep secrets out of model output and general-purpose logs. A token reference, approval reference and provider result can give the order system useful evidence without exposing the credential itself to every component.

If human confirmation is required, preserve the existing checkout and identify the specific action needed. A pending state should not become a fabricated completed order. If the purchase terms expire while waiting, refresh them and obtain the appropriate new decision before committing.

Define who may change each record

The endpoint ownership table is conceptual, not an official API schema. It helps assign write permissions and prevent a caller from setting financial or delivery truth directly. A request can ask to complete an order; the controlled services decide and record the result.

For example, the agent can request current terms but should not set the merchant's authoritative price. It can request completion but should not declare the payment confirmed. It can retrieve delivery status but should not mark a report entitlement delivered merely because it wants to finish the task. Those state changes need evidence from the responsible services.

Use authorization on retrieval as well as writes. Knowing a session or order reference must not automatically grant access to another customer's details. Apply the product's actual account or possession mechanism, and keep public product discovery separate from private order access.

For a versioned conceptual contract record, label the merchant design Cedar adapter revision 2026-10-08. Its create operation accepts a report identifier and quantity, returning checkout C-31 with the current $31 terms; completion requires C-31, applicable authority A-35 and a supported payment reference; status retrieval returns the existing O-31 and its delivery state. This is a local design example, not an ACP/UCP version, endpoint schema or runnable request. Record the separately selected official protocol revision alongside it.

Preserve one business action across retries

A completion timeout leaves an unknown result. The store may already have accepted the purchase and processed payment. The agent needs a way to retrieve the existing session or order, or use the documented safe retry behavior. Starting another purchase immediately can create an unintended duplicate.

Implement idempotency according to the chosen contract and preserve a durable outcome at the business boundary. A request trace helps identify a network call, while the business operation reference helps resolve the purchase. Do not conflate them or create a fresh unrelated financial operation for every retry.

Handle conflicting repeats explicitly. If a repeated operation identity carries a changed item or amount, it should not inherit an earlier success without validation. Return the appropriate supported outcome and preserve the evidence needed to investigate. Test that case before inviting agents to retry automatically.

Process provider and order events separately

A payment provider event is evidence about a financial operation under that provider's contract. A merchant order event communicates the merchant's current business state. A fulfilment event records a delivery operation. Name the directions and owners clearly, because they are not interchangeable proof.

Verify incoming events through the actual integration mechanism, deduplicate appropriately and avoid moving a record backward when an older event arrives late. Outbound notifications should reflect the authoritative order rather than whatever the model last said in a conversation. Keep sensitive values out of event payloads where they are unnecessary.

ACP's documentation describes merchant order webhooks and their signing arrangement. If you implement that route, use its exact schema and signing instructions. Do not copy a payment-provider webhook pattern and assume it applies unchanged to merchant-to-channel notifications. [1]

Deliver and recover against the committed order

After the appropriate financial result, grant access to the purchased report through the delivery service. Preserve the order identity across retry attempts. If delivery fails, keep the paid order visible and assign a recoverable exception. Do not erase the financial record or require another purchase to obtain the original entitlement.

If the product cannot be delivered, use the merchant's disclosed support and resolution policy with the actual payment route. A support decision and a financial refund are separate records. Give the customer the real current status and a durable reference rather than a confident but unsupported completion message.

Agentify Commerce provides a digital offer catalog, direct-to-merchant USDC/x402 payment and digital delivery with separate test and live routes. It is an affiliated option for custom stores and paid digital services. Evaluate the actual digital purchase flow; do not infer physical shipping, universal refunds or native ACP/UCP support from x402 payment support. [4]

Launch a bounded route and define a pause

Choose one product, one supported buyer route and an operational owner for each boundary. Write expected results for a normal order, changed terms, unavailable item, repeated completion, lost response and delivery failure. Use safe provider-supported test mechanisms and preserve configuration-specific evidence.

Define how to pause new purchases without abandoning existing orders. The adapter can stop accepting new completions while support retains status and delivery access for paid customers. Record the person authorized to make that decision and the message callers should receive. A deployment rollback should not turn confirmed purchases into missing records.

Monitor actual outcomes by stage, with appropriate data minimization. Do not treat a product response as a sale or a payment as proof of delivery. Add broader distribution only when the route produces a clear result and the exceptions have accountable owners.

The architecture is successful when the custom store can explain one purchase from the offered edition to the delivered entitlement, including uncertainty. Supporting an agent should add an interface to that coherent business process. It should not create a separate reality in which price, permission, money and delivery are inferred from unrelated text.

• Normal purchase: the current report produces one correctly priced order and one entitlement.
• Unavailable item: completion stops without a new financial action or substituted product.
• Changed total: $36 exceeds the $35 scope and requires a new decision.
• Changed license: a subscription cannot reuse one-time personal-report authority.
• Expired terms: retrieve fresh terms and apply the selected contract’s continuation rule.
• Identical retry after response loss: resolve the existing O-31 without a second payment.
• Conflicting operation reuse: changed terms with the same operation identity produce a clear conflict outcome.
• Repeated or delayed event: verify the event and retain a consistent current order state.
• Unauthorized retrieval: another buyer cannot read O-31 or obtain its entitlement.
• Payment-confirmed delivery failure: recover access against O-31 or enter the disclosed resolution workflow without charging again.