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.
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:
- 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.
| Detail | Description |
|---|---|
| Your order number | Sent as reference_id. It must be unique across your orders: Teak uses it to match webhooks and lookups to your order. |
| The customer | The 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 address | Recommended. Teak uses it to confirm where the customer is located. |
| Payment | Always { "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:
| Outcome | When | What to do |
|---|---|---|
202 Accepted | At 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 Content | No item is protected, for example the customer declined everything. No order is created. | Nothing. This is a normal outcome, not an error. |
| Already placed | An 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 422 | The request is invalid, for example a required detail is missing. | Fix the request. The message says what's wrong. Don't retry it unchanged. |
401 | The access token is missing or expired. | Get a new token and retry once. |
403 | TeakOS 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. |
503 | Teak 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.
Updated 9 days ago
