Build with the API

If you want full control of the experience, build it yourself on the Checkout API. Phew still does the hard parts: classifying each item, deciding whether it can be covered, pricing it, issuing the policy and handling claims. You design how the offer looks and where it appears: in a checkout, an app, a receipt, a bank’s purchase overview, or somewhere we haven’t thought of.

The whole integration is three server-side calls. Your frontend only ever talks to your own backend; the Phew secret key stays on the server.

Browser ──▶ your backend ──▶ POST /v1/offers            (cart ready)
Browser ◀── plans, prices, documents
Browser ──▶ your backend ──▶ POST /v1/policies          (order paid)
                         ──▶ POST /v1/policies/{id}/cancel  (item returned)

Steps

1. Request an offer when the cart is ready. Call POST /v1/offers with the items, currency and market. Cache the response against the cart until expires_at (30 minutes); request a new one if the cart changes.

2. Show the offer. For each eligible item, show the plans with their price and the links in documents. Let the customer choose one plan or none.

3. Add the premium to the order. If you collect the premium (the usual model), add it as its own line on the order so it appears on the receipt and can be refunded separately.

4. Create the policy when payment succeeds. Call POST /v1/policies from the same place you mark the order as paid, with an Idempotency-Key derived from the order ID so retries never create duplicates.

5. Cancel on returns. When a covered item is returned or the customer withdraws, call POST /v1/policies/{id}/cancel.

6. Listen for webhooks. Subscribe to claim.* and settlement.statement.created if you want to show claim status or reconcile automatically. See Events.

Display requirements

Insurance distribution rules apply to how the offer is shown. Every integration must:

• Show the plan name, term and price, including all taxes.
• Link to the terms (documents.terms_url) and the insurance product information document (documents.ipid_url) before the customer adds the cover.
• Leave the offer unselected by default. A pre-ticked box is not allowed.
• Make declining as easy as accepting.
• Show the cover as a separate line on the order confirmation and receipt.

Tip

Phew can review your checkout in sandbox before you go live. Send us a screenshot or a link to a test store.

Failure handling

The offer is an add-on and must never block a sale.

• Use a short timeout (2 seconds) on POST /v1/offers. If it fails or times out, hide the offer and continue.
• Retry POST /v1/policies with the same Idempotency-Key on network errors and 5xx responses, with exponential backoff, for up to 24 hours. A queue is the simplest way to do this.
• If a policy can’t be created at all, refund the premium line and let us know. The customer should never pay for cover they don’t have.