Creating an offer
An offer is a frozen copy of a customer's basket on topi, which the customer reviews and accepts on the topi Hosted Checkout. Creating one is where a transaction begins.
The full request and response, with examples, are in the API reference. This page covers how the offer fits into your flow, which the reference does not.
Create the offer and redirect
Call createOffer (POST /v1/offers) from your backend with the basket. See the API reference for the full request and which fields are required. Two things worth knowing that the reference does not spell out: shipping_address is required when sales_channel is ecommerce, and you choose the expires_at value yourself.
On success, topi returns the offer with a checkout_redirect_url. Redirect the customer to that URL, exactly as returned (do not build it yourself, the format can change). The redirect happens in the same browser tab.
What happens next
The customer reviews, customizes, and accepts the offer on the topi Hosted Checkout. topi then runs a risk review. On approval, the offer becomes an order and you receive an order.created webhook. See Receiving and fulfilling orders.
Validate before you create
To check in advance whether an offer can be created, call validate (POST /v1/offers/validate). It takes the same payload as createOffer but creates nothing. It returns a pricing overview on success, or a specific error if something would block the offer: an unsupported product or shipping method, a seller_offer_reference already in use, mismatched currencies, and so on.
Earlier in the flow, cartRentalOverview answers the catalog-level question of whether a basket's products can be checked out at all.
Once the offer exists, its prices are frozen until it expires.
Triggering checkout from your channel
- Online stores: topi Elements provides a ready-made checkout button that calls your backend to create the offer.
- Telesales and point of sale: create the offer from your backend when the customer chooses topi, then open or share the
checkout_redirect_url.