Configuration options

Pass options to the configure command:

teak('configure', {
  apiKey: 'pk_...',                                      // required
  sandbox: true,
  currency: 'USD',
  locale: 'en_US',
  sessionId: '3f1c9a2e-8b4d-4e6f-9a0b-1c2d3e4f5a6b',     // optional: your own session ID
  persist: true,
  source: 'general',                                     // only if your Teak integration contact asks
  items: [                                               // required
    {
      name: 'Summer Fest - General Admission',
      referenceNumber: 'ITEM-1',
      productTypes: ['general-admission'],
      cost: 120.0,
      event: {
        name: 'Summer Fest',
        location: 'Austin, TX',
        startDatetime: '2026-07-18T18:00:00-05:00',
        endDatetime: '2026-07-18T23:00:00-05:00',
      },
      metadata: { ticketType: 'GA' },                    // only if your Teak integration contact asks
    },
  ],
  loadedCb: (context) => {},
  optInCb: (context) => {},
  optOutCb: (context) => {},
  updatedCb: (context) => {},
  onErrorCb: (sessionId) => {},
});

This example uses every option and item field. Only apiKey and items are required; each one is described below.

Call configure again at any time to update the widget, for example when the cart changes. Each call can change any option. Always pass the full list of items, not only the ones that changed.

Options

Options not listed here have no effect in the TeakOS Widget. An unrecognized option is ignored, with a message in the browser console.

Items

Pass one item for each thing the customer is buying. Two tickets are two items.

Product types

Product types let you offer different refund protection for each kind of product you sell. For example, general admission tickets can have one protection offer, VIP packages another, and parking a third.

A product type is how your inventory system labels a product, for example general-admission, vip, or parking. During onboarding, your Teak integration contact works with you to list your product types and decide the refund protection for each one. Teak then maps each product type to its protection, so you send the same labels you use internally, and each item is quoted for the protection its product type maps to.

Items in the same cart can have different product types, and each is quoted for its own protection.

Every item needs a product type. Set it in one of two ways:

• On each item, with productTypes. Use this when items in the same cart need different products.

  JavaScript

  items: [
    {
      name: 'Summer Fest - General Admission',
      referenceNumber: 'ITEM-1',
      productTypes: ['general-admission'],   // your inventory system's label for this product
      cost: 120.0,
      event: { location: 'Austin, TX' },
    },
  ],

• On the widget element, with its id. Items without their own productTypes use the id of every widget element on the page.

  HTML

  <teak-widget id="general-admission"></teak-widget>

An item's own productTypes take precedence over element ids.

If you send a product type Teak hasn't mapped for your account, the widget shows no offer for it, without an error or a console message. When you add a new kind of product to your inventory, ask your Teak integration contact to map it before you send it. See A product type isn't mapped.

Session ID

The widget creates a session ID when it loads. To use your own instead, pass a UUID as sessionId in configure, for example one you create with crypto.randomUUID(). preload doesn't take it.

teak('configure', {
  apiKey: 'pk_...',
  sessionId: '3f1c9a2e-8b4d-4e6f-9a0b-1c2d3e4f5a6b',   // your UUID for this checkout
  items: [ /* ... */ ],
});

Pass your own session ID to:

• Match the session to your records. The ID you pass is the session ID you submit, and it becomes the Teak order ID. You can store it with your cart from the start, and find the same session in your logs and in Teak.
• Continue a session on another page or device. Pass the same sessionId in configure there, and the widget carries on with the same session.

teak.get('token') returns the ID you passed, so you submit the order as usual. To switch to a different session, call configure again with a different sessionId.

sessionId must be a UUID in its standard form: 32 hexadecimal characters in groups of 8-4-4-4-12, for example 3f1c9a2e-8b4d-4e6f-9a0b-1c2d3e4f5a6b. Uppercase letters are accepted. If it isn't valid, the widget logs E4014 and ignores it: the rest of your configure call still applies, on the session the widget already has. That's a new session, or the one stored in the browser, the same as when you leave sessionId out. Checkout isn't affected.

Locales

A language code on its own maps to a default region: en to en_US, es to es_ES, fr to fr_FR, de to de_DE, it to it_IT, nl to nl_NL, pt to pt_BR, and sv to sv_SE.

Next steps

With the widget configured:

• Control the widget with commands and methods, and read its state.
• Look up any code in widget error codes, with its cause and fix.