Confirm the order

Record the customer's protection choices and place the order with Teak when the purchase completes.

Your server records the customer's protection choices and places the order with Teak. Teak then issues protection for every protected item, at the price you showed.

Your Teak integration contact gives you the calls

Teak gives you the calls for this step during onboarding. You can build everything around them now: this page covers what you send and how to handle each outcome.

Place the order with Teak only after your own order is confirmed, for example after the customer's payment succeeds. That way, Teak never issues protection for an order that didn't go through.

1. Record the customer's choices

Send the customer's choice for every optional item in the cart, on the session from the Programs API:

ProtectionWhat you send
OptionalWhether the customer accepted or declined protection for the item. Items can differ: a customer can protect one ticket and not another.
EmbeddedNothing to ask. Teak adds embedded protection automatically, and it can't be removed.
  • No choice means no protection. An optional item with no recorded choice isn't protected.
  • The latest choice counts. If the customer changes their mind before they complete the purchase, send the new choice.
  • One choice per cart item. If the same item appeared in more than one call to the Programs API, for example on search and again at checkout, send its choice once.

2. Send the order details

Along with the session ID and the customer's choices, you send these details. You never send prices or items, because the session already holds them.

DetailDescription
Your order numberSent as reference_id. It must be unique across your orders: Teak uses it to match webhooks and lookups to your order.
The customerThe person booking, which isn't always the traveler or attendee. Their name and email are required. For optional protection, Teak emails them their protection details.
Billing addressRecommended. Teak uses it to confirm where the customer is located.
PaymentAlways { "type": "invoice" }. Teak bills you for issued protection on your regular invoice.

3. Handle the outcome

Check the HTTP status first. Whether Teak issues anything depends on the protection and the customer's choices:

OutcomeWhenWhat to do
202 AcceptedAt least one item is protected: the customer accepted optional protection, or the order has embedded protection.Store the session ID with your order. Teak issues protection and notifies you.
204 No ContentNo item is protected, for example the customer declined everything. No order is created.Nothing. This is a normal outcome, not an error.
Already placedAn earlier attempt for this session already went through, for example one that timed out.Treat it as accepted, like a 202. It doesn't mean the order failed.
400 or 422The request is invalid, for example a required detail is missing.Fix the request. The message says what's wrong. Don't retry it unchanged.
401The access token is missing or expired.Get a new token and retry once.
403TeakOS isn't enabled for your account, or the session belongs to another account's keys.Contact your Teak integration contact, or use the same client's keys for every call on a session.
503Teak is temporarily unavailable.Retry with backoff, on the same session.

Retrying is safe: Teak never creates a second order for a session.

4. Start a new session for the next purchase

A session covers one purchase, and expires 2 hours after your last call to the Programs API, or 24 hours after it started. If it expires before the order is placed, price the cart again on a new session, show the customer the new prices, and confirm that. Once you've confirmed the order, clear the session ID from the customer's cart, whatever the response, so their next call to the Programs API starts a new session. See Sessions.

If Teak accepts an order but then can't create it, that session can't be used again. Price the items on a new session, and confirm that.

Next steps

Orders are reaching Teak. Next:

  • After the order: record issued protection and later changes, and give the customer their protection details.
  • Learn how to handle errors from every endpoint, and when to retry.

Did this page help you?