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.
- One session per purchase. Send its
session_idon 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
| Step | What happens to the session |
|---|---|
| 1. Offer | Your 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 order | Records the customer's choices and places the order. Teak issues protection for each protected item. The session is closed. |
| 3. Notify | Teak's webhooks for the order carry your order number and each item's reference_id. |
See the server-to-server guide for each step.
The widget creates the session when it loads, prices the cart, and saves the customer's choice for you. teak.get('token') returns the session ID, which your server sends to Submit an order.
To start the session yourself, pass your own UUID as sessionId.
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 session | What it means for you |
|---|---|
| The same protection throughout | Teak reuses the protection it picked earlier in the session, so the protection on search results is the protection at checkout. |
| Stable prices | For 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 order | Retrying can't create a second order. If Teak says the order was already placed, an earlier attempt was accepted. |
| It belongs to one account | A 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 this | Why |
|---|---|
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 happened | What to do |
|---|---|
| Your first call to the Programs API got no response | Call 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 placed | Call 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 placed | Teak already has the order. Treat it as accepted, not as a failure. |
| Teak couldn't create the order after accepting it | That session can't be used again. Price the items on a new session, and confirm that. |
Next steps
- See what to send for each item in Price and show protection.
- Learn how to handle errors from every endpoint.
Updated 9 days ago
