Contract events

A contract is the protection on one item in an order. Teak sends a contract event each time a contract's state changes, one webhook per item. Every contract event has resource: "Policy" and the same data shape. data.status shows the contract's state after the event.

A contract is called a Policy in the API

Contract events have resource: "Policy", each contract is identified by policy_number, and you void or cancel one with the /policies/ endpoints.

When each event fires, every field, and an example payload are in the Contract events reference. This page covers what to do when you receive each one. To make a change yourself, see Change a contract.

Events

Contract Issued

action: "Issued". Required. Store policy_number against the item: you need it to change the contract. Teak invoices you for issued contracts, so these events let you reconcile your orders with your invoice.

Contract Void

action: "Voided". Required. Refund the customer the premium, since you collected it at checkout, and mark the protection as removed in your system. This applies whether the customer voided it (status: "voided") or the order didn't pass Teak's checks (status: "rejected").

Order-level void events

If your account is set up to void whole orders, you can also subscribe to an order-level void event, sent with resource: "Order" and action: "Voided". You still receive a Contract Void for each item, so check resource and refund each item only once.

Contract Canceled

action: "Canceled". Mark the protection as canceled in your system. Don't refund the customer.

Contract Chargeback

action: "Chargeback". Mark the protection as canceled in your system.

Contract On Hold

action: "On_Hold". Show the protection as pending, and watch for a later event with the same policy_number.

Contract Upgraded

action: "Upgraded". Update the item and the protection price in your system.

Contract Downgraded

action: "Downgraded". Required if customers can exchange items. Refund the customer the difference between the original and the new protection price.

Contract Exchanged

action: "Exchanged". Update the item details in your system. The protection price doesn't change.

Next steps

To handle refund requests too, or finish your checkout flow:

Track a customer's refund request from submission to decision with refund request events.
Finish up after checkout: reset the widget, confirm protection was issued, and give the customer their links.