Webhook Events

Event Types

Shoppex supports order, subscription, product, query, feedback, and affiliate webhooks. Event names use colons as separators, like order:paid.

When creating webhooks through the Dev API, send explicit event names like order:paid — wildcard patterns like invoice.* are not supported. Fetch the full allowlist from GET /dev/v1/webhooks/events.

These event payloads are not the same as the dynamic_webhook callback used by DYNAMIC products. For that contract, see Dynamic Product Delivery.

Supported Event Names

Order Events
Subscription Events
Reseller Events
Other Events

Event	Description
`order:created`	Order created
`order:updated`	Order updated
`order:partial`	Partial payment received
`order:paid`	Order fully paid
`order:cancelled`	Order cancelled or expired
`order:disputed`	Order dispute opened
`order:created:product`	Order created with product payload
`order:updated:product`	Order updated with product payload
`order:partial:product`	Partial payment with product payload
`order:paid:product`	Paid order with product payload
`order:cancelled:product`	Cancelled order with product payload
`order:disputed:product`	Disputed order with product payload
`order:manual_payment_pending`	Manual payment review required

For paid product purchases, subscribe to order:paid or order:paid:product. If that purchase reduces available stock, Shoppex does not emit a separate product:stock event for the same checkout.

Payload Families

Invoice Payload

These events use the same base invoice payload shape as order:paid:

order:created
order:updated
order:partial
order:paid
order:cancelled
order:disputed
order:manual_payment_pending

Invoice Payload With Products

These events use the same invoice payload plus the products array, like order:paid:product:

order:created:product
order:updated:product
order:partial:product
order:paid:product
order:cancelled:product
order:disputed:product

Example Payloads

order:paid

Triggered when an order/invoice is successfully paid.

{
  "event": "order:paid",
  "data": {
    "uniqid": "abc123def456",
    "type": "PRODUCT",
    "status": "COMPLETED",
    "gateway": "STRIPE",
    "total": 49.99,
    "total_display": 49.99,
    "currency": "USD",
    "exchange_rate": 1,
    "crypto_exchange_rate": 0,
    "crypto_gateway": null,
    "apm_method": "CARD",
    "customer_email": "[email protected]",
    "country": "US",
    "quantity": 1,
    "product_id": "prod_xyz",
    "product_title": "Pro License",
    "is_developer_invoice": false,
    "created_at": "2026-01-15T09:10:00.000Z",
    "updated_at": "2026-01-15T10:10:00.000Z"
  },
  "created_at": 1705318200
}

Dashboard simulation for order:paid uses this same envelope shape and the same core fields, just with synthetic values.

order:cancelled

Triggered when an order is cancelled or expires.

{
  "event": "order:cancelled",
  "data": {
    "uniqid": "abc123def456",
    "type": "PRODUCT",
    "status": "VOIDED",
    "gateway": null,
    "total": 49.99,
    "total_display": 49.99,
    "currency": "USD",
    "exchange_rate": 1,
    "crypto_exchange_rate": 0,
    "crypto_gateway": null,
    "apm_method": null,
    "customer_email": "[email protected]",
    "product_id": "prod_xyz",
    "product_title": "Pro License",
    "created_at": "2026-01-15T09:10:00.000Z",
    "updated_at": "2026-01-16T09:03:20.000Z"
  },
  "created_at": 1705400600
}

order:paid:product

Same as order:paid but includes full product details in the payload.

{
  "event": "order:paid:product",
  "data": {
    "uniqid": "abc123def456",
    "type": "PRODUCT",
    "status": "COMPLETED",
    "gateway": "STRIPE",
    "total": 49.99,
    "total_display": 49.99,
    "currency": "USD",
    "exchange_rate": 1,
    "crypto_exchange_rate": 0,
    "crypto_gateway": null,
    "apm_method": "CARD",
    "customer_email": "[email protected]",
    "product_id": "prod_xyz",
    "product_title": "Pro License",
    "products": [
      {
        "uniqid": "prod_xyz",
        "title": "Pro License",
        "description": "Full access to all features",
        "price": 49.99,
        "price_display": 49.99,
        "currency": "USD",
        "type": "SERVICE"
      }
    ],
    "created_at": "2026-01-15T09:10:00.000Z",
    "updated_at": "2026-01-15T10:10:00.000Z"
  },
  "created_at": 1705318200
}

order:cancelled:product

Same as order:cancelled but includes full product details.

order:manual_payment_pending

Triggered when Shoppex is waiting for an offline or manual payment review.

{
  "event": "order:manual_payment_pending",
  "data": {
    "uniqid": "abc123def456",
    "type": "PRODUCT",
    "status": "PENDING",
    "gateway": "MANUAL",
    "total": 49.99,
    "total_display": 49.99,
    "currency": "USD",
    "exchange_rate": 1,
    "crypto_exchange_rate": 0,
    "crypto_gateway": null,
    "apm_method": null,
    "customer_email": "[email protected]",
    "country": "US",
    "quantity": 1,
    "product_id": "prod_xyz",
    "product_title": "Pro License",
    "is_developer_invoice": false,
    "created_at": "2026-01-15T09:10:00.000Z",
    "updated_at": "2026-01-15T09:20:00.000Z"
  },
  "created_at": 1705315200
}

Event	Description
`subscription:trial:started`	Trial started
`subscription:trial:ended`	Trial ended
`subscription:created`	Subscription created
`subscription:updated`	Subscription updated
`subscription:renewed`	Subscription renewed
`subscription:cancelled`	Subscription cancelled
`subscription:upcoming`	Upcoming renewal reminder
`subscription:trial:started:product`	Trial started with product payload
`subscription:trial:ended:product`	Trial ended with product payload
`subscription:created:product`	Subscription created with product payload
`subscription:updated:product`	Subscription updated with product payload
`subscription:renewed:product`	Subscription renewed with product payload
`subscription:cancelled:product`	Subscription cancelled with product payload
`subscription:upcoming:product`	Upcoming renewal with product payload

Payload Family

These events use the same subscription payload shape as subscription:created:

subscription:trial:started
subscription:trial:ended
subscription:created
subscription:updated
subscription:renewed
subscription:cancelled
subscription:upcoming
subscription:trial:started:product
subscription:trial:ended:product
subscription:created:product
subscription:updated:product
subscription:renewed:product
subscription:cancelled:product
subscription:upcoming:product

Example Payloads

subscription:created

Triggered when a new subscription starts.

{
  "event": "subscription:created",
  "data": {
    "id": "sub_abc123",
    "status": "ACTIVE",
    "gateway": "STRIPE",
    "customer_id": "cust_xyz789",
    "current_period_start": "2026-01-15T00:00:00.000Z",
    "current_period_end": "2026-02-15T00:00:00.000Z",
    "created_at": "2026-01-15T00:00:00.000Z"
  },
  "created_at": 1705314600
}

subscription:cancelled

Triggered when a subscription is cancelled.

{
  "event": "subscription:cancelled",
  "data": {
    "id": "sub_abc123",
    "status": "CANCELLED",
    "gateway": "STRIPE",
    "customer_id": "cust_xyz789",
    "current_period_start": "2026-01-15T00:00:00.000Z",
    "current_period_end": "2026-02-15T00:00:00.000Z",
    "created_at": "2026-01-15T00:00:00.000Z"
  },
  "created_at": 1705918200
}

subscription:renewed

Triggered when a subscription renews for a new billing period.

{
  "event": "subscription:renewed",
  "data": {
    "id": "sub_abc123",
    "status": "ACTIVE",
    "gateway": "STRIPE",
    "customer_id": "cust_xyz789",
    "current_period_start": "2026-02-15T00:00:00.000Z",
    "current_period_end": "2026-03-15T00:00:00.000Z",
    "created_at": "2026-01-15T00:00:00.000Z"
  },
  "created_at": 1707991800
}

Event	Description
`reseller:invited`	Reseller invitation created
`reseller:accepted`	Reseller accepted an invitation
`reseller:suspended`	Reseller relationship suspended
`reseller:terminated`	Reseller relationship terminated
`reseller:embed_campaign_created`	Reseller created an embed campaign
`reseller:embed_campaign_updated`	Reseller embed campaign changed status or metadata
`reseller:sale`	Invoice sale attributed to a reseller
`reseller:payout_requested`	Reseller requested a payout
`reseller:stock_purchase_requested`	Reseller requested wholesale stock
`reseller:stock_purchase_paid`	Stock purchase invoice was paid
`reseller:stock_purchase_revoked`	Stock purchase request was revoked
`reseller:stock_allocated`	Stock was allocated to reseller inventory
`reseller:stock_item_delivered`	Reseller delivered an inventory item to an end customer

Payload Notes

Reseller webhook payloads are merchant-scoped. They include stable IDs plus snapshots needed by external systems.For example:

relationship_id identifies the reseller relationship with the merchant.
reseller_user_id identifies the reseller user.
campaign_id or embed_campaign_id identifies a reseller-owned embed campaign when available.
Stock events use transfer_id and inventory delivery events use item_id.

Example Payloads

reseller:sale

Triggered when a completed invoice is attributed to a reseller link or reseller-owned embed.

{
  "event": "reseller:sale",
  "data": {
    "relationship_id": "rel_123",
    "reseller_user_id": "usr_123",
    "invoice_id": "inv_db_123",
    "invoice_uniqid": "abc123def456",
    "affiliate_link_id": "aff_123",
    "embed_campaign_id": "emb_123",
    "product_id": "prod_123",
    "variant_id": "var_123",
    "retail_amount": 49.99,
    "commission_amount": 5,
    "currency": "USD",
    "mode": "AFFILIATE"
  },
  "created_at": 1777111200
}

reseller:stock_purchase_requested

Triggered when a reseller requests wholesale stock.

{
  "event": "reseller:stock_purchase_requested",
  "data": {
    "relationship_id": "rel_123",
    "reseller_user_id": "usr_123",
    "transfer_id": "rst_123",
    "product_id": "prod_123",
    "variant_id": null,
    "quantity": 25,
    "wholesale_unit_price": 7.5,
    "currency": "USD"
  },
  "created_at": 1777111200
}

reseller:stock_item_delivered

Triggered when reseller inventory is delivered to an end customer.

{
  "event": "reseller:stock_item_delivered",
  "data": {
    "relationship_id": "rel_123",
    "reseller_user_id": "usr_123",
    "transfer_id": "rst_123",
    "item_id": "rsi_123",
    "product_id": "prod_123",
    "variant_id": null,
    "serial_id": "ser_123",
    "delivered_to_email": "[email protected]"
  },
  "created_at": 1777111200
}

reseller:purchase is accepted by the webhook event allowlist for integrations that already subscribed to the broad purchase name, but new integrations should use the more specific stock purchase events above.

Event	Description
`product:created`	Product created
`product:edited`	Product updated
`product:stock`	Product stock changed through a direct catalog/product update
`product:dynamic`	Dynamic product webhook dispatched
`query:created`	Support query created
`query:replied`	Support query replied
`feedback:received`	Feedback received
`affiliate:payout_requested`	Affiliate payout requested

Payload Notes

Invoice-Context Product Payload

product:dynamic currently uses the same invoice-style payload family as the order events. It is not the same as the direct dynamic_webhook delivery callback.

Runtime-Specific Events

product:stock is for direct catalog stock changes, such as dashboard or API product edits. For stock consumed by checkout, use the matching order event, usually order:paid:product.The remaining supported event names on this page are listed as valid event values. Dedicated public example payloads for product:created, product:edited, product:stock, query:created, query:replied, feedback:received, and affiliate:payout_requested are not expanded here yet.

Example Payload

product:dynamic

Triggered after Shoppex starts dynamic product delivery for an invoice-backed purchase. This webhook uses invoice context and is separate from the direct dynamic_webhook delivery request.

{
  "event": "product:dynamic",
  "data": {
    "uniqid": "abc123def456",
    "type": "PRODUCT",
    "status": "COMPLETED",
    "gateway": "STRIPE",
    "total": 49.99,
    "total_display": 49.99,
    "currency": "USD",
    "customer_email": "[email protected]",
    "country": "US",
    "quantity": 1,
    "product_id": "prod_xyz",
    "product_title": "Dynamic Role",
    "is_developer_invoice": false,
    "created_at": "2026-01-15T09:10:00.000Z",
    "updated_at": "2026-01-15T10:10:00.000Z"
  },
  "created_at": 1705318200
}

Common Fields

All webhook payloads include these top-level fields:

Field	Type	Description
`event`	string	Event type (e.g., `order:paid`)
`data`	object	Event-specific payload
`created_at`	number	Unix timestamp when event was created

Top-level webhook created_at is a Unix timestamp. Nested timestamps inside data, like invoice created_at / updated_at or subscription period fields, are ISO 8601 strings when present.

Start Here

Concepts

Webhooks

Headless Commerce

Use Cases

Embed SDK

Event Types

Supported Event Names

Payload Families

Invoice Payload

Invoice Payload With Products

Example Payloads

order:paid

order:cancelled

order:paid:product

order:cancelled:product

order:manual_payment_pending

Payload Family

Example Payloads

subscription:created

subscription:cancelled

subscription:renewed

Payload Notes

Example Payloads

reseller:sale

reseller:stock_purchase_requested

reseller:stock_item_delivered

Payload Notes

Invoice-Context Product Payload

Runtime-Specific Events

Example Payload

product:dynamic

Common Fields

Next Steps

Webhooks Overview

Dynamic Delivery

​Event Types

​Supported Event Names

​Payload Families

​Invoice Payload

​Invoice Payload With Products

​Example Payloads

​order:paid

​order:cancelled

​order:paid:product

​order:cancelled:product

​order:manual_payment_pending

​Payload Family

​Example Payloads

​subscription:created

​subscription:cancelled

​subscription:renewed

​Payload Notes

​Example Payloads

​reseller:sale

​reseller:stock_purchase_requested

​reseller:stock_item_delivered

​Payload Notes

​Invoice-Context Product Payload

​Runtime-Specific Events

​Example Payload

​product:dynamic

​Common Fields

​Next Steps

Webhooks Overview

Dynamic Delivery

Event Types

Supported Event Names

Payload Families

Invoice Payload

Invoice Payload With Products

Example Payloads

order:paid

order:cancelled

order:paid:product

order:cancelled:product

order:manual_payment_pending

Payload Family

Example Payloads

subscription:created

subscription:cancelled

subscription:renewed

Payload Notes

Example Payloads

reseller:sale

reseller:stock_purchase_requested

reseller:stock_item_delivered

Payload Notes

Invoice-Context Product Payload

Runtime-Specific Events

Example Payload

product:dynamic

Common Fields

Next Steps