Events Reference

This page lists every webhook event TakeTheme can send and the shape of the payload it carries. All events share the same envelope structure; the data.object differs by event.

Envelope

Every delivery, for every event type, is wrapped in this envelope:

{
  "id": "3f1c2b9e-8a4d-4c7e-9b1a-2d6f8e0c1a34",
  "type": "order.paid",
  "created": 1751371200.123,
  "data": {
    "object": { "...": "the order object" }
  }
}

id — unique event ID (UUID). Also sent in the X-TakeTheme-Delivery header. Use it to deduplicate.
type — one of the event types below. Also sent in the X-TakeTheme-Event header.
created — Unix timestamp (seconds) when the event was generated.
data.object — the resource; for all events below, the order object.

Order events

All order events carry the same order object in data.object. The event type tells you what changed; inspect the object's status fields to see the resulting state.

Event	Trigger
`order.placed`	A new order is created (storefront checkout, admin-created order, or draft order completed).
`order.paid`	Payment is captured or the order is manually marked as paid.
`order.fulfilled`	The order — or its remaining items — is marked fulfilled.
`order.cancelled`	The order is cancelled.
`order.returned`	The order is marked as returned.
`order.refunded`	The order is refunded (fully or partially).
`order.updated`	The order is edited (items, address, tracking, notes, hold/release, archive, etc.). Debounced to one delivery per order per ~5s.

Order object

data.object for order events:

Field	Type	Description
`id`	string	The order's unique ID.
`internalId`	string	Human-facing order number (e.g. `1042`). Use this in your UI, not `id`.
`trackNumber`	string	Tracking number (may be empty for some orders).
`status`	string	Order status (e.g. `open`, `cancelled`).
`paymentStatus`	string	Payment state (e.g. `unpaid`, `paid`, `partially_refunded`, `refunded`).
`fulfillmentStatus`	string	Fulfillment state (e.g. `unfulfilled`, `partially_fulfilled`, `fulfilled`).
`totalPrice`	number	Order total in the store's currency.
`currency`	string	ISO currency code (e.g. `EGP`, `USD`).
`payment`	object	Money breakdown — see below.
`discountCode`	string \| null	Coupon code applied, if any.
`appliedDiscounts`	array	Structured automatic + code discounts applied to the order.
`customer`	object	`{ customerId, name, email, phone }` for the order's customer.
`contact`	object	`{ email, phone }` order-level contact (populated for guest/COD orders).
`items`	array	Line items — see below.
`deliveryStatus`	array	Per-item shipment/tracking — see below.
`shippingAddress`	object	The shipping address (may be empty for digital-only orders).
`billingAddressSameAsShipping`	boolean	Whether billing equals shipping.
`note`	string	Merchant/customer order note.
`tags`	array	Order tags.
`origin`	string	Order channel (e.g. `online_store`, admin).
`isDraft`	boolean	Whether the order is a draft.
`isAllDigital`	boolean	Whether every line item is a digital product.
`previousStatus`	string \| null	Prior status — handy for detecting the transition on `order.updated`.
`createdAt`	string (ISO 8601)	When the order was created.

payment:

Field	Type	Description
`subTotal`	number	Items subtotal before shipping/tax/discounts.
`shipping`	number	Shipping charged.
`tax`	number	Tax charged.
`discountAmount`	number	Total discount applied.
`handlingFee`	number	Handling/COD fee.
`total`	number	Grand total (equals `totalPrice`).
`method`	string	Payment method (e.g. `cod`, `card`).
`provider`	string \| null	Payment provider/gateway.
`refundedAmount`	number	Amount refunded so far (for refund/return events).
`refundedShipping`	number	Shipping refunded so far.

Each entry in items:

Field	Type	Description
`id`	string	The order line's ID (correlates with `deliveryStatus.itemId`).
`productId`	string	The product's ID (`null` for ad-hoc / custom items).
`name`	string	Product name at time of order.
`quantity`	number	Quantity ordered.
`price`	number	Unit price charged.
`discountPrice`	number \| null	Original (strikethrough) unit price, when discounted.
`image`	string \| null	Line item thumbnail URL.
`variantId`	string \| null	Selected variant ID.
`variantLabel`	string \| null	Human label for the variant (e.g. `Size: L • Color: Blue`).
`variantDetails`	array	`[{ optionName, value }]` for the selected variant.
`isPhysicalProduct`	boolean	Whether the line requires shipping.
`isCustomItem`	boolean	Whether it's an ad-hoc/custom line.
`customInputValue`	string \| null	Buyer personalization (e.g. engraving text).
`removed`	boolean	`true` if the line was removed after fulfilment — filter these out when reconciling to `totalPrice`.
`fulfillmentStatus`	string	Per-line fulfilment state.

Each entry in deliveryStatus:

Field	Type	Description
`itemId`	string	The order line this shipment covers.
`trackingNumber`	string \| null	Carrier tracking number.
`trackingUrl`	string \| null	Carrier tracking URL.
`trackingCompany`	string \| null	Carrier name.
`deliveryStatus`	string \| null	Carrier-reported delivery state.

What's intentionally omitted

For privacy and security the payload excludes internal/sensitive fields: ad-tracking identifiers (fbc/fbp/IP/user-agent), conversion attribution, fraud/risk scoring, digital download tokens, the internal timeline, and staff assignment. Fetch the order by ID from the Orders API if you need more.

Example: `order.paid`

{
  "id": "3f1c2b9e-8a4d-4c7e-9b1a-2d6f8e0c1a34",
  "type": "order.paid",
  "created": 1751371200.123,
  "data": {
    "object": {
      "id": "665f1b2c9a3e4d0012ab34cd",
      "internalId": "1042",
      "trackNumber": "TT-1042",
      "status": "open",
      "paymentStatus": "paid",
      "fulfillmentStatus": "unfulfilled",
      "totalPrice": 349.99,
      "currency": "EGP",
      "payment": {
        "subTotal": 329.99,
        "shipping": 20,
        "tax": 0,
        "discountAmount": 0,
        "handlingFee": 0,
        "total": 349.99,
        "method": "card",
        "provider": "kashier",
        "refundedAmount": 0,
        "refundedShipping": 0
      },
      "discountCode": null,
      "appliedDiscounts": [],
      "customer": {
        "customerId": "665d9f0a9a3e4d0012a9f0aa",
        "name": "Mona Adel",
        "email": "mona@example.com",
        "phone": "+201000000000"
      },
      "contact": { "email": "mona@example.com", "phone": "+201000000000" },
      "items": [
        {
          "id": "665f1b2c9a3e4d0012ab3500",
          "productId": "665e0a1b9a3e4d0012aa11bb",
          "name": "Linen Shirt — Medium",
          "quantity": 2,
          "price": 174.995,
          "discountPrice": null,
          "image": "https://cdn.example.com/linen-shirt.jpg",
          "variantId": "665e0a1b9a3e4d0012aa11cc",
          "variantLabel": "Size: M",
          "variantDetails": [{ "optionName": "Size", "value": "M" }],
          "isPhysicalProduct": true,
          "isCustomItem": false,
          "customInputValue": null,
          "removed": false,
          "fulfillmentStatus": "unfulfilled"
        }
      ],
      "deliveryStatus": [],
      "shippingAddress": {
        "name": "Mona Adel",
        "street": "12 Nile St.",
        "city": "Cairo",
        "state": "Cairo",
        "country": "EG"
      },
      "billingAddressSameAsShipping": true,
      "note": "",
      "tags": [],
      "origin": "online_store",
      "isDraft": false,
      "isAllDigital": false,
      "previousStatus": "open",
      "createdAt": "2026-07-01T12:00:00.000Z"
    }
  }
}

Example: `order.fulfilled`

Same object shape; note the changed fulfillmentStatus:

{
  "id": "a2b9c1d0-7e6f-4a3b-8c2d-1f0e9d8c7b6a",
  "type": "order.fulfilled",
  "created": 1751374800.501,
  "data": {
    "object": {
      "id": "665f1b2c9a3e4d0012ab34cd",
      "internalId": "1042",
      "trackNumber": "TT-1042",
      "status": "open",
      "paymentStatus": "paid",
      "fulfillmentStatus": "fulfilled",
      "totalPrice": 349.99,
      "currency": "EGP",
      "customer": { "customerId": "665d9f0a9a3e4d0012a9f0aa", "name": "Mona Adel", "email": "mona@example.com", "phone": "+201000000000" },
      "items": [
        { "id": "665f1b2c9a3e4d0012ab3500", "productId": "665e0a1b9a3e4d0012aa11bb", "name": "Linen Shirt — Medium", "quantity": 2, "price": 174.995, "fulfillmentStatus": "fulfilled" }
      ],
      "deliveryStatus": [
        { "itemId": "665f1b2c9a3e4d0012ab3500", "trackingNumber": "EG123456789", "trackingUrl": "https://track.bosta.co/EG123456789", "trackingCompany": "Bosta", "deliveryStatus": "in_transit" }
      ],
      "shippingAddress": { "city": "Cairo", "country": "EG" },
      "createdAt": "2026-07-01T12:00:00.000Z"
    }
  }
}

Handling events

Branch on type and read the status fields you care about:

switch (event.type) {
  case "order.placed":
    // Reserve inventory, create a record in your system.
    break;
  case "order.paid":
    // Trigger fulfillment / accounting.
    break;
  case "order.fulfilled":
    // Notify the customer, close the fulfillment task.
    break;
  case "order.cancelled":
  case "order.returned":
  case "order.refunded":
    // Reverse inventory / issue store credit / update ledgers.
    break;
  case "order.updated":
    // Re-sync the order snapshot from event.data.object.
    break;
  default:
    // Unknown/future event type — acknowledge and ignore.
    break;
}

Forward-compatibility

New event types may be added over time. Always acknowledge unrecognized type values with a 2xx and ignore them, rather than erroring — this keeps your endpoint healthy and avoids auto-disable.

Envelope​

Order events​

Order object​

Example: order.paid​

Example: order.fulfilled​

Handling events​