Webhook events - Shoppex

Event types

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

When creating webhooks through the Dev API, send the exact event name, for example order:paid. Wildcard patterns like invoice.* do not work. 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
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
`order:item.delivered`	Line item fulfilled with late content
`order:item.delivery_failed`	Dynamic line item delivery failed
`order:shipped`	Physical items of an order marked shipped, or their tracking corrected

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

order:item.delivered and order:item.delivery_failed report per-line-item fulfillment after payment. See Asynchronous and Manual Fulfillment for their payloads and recovery flow.

order:shipped and order:item.delivered also cover physical products. Marking an order shipped sends one order:shipped. Marking it delivered sends one order:item.delivered per physical line item, with deliveredItems.delivery_type: "PHYSICAL". There is no separate “delivered” order event.

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

Each invoice payload includes line_items. Every entry includes the stable line-item id, product snapshot, optional variant, quantity, delivery_status, and delivered_at. Paid events also include license_keys on delivered SERIALS line items. Other lifecycle events omit the keys.

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

A shop-level subscription receives the complete order. A webhook configured on a specific product receives only that product’s matching line_items and products entries. In a cart containing multiple serial products, product A’s endpoint therefore never receives product B’s license keys.

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",
    "line_items": [
      {
        "id": "018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
        "product_id": "prod_xyz",
        "product_title": "Pro License",
        "product_type": "SERIALS",
        "variant_id": "variant_pro",
        "variant_title": "Pro",
        "quantity": 1,
        "delivery_status": "DELIVERED",
        "delivered_at": "2026-01-15T10:10:00.000Z",
        "license_keys": [
          { "key": "AAAA-BBBB-CCCC" }
        ]
      }
    ],
    "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.

license_keys contains the unredacted product keys delivered to the buyer. Treat the webhook body as sensitive, avoid recording it in application logs, and only forward it to systems that are allowed to store the delivered product.

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",
    "line_items": [
      {
        "id": "018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
        "product_id": "prod_xyz",
        "product_title": "Pro License",
        "product_type": "SERIALS",
        "variant_id": "variant_pro",
        "variant_title": "Pro",
        "quantity": 1,
        "delivery_status": "PENDING",
        "delivered_at": null
      }
    ],
    "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",
    "line_items": [
      {
        "id": "018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
        "product_id": "prod_xyz",
        "product_title": "Pro License",
        "product_type": "SERIALS",
        "variant_id": "variant_pro",
        "variant_title": "Pro",
        "quantity": 1,
        "delivery_status": "DELIVERED",
        "delivered_at": "2026-01-15T10:10:00.000Z",
        "license_keys": [
          { "key": "AAAA-BBBB-CCCC" }
        ]
      }
    ],
    "products": [
      {
        "uniqid": "prod_xyz",
        "title": "Pro License",
        "description": "Full access to all features",
        "price": 49.99,
        "price_display": 49.99,
        "currency": "USD",
        "type": "SERIALS"
      }
    ],
    "created_at": "2026-01-15T09:10:00.000Z",
    "updated_at": "2026-01-15T10:10:00.000Z"
  },
  "created_at": 1705318200
}

variant_id and variant_title are null when the product has no variant. license_keys is omitted unless a paid SERIALS line has committed keys. Use the line-item id as the stable correlation key; carts can contain the same product more than once with different variants.

order:cancelled:product

Same as order:cancelled but includes full product details.

order:shipped

Triggered when the physical items of an order are marked shipped, from the dashboard or through POST /dev/v1/orders/{id}/ship. Marking a shipped order again to correct the tracking sends the event again with firstShipment: false.Unlike the invoice-payload events above, order:shipped carries only the shipment. It uses camelCase keys, like order:item.delivered, and contains no shipping address.

{
  "event": "order:shipped",
  "data": {
    "invoiceId": "abc123def456",
    "shippedBy": "MERCHANT",
    "firstShipment": true,
    "shippedAt": "2026-09-23T10:15:00.000Z",
    "trackingCode": "1Z999AA10123456784",
    "trackingUrl": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
    "lineItemIds": [
      "018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f"
    ]
  },
  "created_at": 1790158500
}

invoiceId is the order uniqid. shippedBy is MERCHANT or API. shippedAt keeps the time of the first shipment. trackingCode and trackingUrl are the current tracking, or null. lineItemIds lists the physical line items the shipment covers. It goes to shop-level webhooks only, not to webhooks configured on a single product.

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",
    "line_items": [
      {
        "id": "018f6f2e-7c3a-7b21-9d4e-5a1b2c3d4e5f",
        "product_id": "prod_xyz",
        "product_title": "Pro License",
        "product_type": "SERIALS",
        "variant_id": "variant_pro",
        "variant_title": "Pro",
        "quantity": 1,
        "delivery_status": "PENDING",
        "delivered_at": null
      }
    ],
    "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:plan_change_scheduled`	A plan change waits for the next renewal
`subscription:plan_changed`	The subscription moved to another plan
`subscription:payment_failed`	Card declined or renewal invoice expired
`subscription:past_due`	With reason: `on_hold`, `provider_retrying`, `unpaid`
`subscription:recovered`	Paid after past due; access is back
`subscription:paused`	A pause started
`subscription:resumed`	A paused subscription runs again
`subscription:trial:converted`	A trial ended and the first full payment went through
`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
`subscription:plan_change_scheduled:product`	Plan change scheduled, with product payload
`subscription:plan_changed:product`	Plan changed, with product payload
`subscription:payment_failed:product`	Payment failed, with product payload
`subscription:past_due:product`	Past due, with product payload
`subscription:recovered:product`	Recovered, with product payload
`subscription:paused:product`	Paused, with product payload
`subscription:resumed:product`	Resumed, with product payload
`subscription:trial:converted:product`	Trial converted, 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:plan_changed

Triggered when a subscription moves to another plan: right away after the buyer paid the difference, or once the renewal that bills a scheduled change is paid. amount_charged is always a paid amount: a renewal that declines or waits on the bank sends no subscription:plan_changed until its payment completes. subscription:plan_change_scheduled has the same payload, with amount_charged "0.00" and effective_at the renewal date. changed_by is buyer or merchant.

{
  "event": "subscription:plan_changed",
  "data": {
    "subscriptionId": "0f6c1a52-8d3e-4b7a-9c21-5e4d3b2a1f00",
    "subscription_id": "sub_abc123",
    "change_id": "5b0e3f0a-2c1d-4c8e-9a51-3f8d2b7c6e10",
    "from_plan": { "variant_id": "var_pro", "name": "Pro", "price": "19.99", "currency": "USD", "interval": "MONTH", "interval_count": 1 },
    "to_plan": { "variant_id": "var_elite", "name": "Elite", "price": "39.99", "currency": "USD", "interval": "MONTH", "interval_count": 1 },
    "amount_charged": "9.68",
    "currency": "USD",
    "effective_at": "2026-10-19T14:12:00.000Z",
    "changed_by": "buyer"
  },
  "created_at": 1792419120
}

Lifecycle events: past due, recovered, paused, resumed, trial converted, payment failed

subscription:updated keeps firing for every change; these events say what changed. Each one is sent once, when the change happens, and its payload is the subscription as it was then: a later change does not rewrite it. Every payload carries access.has_access, whether the buyer keeps access now. The status-change events (all but subscription:payment_failed) also carry previous_status, the status before the change. Times are ISO 8601. The :product variants carry the same payload.

subscription:past_due: reason is on_hold (an invoice-billed renewal was not paid in time; access is off until it is paid, and the subscription ends at hold_ends_at), provider_retrying (Stripe or PayPal is still retrying the card), or unpaid (Stripe stopped retrying). open_renewal is the invoice to pay, with what is still due and its pay_url, or null when the provider bills the card itself.
subscription:recovered: a payment (or the merchant) ended a past-due or unpaid state.
subscription:paused carries the pause (starts_at, resume_at, paused_by, reason). subscription:resumed follows the pause end.
subscription:trial:converted: the trial ended and the first full payment went through. It follows the paid invoice, not the status change: Stripe ends a trial before it charges the card, so a declined first charge sends subscription:past_due and subscription:payment_failed instead.
subscription:payment_failed: failure is charge_declined (one event per failed charge; on PayPal one per declined billing period, PayPal’s retries of that period included) or renewal_expired (an invoice-billed renewal ran out unpaid). attemptKey names the attempt.

{
  "event": "subscription:past_due",
  "data": {
    "id": "0f6c1a52-8d3e-4b7a-9c21-5e4d3b2a1f00",
    "uniqid": "sub_abc123",
    "status": "PAST_DUE",
    "previous_status": "ACTIVE",
    "reason": "on_hold",
    "gateway": "NATIVE_CRYPTO",
    "customer_id": "cust_xyz789",
    "current_period_start": "2026-09-15T00:00:00.000Z",
    "current_period_end": "2026-10-15T00:00:00.000Z",
    "trial_end": null,
    "hold_ends_at": "2026-10-29T00:00:00.000Z",
    "cancel_at_period_end": false,
    "access": { "has_access": false },
    "open_renewal": {
      "invoice": "inv_renewal_456",
      "amount": "19.99",
      "currency": "USD",
      "pay_by": "2026-10-29T00:00:00.000Z",
      "pay_url": "https://checkout.shoppex.io/invoice/inv_renewal_456"
    },
    "occurred_at": "2026-10-22T09:00:00.000Z"
  },
  "created_at": 1792659600
}

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
`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
`reseller:enrolled`	Customer became an active reseller
`reseller:application.created`	Customer applied to the reseller program
`reseller:application.rejected`	Reseller application rejected
`reseller:suspended`	Reseller suspended
`reseller:order.completed`	Wholesale reseller order paid and delivered
`reseller:tier.advanced`	Reseller reached a higher discount tier automatically

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.

Reseller events

Four enrollment-lifecycle events share one payload family: a single reseller object. They are reseller:enrolled, reseller:application.created, reseller:application.rejected, and reseller:suspended. reseller:order.completed and reseller:tier.advanced each have their own shape, documented below.reseller:enrolled fires on all three enrollment paths (invite accepted, self-enrollment in open mode, and merchant approval of an application). Reinstating a suspended reseller does not send an event. There is no reseller:reinstated.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
}

reseller:enrolled

Triggered when a customer becomes an active reseller. reseller:application.created, reseller:application.rejected and reseller:suspended carry the identical reseller object — only status and the timestamp fields differ.

{
  "event": "reseller:enrolled",
  "data": {
    "reseller": {
      "id": "019cb402-1111-7000-8000-000000000001",
      "customer_id": "019cb402-2222-7000-8000-000000000002",
      "email": "[email protected]",
      "status": "ACTIVE",
      "tier": {
        "id": "019cb402-3333-7000-8000-000000000003",
        "name": "Gold",
        "discount_percent": 15
      },
      "application_note": null,
      "lifetime_revenue": "0.00",
      "lifetime_orders": 0
    }
  },
  "created_at": 1753430400
}

tier is null when no tier is assigned yet. application_note is only populated for application-mode enrollments. lifetime_revenue is a decimal string, lifetime_orders an integer.

reseller:order.completed

Triggered when a wholesale reseller order is paid from the reseller’s balance and delivered. The items array is the price snapshot frozen at order time. It is not re-derived from the current tier or product prices.

{
  "event": "reseller:order.completed",
  "data": {
    "reseller": {
      "id": "019cb402-1111-7000-8000-000000000001",
      "email": "[email protected]",
      "tier": {
        "id": "019cb402-3333-7000-8000-000000000003",
        "name": "Gold",
        "discount_percent": 15
      }
    },
    "order": {
      "invoice_uniqid": "019cb402-4444-7000-8000-000000000004",
      "total": "425.00",
      "currency": "USD",
      "items": [
        {
          "product_id": "019cb402-5555-7000-8000-000000000005",
          "variant_id": null,
          "quantity": 5,
          "unit_price": "85.00",
          "line_total": "425.00"
        }
      ]
    }
  },
  "created_at": 1753430460
}

reseller:tier.advanced

Triggered when an order completion pushes a reseller’s lifetime totals past a tier’s auto-advance threshold. This event only ever fires alongside reseller:order.completed — there is no other code path that advances a tier automatically. Note the flat shape: the reseller is identified by reseller_id and email at the top level, not by a nested reseller object.

{
  "event": "reseller:tier.advanced",
  "data": {
    "reseller_id": "019cb402-1111-7000-8000-000000000001",
    "email": "[email protected]",
    "previous_tier": {
      "id": "019cb402-6666-7000-8000-000000000006",
      "name": "Silver",
      "discount_percent": 10
    },
    "new_tier": {
      "id": "019cb402-3333-7000-8000-000000000003",
      "name": "Gold",
      "discount_percent": 15
    },
    "lifetime_revenue": "12500.00",
    "lifetime_orders": 42
  },
  "created_at": 1753430461
}

previous_tier is null when the reseller had no tier before. discount_percent is a number on this event, unlike the decimal strings used for money fields.

Common fields

All webhook payloads include these top-level fields:

Field	Type	Description
`event`	string	Event type, for example `order:paid`
`data`	object	Event-specific payload
`created_at`	number	Unix timestamp when the 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.

Webhooks

Setup, verification, and response handling

Dynamic delivery

Deliver products in real time through the webhook response

​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:shipped

​order:manual_payment_pending

​Payload family

​Example payloads

​subscription:created

​subscription:cancelled

​subscription:plan_changed

​Lifecycle events: past due, recovered, paused, resumed, trial converted, payment failed

​subscription:renewed

​Payload notes

​Invoice-context product payload

​Runtime-specific events

​Reseller events

​Example payload

​product:dynamic

​reseller:enrolled

​reseller:order.completed

​reseller:tier.advanced

​Common fields

Webhooks

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:shipped

order:manual_payment_pending

Payload family

Example payloads

subscription:created

subscription:cancelled

subscription:plan_changed

Lifecycle events: past due, recovered, paused, resumed, trial converted, payment failed

subscription:renewed

Payload notes

Invoice-context product payload

Runtime-specific events

Reseller events

Example payload

product:dynamic

reseller:enrolled

reseller:order.completed

reseller:tier.advanced

Common fields