Price and show protection

Price protection with the Programs API, and show the offer in your own interface.

Deprecated in 2027

The Programs API and the current way of placing server-to-server orders will be deprecated in 2027. The four integration steps stay the same. See Coming soon.

Your server sends items to the Programs API, and Teak returns a protection price for each one. Call it wherever you show protection, for example next to each result on a search page and for the customer's cart at checkout. You show the offer in your own interface.

1. Get an access token

Exchange your API keys for an access token with Create an access token. Tokens expire after 5 minutes. Your server calls Teak several times during a purchase, so reuse one token until it's close to expiring, and get a new one if a call returns 401.

The code on this page uses getTeakToken() and TEAK_API from Reuse the token.

2. Build the request

{
  "session_id": "3f1c9a2e-8b4d-4e6f-9a0b-1c2d3e4f5a6b",
  "currency": "USD",
  "locale": "en_US",
  "location": { "country": "US", "region": "TX" },
  "items": [
    {
      "name": "Summer Fest - General Admission",
      "reference_id": "ITEM-1",
      "product_types": ["general-admission"],
      "cost": "57.50",
      "event": {
        "name": "Summer Fest",
        "start_datetime": "2026-07-18T19:00:00-05:00",
        "end_datetime": "2026-07-18T23:00:00-05:00"
      }
    },
    {
      "name": "Summer Fest - VIP",
      "reference_id": "ITEM-2",
      "product_types": ["general-admission"],
      "cost": "149.00",
      "event": {
        "name": "Summer Fest",
        "start_datetime": "2026-07-18T19:00:00-05:00",
        "end_datetime": "2026-07-18T23:00:00-05:00"
      }
    }
  ]
}

Every field is required except session_id.

FieldDescription
session_idThe session for this purchase, from your first response from the Programs API. Leave it out on the first call, and Teak starts one. A session lasts 2 hours after your last call, and no more than 24 hours. See Sessions.
currencyISO 4217 code, such as USD. Use the same one for every call in the session.
localeThe language and region for the response, such as en_US.
locationWhere the customer is. See Send the customer's location.
itemsThe items to price: one or many, for example a page of search results, or every item in the cart.

For each item, every field is required:

FieldDescription
nameThe item's name, as the customer sees it.
reference_idYour ID for the item. It comes back with its price, and in webhooks as reference_number. Give each item in a call its own reference_id.
product_typesYour product types for the item. Teak maps them to protection when your account is set up.
costThe price of one item, as a string such as "57.50". Include its share of taxes and fees, but not protection. A number returns 422, and items that cost "0" are left out.
event.nameWhat the customer is buying protection for, such as the event or trip.
event.start_datetime, event.end_datetimeISO 8601 times with their UTC offset, such as 2026-07-18T19:00:00-05:00. Send at least one. See Event times.

Event times

Teak uses each item's start and end times to decide which protection applies, because some protection depends on when the event is and how long it lasts. So:

  • Always include the UTC offset, for example 2026-07-18T19:00:00-05:00, or send the time in UTC with Z. A time without an offset is read as UTC, which can move the event by several hours.
  • Convert from the event's own time zone, not your server's.
  • Send at least one of the two. Without an end, Teak assumes the event ends 48 hours after it starts when choosing protection. An end before the start returns 422.

Send the customer's location

Teak only offers protection that's available where the customer is. Without the widget, Teak can't read this from a browser, so you send it in location. Send at least one of these. Teak uses the first one it can resolve, in this order:

FieldExampleNotes
country and region"US" and "TX"Strongly preferred, because it's the most reliable. country is an ISO 3166-1 alpha-2 code. region is the state or province code without the country prefix, and is required in the US and Canada.
ip_address"203.0.113.24"The customer's IPv4 or IPv6 address, not your server's.

If Teak can't resolve a location from what you send, the Programs API returns 422.

3. Call the Programs API

// items is your own list of results or cart items. getTeakToken() and TEAK_API: see Reuse the token.
async function getPrograms(items, customer, sessionId) {
  const res = await fetch(`${TEAK_API}/programs`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${await getTeakToken()}`,
    },
    body: JSON.stringify({
      session_id: sessionId || undefined,  // left out on the first call
      currency: 'USD',
      locale: 'en_US',
      location: { country: customer.country, region: customer.region },
      items: items.map((item) => ({
        name: item.name,
        reference_id: item.id,
        product_types: [item.productType],
        cost: item.price.toFixed(2),         // a string, not a number
        event: {
          name: item.eventName,
          start_datetime: item.startsAt,     // ISO 8601 with a UTC offset
          end_datetime: item.endsAt,
        },
      })),
    }),
    signal: AbortSignal.timeout(2000),       // never hold up your page
  });
  if (!res.ok) throw new Error(`Teak Programs API call failed: ${res.status}`);
  return res.json();
}
# items is your own list of results or cart items. get_teak_token() and TEAK_API: see Reuse the token.
def get_programs(items, customer, session_id=None):
    body = {
        "currency": "USD",
        "locale": "en_US",
        "location": {"country": customer["country"], "region": customer["region"]},
        "items": [
            {
                "name": item["name"],
                "reference_id": item["id"],
                "product_types": [item["product_type"]],
                "cost": f"{item['price']:.2f}",  # a string, not a number
                "event": {
                    "name": item["event_name"],
                    "start_datetime": item["starts_at"],  # ISO 8601 with a UTC offset
                    "end_datetime": item["ends_at"],
                },
            }
            for item in items
        ],
    }
    if session_id:  # left out on the first call
        body["session_id"] = session_id
    res = requests.post(
        f"{TEAK_API}/programs",
        headers={"Authorization": f"Bearer {get_teak_token()}"},
        json=body,
        timeout=2,  # never hold up your page
    )
    res.raise_for_status()
    return res.json()
# TEAK_ACCESS_TOKEN is an access token from Create an access token.
curl https://api.sandbox.helloteak.com/v1/programs \
  -H "Authorization: Bearer $TEAK_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "USD",
    "locale": "en_US",
    "location": { "country": "US", "region": "TX" },
    "items": [
      {
        "name": "Summer Fest - General Admission",
        "reference_id": "ITEM-1",
        "product_types": ["general-admission"],
        "cost": "57.50",
        "event": {
          "name": "Summer Fest",
          "start_datetime": "2026-07-18T19:00:00-05:00",
          "end_datetime": "2026-07-18T23:00:00-05:00"
        }
      }
    ]
  }'

The response:

{
  "session_id": "3f1c9a2e-8b4d-4e6f-9a0b-1c2d3e4f5a6b",
  "currency": "USD",
  "items": [
    { "reference_id": "ITEM-1", "premium": "4.60", "premium_literal": "$4.60" },
    { "reference_id": "ITEM-2", "premium": "11.92", "premium_literal": "$11.92" }
  ]
}
FieldWhat to do with it
session_idKeep it with the customer's cart. Send it on every later call for this purchase.
items[].reference_idMatch each price to your item.
items[].premium, premium_literalThe item's protection price, as a decimal string and formatted for display.

For the same item on the same session, the price from the Programs API is the price the customer confirms. If an item changes, for example its cost or event times, call the Programs API again.

If any item can't be priced, for example because its product type isn't mapped, the whole call fails and the error names the item. Fix or leave out that item, and call again.

Set a short client timeout, so a slow call never holds up your page. If the call fails or times out, show the page without a protection price.

Handle errors

The Programs API returns a standard HTTP status with a { "msg", "type" } body, or a list of field errors when the request body is invalid.

ResponseMeaningWhat to do
400Teak couldn't convert the price to your currency.Show the page without protection, and retry later.
401The access token is missing or expired.Get a new token and retry once.
403Your account isn't set up for pricing yet, 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.
404Teak has no protection or pricing for an item. The message names it.Check the item's product_types with your Teak integration contact.
422An unknown product type, a location Teak can't resolve, an invalid session_id, a cost over the coverage limit, or an invalid field.Fix the request. The msg or field list says what's wrong.

If you can't get a price, let the customer complete their purchase without protection. See the Programs API for an example of every error, and Error handling for retries.

4. Show the offer

Without the widget, you show the offer in your own interface. Use the prices from the Programs API exactly as returned, and keep the offer next to the order total so the customer sees what they'll pay.

  • Optional protection: show the price, what the protection covers, and a way to accept or decline it. Add the price to the order total only if the customer accepts.
  • Embedded protection: the price is already part of the item's price. Tell the customer that protection is included.

5. Price again when the cart changes

Call the Programs API again, with the same session_id, whenever the cart changes: an item is added or removed, or an item's cost or event times change. Show the new prices before the customer completes their purchase.

Next steps

The customer has seen the offer. Next:

  • Confirm the order when the customer completes their purchase.
  • Learn how a session carries the purchase from the first price to the order.

Did this page help you?