Sessions

How a session carries one customer's purchase from the first price they see to the order you place.

A session is one customer's purchase, from the first price they see to the order you place. It holds the protection Teak picked for each item, its price, and the customer's choices. When the order is placed, the session ID becomes the Teak order ID.

The short version
  • One session per purchase. Send its session_id on every call for that purchase.
  • Sessions expire. On the server-to-server path, a session lasts 2 hours after your last call to the Programs API, and no more than 24 hours after it started.
  • Never reuse a session once the order is placed, whatever the response.
  • Start the next purchase without a session ID, and Teak starts a new one.

The life of a session

StepWhat happens to the session
1. OfferYour first call to the Programs API without a session_id creates the session. Teak records which protection it picked for each item. Call it as often as you like with the same session_id, for example once per search and again for the cart.
2. Confirm the orderRecords the customer's choices and places the order. Teak issues protection for each protected item. The session is closed.
3. NotifyTeak's webhooks for the order carry your order number and each item's reference_id.

See the server-to-server guide for each step.

How long a session lasts

On the server-to-server path, a session stays usable for 2 hours after your last call to the Programs API, and never more than 24 hours after it started. Each call to the Programs API on the session extends it, up to the 24-hour limit.

An expired session can't be revived. Start a new one by calling the Programs API without a session_id, and show the customer the new prices before they complete their purchase.

To keep the session current through checkout, call the Programs API for the cart when the customer reaches checkout. See Price again when the cart changes.

What you can rely on

Within a sessionWhat it means for you
The same protection throughoutTeak reuses the protection it picked earlier in the session, so the protection on search results is the protection at checkout.
Stable pricesFor an unchanged item, the price the customer confirms is the price you showed. If the item changes, for example its cost or event times, price it again. You never send prices when you place the order.
At most one orderRetrying can't create a second order. If Teak says the order was already placed, an earlier attempt was accepted.
It belongs to one accountA call with another account's keys gets 403. If you're a partner with several clients, use the same client's keys for every call on a session.

Rules to follow

Do thisWhy
Send the session_id from your first response on every later call for the purchase.Teak keeps the same protection from search to checkout.
Send the same currency on every call in a session.A session is priced in one currency.
Don't use a session again once the order is placed, whatever the response.The session is closed. Start a new one for the next purchase.
Don't share a session between customers or purchases.Each session becomes one order.
Start a new session if the current one has expired.An expired session can't be revived or used to place an order.

When something goes wrong

What happenedWhat to do
Your first call to the Programs API got no responseCall it again without a session ID, and use the session_id from the response you receive. The session from the lost call is never used.
The session expired before the order was placedCall the Programs API for the cart without a session ID, show the customer the new prices, and confirm the order on the new session.
Teak says the order was already placedTeak already has the order. Treat it as accepted, not as a failure.
Teak couldn't create the order after accepting itThat session can't be used again. Price the items on a new session, and confirm that.

Next steps


Did this page help you?