Custom Metadata

Send details about each item, like ticket type or delivery method, so Teak offers the protection that fits it.

Custom metadata is a set of details you send about each item, such as the ticket type, the seating, or how the tickets are delivered. Teak uses it to choose the refund protection that fits that item, and leaves everything else about your integration as it is.

{
  "name": "Summer Fest - VIP",
  "metadata": {
    "ticket_type": "vip",
    "delivery_method": "mobile",
    "is_resale": false
  }
}

Without metadata, Teak chooses protection by the item's product type, the customer's location, and the event's timing. With metadata, it can also take into account anything you know about the item when the customer buys it.

Custom metadata is part of Checkout Intelligence™, Teak's way of fitting the offer to each customer. Checkout Intelligence™ shapes the protection, product, and price behind your offer, and the more Teak knows about each item, the closer that fit can be.

The short version
  • Teak sets up the rules. Your Teak integration contact agrees the keys with you and decides which protection each combination gets.
  • You add one field. Send metadata on each item, with the keys and values you agreed.
  • Nothing breaks without it. If metadata is missing or doesn't match a rule, Teak chooses protection the usual way.

Why use it

BenefitWhat it means for you
Protection that fits the purchaseOffer different protection to a VIP package and a general admission ticket, to a resale ticket and a primary one, or to mobile and will-call delivery, all for the same event.
No code change for new rulesOnce you send the metadata, Teak can change which protection each combination gets without a new release from you.
Room to testCheckout Intelligence™ can run more than one protection for the same items and compare how each performs, so your offer improves over time.
Safe to addIt's an optional field. Items without metadata are offered protection exactly as they are today.

How Teak uses it

Teak takes the item's metadata into account alongside its product type, the customer's location, and the event's timing when it chooses protection.

A rule compares one key in the item's metadata to a value, for example ticket_type equals vip, and decides which protection the item is offered. If an item matches no rules, Teak chooses protection the usual way, so it's never left without an offer because of its metadata.

Teak can also write rules about the cart itself, such as the cart total, the number of items, or the average item cost. It works those out from the items you send, so you don't add them to metadata.

Send metadata

Add metadata to each item. Use the keys and values your Teak integration contact gave you.

Add metadata to each item in configure:

teak('configure', {
  apiKey: 'pk_...',
  items: [
    {
      name: 'Summer Fest - VIP',
      referenceNumber: 'ITEM-1',
      productTypes: ['vip'],
      cost: 149.0,
      event: {
        name: 'Summer Fest',
        startDatetime: '2026-07-18T19:00:00-05:00',
      },
      metadata: { ticket_type: 'vip', delivery_method: 'mobile' },
    },
  ],
});

The widget sends the keys exactly as you write them. It doesn't change their case.

Send the same metadata for an item on every call in the session. Teak checks the rules on each call, so if an item's metadata changes, the protection Teak picks for it can change too.

Keys

  • Use the keys exactly as agreed. Keys are matched exactly, and Teak's keys are lowercase: letters, digits, underscores, and dots, such as ticket_type. ticketType doesn't match ticket_type.
  • Keep it flat. Teak matches top-level keys only. Send "delivery_method": "mobile", not "delivery": { "method": "mobile" }.
  • Extra keys are fine. Teak ignores keys it has no rules for, so you can send a key before a rule uses it.
  • Don't send personal data. Describe the item, not the customer: no names, email addresses, or phone numbers.

Values

Each key has a type, agreed when it's set up. Send values of that type:

TypeExampleRules can check
String"vip"Equals, doesn't equal, contains, is one of a list
Number4 or "4"Equals, doesn't equal, greater or less than, between, is one of a list
Booleantrue or "true"Equals, doesn't equal
Date"2026-07-18"Equals, doesn't equal, before or after, between

Teak reads numbers and booleans sent as strings, such as "4" or "true". Any rule can also check whether a key is present or missing.

What happens if something is off

What happenedWhat Teak does
A key a rule needs is missingThe rule doesn't match.
A value is the wrong type, for example "vip" for a numberThe rule doesn't match.
The item matches no rulesTeak chooses protection the usual way.
metadata isn't a JSON objectThe request is rejected with 422.

Set it up

  1. List what you know. Note the details you have about each item at checkout, such as ticket type, seating, delivery, or resale.
  2. Agree the keys. Your Teak integration contact chooses the keys, their types, and the values to send.
  3. Send metadata in the sandbox. Add metadata to your items, and check the protection offered for each combination.
  4. Go live. Teak turns the rules on for your account. After that, Teak can change the rules without a release from you.

Next steps


Did this page help you?