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.
- 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
metadataon 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
| Benefit | What it means for you |
|---|---|
| Protection that fits the purchase | Offer 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 rules | Once you send the metadata, Teak can change which protection each combination gets without a new release from you. |
| Room to test | Checkout Intelligence™ can run more than one protection for the same items and compare how each performs, so your offer improves over time. |
| Safe to add | It'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.
Add metadata to each item in your call to the Programs API:
{
"currency": "USD",
"location": { "country": "US", "region": "TX" },
"items": [
{
"name": "Summer Fest - VIP",
"reference_id": "ITEM-1",
"product_types": ["vip"],
"cost": "149.00",
"event": {
"name": "Summer Fest",
"start_datetime": "2026-07-18T19:00:00-05:00"
},
"metadata": {
"ticket_type": "vip",
"delivery_method": "mobile",
"is_resale": false
}
}
]
}See Price and show protection for the rest of the request.
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.ticketTypedoesn't matchticket_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:
| Type | Example | Rules can check |
|---|---|---|
| String | "vip" | Equals, doesn't equal, contains, is one of a list |
| Number | 4 or "4" | Equals, doesn't equal, greater or less than, between, is one of a list |
| Boolean | true 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 happened | What Teak does |
|---|---|
| A key a rule needs is missing | The rule doesn't match. |
A value is the wrong type, for example "vip" for a number | The rule doesn't match. |
| The item matches no rules | Teak chooses protection the usual way. |
metadata isn't a JSON object | The request is rejected with 422. |
Set it up
- List what you know. Note the details you have about each item at checkout, such as ticket type, seating, delivery, or resale.
- Agree the keys. Your Teak integration contact chooses the keys, their types, and the values to send.
- Send metadata in the sandbox. Add
metadatato your items, and check the protection offered for each combination. - Go live. Teak turns the rules on for your account. After that, Teak can change the rules without a release from you.
Next steps
- See every item field in Widget configuration or Price and show protection.
- Learn how Sessions keep the same protection from search to checkout.
Updated 9 days ago
