Event Types

An event type is a stable public name, written <object>.<what happened>. When you register an endpoint you choose the types it receives, or all of them. Each type names the snapshot it carries in data.object; the shapes are under Snapshot shapes.

Several internal actions can produce the same event type. source.action on the event tells you which one fired, and data.changes lists the fields that changed when there are any.

V1 catalog

This is the V1 catalog: 35 event types across orders, refunds, shipments, subscriptions, and customers. New types are added without changing existing ones. Catalog (products and variants), store credit, rewards, and coupons are not covered yet and are candidates for a later release.

Orders

Event type	When it fires	Snapshot
order.created	An order is placed at checkout, created by an admin, or created as a replacement for another order.	order
order.payment_status_changed	The order’s payment status changes, for example from AUTHORIZED to PAID.	order
order.payment_captured	A gateway payment on the order is captured, or an admin records an offline payment against it.	order
order.payment_failed	A payment attempt on the order is declined or errors.	order
order.fulfillment_status_changed	The order’s fulfillment status changes, for example from UNFULFILLED to PARTIALLY_FULFILLED.	order
order.fulfilled	Every physical line on the order has shipped. Fires each time the order becomes fully fulfilled, for example again after a cancelled shipment is re-fulfilled.	order
order.cancelled	The order is cancelled or voided.	order
order.updated	The order’s address, customer, custom fields, or order date is changed, or a discount is applied.	order
order.chargeback_reported	The payment processor reports a chargeback against the order’s payment.	order

Refunds

Event type	When it fires	Snapshot
refund.issued	A refund is issued against an order.	refund
refund.completed	The payment processor confirms the refund has gone through.	refund
refund.failed	The payment processor rejects the refund.	refund
refund.voided	The refund is voided before it settles, so no money is returned.	refund

Shipments

Event type	When it fires	Snapshot
shipment.created	Items on an order are fulfilled and a shipment recorded. Fires once per fulfillment, including the last.	shipment
shipment.status_changed	The shipment’s status changes, for example from IN_TRANSIT to DELIVERED.	shipment
shipment.tracking_updated	The shipment’s carrier, tracking number, or tracking URL changes.	shipment
shipment.cancelled	The shipment is cancelled.	shipment

Subscriptions

Event type	When it fires	Snapshot
subscription.created	A subscription is created.	subscription
subscription.status_changed	The subscription’s status changes, including when renewals give up after repeated failures and when it recovers.	subscription
subscription.cancelled	The subscription is cancelled.	subscription
subscription.paused	The subscription is paused.	subscription
subscription.resumed	A paused subscription is resumed, or a cancelled one is reactivated.	subscription
subscription.processed	A renewal runs and its order is placed.	subscription
subscription.payment_failed	A renewal payment is declined or errors.	subscription
subscription.cycle_skipped	An upcoming renewal is skipped, by the customer, an admin, or automatically.	subscription
subscription.processing_date_changed	The next processing date is moved.	subscription
subscription.items_changed	An item on the subscription is added, removed, updated, or swapped for another.	subscription
subscription.pricing_changed	The subscription’s price changes, including when a price supplied by an outside system is applied.	subscription
subscription.replaced	The subscription is replaced by a new one.	subscription

Customers

Event type	When it fires	Snapshot
customer.created	A customer account is created.	customer
customer.updated	The customer’s profile details change, or their email address is claimed or verified.	customer
customer.status_changed	The customer’s status changes, for example from ACTIVE to SUSPENDED.	customer
customer.account_type_changed	The customer’s account type changes, by an admin or through an automatic tier change.	customer
customer.address_changed	One of the customer’s saved addresses is added, updated, or removed.	customerAddress
customer.payment_method_changed	One of the customer’s saved payment methods is added, updated, or removed.	customerPaymentMethod

Tip

One change in the store can produce more than one event, for example a payment that is captured and changes the order’s payment status. Handle each event on its own, and do not rely on a particular pair arriving together or in order.

Snapshot shapes

data.object is the object as it was at the moment of the event. The order and shipment snapshots use the same shapes as the matching resources in the public API reference; the subscription, customer, refund, address, and payment method snapshots are webhook shapes. Every schema is listed there too, as WebhookEvent and the components below.

Snapshot	Schema	Shape
order	PublicOrderListItem	each order returned by GET /order/paged
refund	PublicRefund	new for webhooks
shipment	PublicShipmentSnapshot	PublicShipment plus orderId and orderNumber
subscription	PublicSubscriptionSnapshot	the subscription, with its lines as PublicSubscriptionListItem entries
customer	PublicCustomer	new for webhooks
customerAddress	PublicCustomerAddress	new for webhooks
customerPaymentMethod	PublicCustomerPaymentMethod	new for webhooks

Money is always a plain decimal string in the object’s currency, never a float. Timestamps are ISO 8601 in UTC, except nextProcessingDate, which is a plain date such as 2026-11-08.

Order

PublicOrderListItem: the order’s ids, dates, payment and fulfillment status, totals, and lines.

order.created

{
  "id": "evt_01JA3K8Q2V7XN4M9RZB6TC5HFE",
  "type": "order.created",
  "apiVersion": "2026-10-01",
  "createdOn": "2026-10-08T17:42:11.208Z",
  "storeId": 5,
  "livemode": true,
  "data": {
    "object": {
      "orderId": 48211,
      "orderNumber": 100482,
      "orderDate": "2026-10-08T17:42:09.512Z",
      "completedOn": "2026-10-08T17:42:09.512Z",
      "cancelledOn": null,
      "paymentStatus": "PAID",
      "fulfillmentStatus": "UNFULFILLED",
      "currencyCode": "USD",
      "subtotal": "129.00",
      "discountTotal": "10.00",
      "shippingTotal": "8.95",
      "taxTotal": "9.52",
      "grandTotal": "137.47",
      "replacedOrderNumber": null,
      "itemCount": 3,
      "items": [
        {
          "sku": "GREENS-30",
          "name": "Daily Greens 30-Day",
          "quantity": 1,
          "unitPrice": "89.00",
          "lineTotal": "89.00",
          "customFields": []
        },
        {
          "sku": "SPARK-12",
          "name": "Sparkling Energy 12-Pack",
          "quantity": 2,
          "unitPrice": "20.00",
          "lineTotal": "40.00",
          "customFields": []
        }
      ]
    },
    "changes": null,
    "previousAttributes": null
  },
  "source": { "action": "order.placed", "actorType": "CUSTOMER" }
}

Refund

PublicRefund:

Field	Type	Notes
refundId	number
orderId	number	The refunded order.
orderNumber	number
refundNumber	number	The store’s refund number: from its own refund sequence, or from the order number sequence when the store shares one.
status	string	PENDING, PROCESSING, COMPLETED, FAILED, or VOIDED.
reason	string	RETURN_SELLABLE, RETURN_NON_SELLABLE, GOODWILL, BILLING_ERROR, DAMAGED_GOODS, DUPLICATE_CHARGE, or OTHER.
amount	string	Total refunded: subtotal plus taxTotal plus shippingTotal.
subtotal	string
taxTotal	string
shippingTotal	string
currencyCode	string
refundedOn	string	When the refund was issued.
voidedOn	string or null	When the refund was voided; null unless it was.
createdOn	string
modifiedOn	string	When the refund record last changed.

refund.issued

{
  "id": "evt_01JA3M2D9F4WQ7XK8HZT5RBN6C",
  "type": "refund.issued",
  "apiVersion": "2026-10-01",
  "createdOn": "2026-10-10T14:05:37.019Z",
  "storeId": 5,
  "livemode": true,
  "data": {
    "object": {
      "refundId": 1204,
      "orderId": 48211,
      "orderNumber": 100482,
      "refundNumber": 1,
      "status": "PENDING",
      "reason": "DAMAGED_GOODS",
      "amount": "43.20",
      "subtotal": "40.00",
      "taxTotal": "3.20",
      "shippingTotal": "0.00",
      "currencyCode": "USD",
      "refundedOn": "2026-10-10T14:05:36.204Z",
      "voidedOn": null,
      "createdOn": "2026-10-10T14:05:36.204Z",
      "modifiedOn": "2026-10-10T14:05:36.204Z"
    },
    "changes": null,
    "previousAttributes": null
  },
  "source": { "action": "order_refund.issued", "actorType": "ADMIN" }
}

Shipment

PublicShipmentSnapshot: every field of PublicShipment (status, carrier, tracking, shipped and estimated delivery dates, and the shipped lines), plus orderId and orderNumber so you can tie it to its order without another call.

This sample is a status change, so data.changes carries the old and new status.

shipment.status_changed

{
  "id": "evt_01JA3P7G1S8YV2NC4KDM9EXQ3T",
  "type": "shipment.status_changed",
  "apiVersion": "2026-10-01",
  "createdOn": "2026-10-09T19:28:04.377Z",
  "storeId": 5,
  "livemode": true,
  "data": {
    "object": {
      "shipmentId": 9132,
      "externalShipmentId": "SW-778812",
      "status": "DELIVERED",
      "carrierName": "FedEx",
      "trackingNumber": "771234567890",
      "trackingUrl": "https://www.fedex.com/fedextrack/?trknbr=771234567890",
      "shippedOn": "2026-10-08T21:15:00.000Z",
      "estimatedDelivery": "2026-10-09T23:59:00.000Z",
      "items": [
        { "lineItemId": "61204", "quantity": 1 },
        { "lineItemId": "61205", "quantity": 2 }
      ],
      "orderId": 48211,
      "orderNumber": 100482
    },
    "changes": { "status": { "old": "IN_TRANSIT", "new": "DELIVERED" } },
    "previousAttributes": null
  },
  "source": { "action": "shipment.status_changed", "actorType": "SYSTEM" }
}

Subscription

PublicSubscriptionSnapshot: the subscription as a whole, with each of its live lines in items.

Field	Type	Notes
subscriptionId	number	The id the subscription routes take.
subscriptionNumber	number
status	string	ACTIVE, PAUSED, CANCELLED, or TERMINAL_FAILED.
nextProcessingDate	string or null	Next renewal date; null once the subscription is no longer scheduled to run.
createdOn	string
cancelledOn	string or null
cancelReason	string or null
items	array	One PublicSubscriptionListItem per live line, the same entries the subscription list returns; empty once every line is removed.

subscription.processed

{
  "id": "evt_01JA3R5H6B0ZT9WF2QXC7MPA4D",
  "type": "subscription.processed",
  "apiVersion": "2026-10-01",
  "createdOn": "2026-10-08T06:00:14.552Z",
  "storeId": 5,
  "livemode": true,
  "data": {
    "object": {
      "subscriptionId": 3307,
      "subscriptionNumber": 20419,
      "status": "ACTIVE",
      "nextProcessingDate": "2026-11-08",
      "createdOn": "2026-04-08T15:03:22.118Z",
      "cancelledOn": null,
      "cancelReason": null,
      "items": [
        {
          "subscriptionId": 3307,
          "subscriptionItemId": 4410,
          "subscriptionNumber": 20419,
          "status": "ACTIVE",
          "sku": "GREENS-30",
          "name": "Daily Greens 30-Day",
          "quantity": 1,
          "unitPrice": "79.00",
          "intervalCount": 1,
          "intervalUnit": "MONTH",
          "nextProcessingDate": "2026-11-08",
          "createdOn": "2026-04-08T15:03:22.118Z",
          "cancelledOn": null,
          "cancelReason": null,
          "customFields": []
        }
      ]
    },
    "changes": null,
    "previousAttributes": null
  },
  "source": { "action": "subscription.processed", "actorType": "SYSTEM" }
}

Customer

PublicCustomer:

Field	Type	Notes
storeCustomerId	number	The same id the public API takes as storeCustomerId.
email	string
firstName	string
lastName	string
phoneNumber	string or null
status	string	ACTIVE, BANNED, SUSPENDED, or DEACTIVATED.
accountTypeId	number	The customer’s account type in the store.
accountTypeName	string	That account type’s display name.
emailVerified	boolean
commissionProviderName	string or null	The store’s commission provider; null when the store has none.
commissionProviderId	string or null	The customer’s id in that provider; null until it is synced, or when the store has none.
createdOn	string
modifiedOn	string	When the customer record last changed.

The snapshot never includes passwords, tokens, or card numbers. Address and payment method events carry the address or payment method itself, below, not the customer.

customer.created

{
  "id": "evt_01JA3T9N4E1KX8RB6VHZ3QYW2G",
  "type": "customer.created",
  "apiVersion": "2026-10-01",
  "createdOn": "2026-10-08T16:20:51.090Z",
  "storeId": 5,
  "livemode": true,
  "data": {
    "object": {
      "storeCustomerId": 88214,
      "email": "jordan.lee@example.com",
      "firstName": "Jordan",
      "lastName": "Lee",
      "phoneNumber": "+15125550143",
      "status": "ACTIVE",
      "accountTypeId": 1,
      "accountTypeName": "Retail",
      "emailVerified": false,
      "commissionProviderName": null,
      "commissionProviderId": null,
      "createdOn": "2026-10-08T16:20:50.733Z",
      "modifiedOn": "2026-10-08T16:20:50.733Z"
    },
    "changes": null,
    "previousAttributes": null
  },
  "source": { "action": "customer.created", "actorType": "API_TOKEN" }
}

Customer address

PublicCustomerAddress: the saved address that was added, updated, or removed. storeCustomerId ties it to its customer.

Field	Type	Notes
customerAddressId	number
storeCustomerId	number	The customer the address belongs to.
firstName	string
lastName	string
company	string or null
streetLine1	string
streetLine2	string or null
city	string
stateProvince	string
postalCode	string
countryCode	string	ISO 3166-1 alpha-2, for example US.
isDefault	boolean	Whether this is the customer’s default address.
isActive	boolean	false once the address is removed; a removal event carries the removed address.

This sample is an edit, so data.changes carries the old and new values.

customer.address_changed

{
  "id": "evt_01JA3V2C8M5QZ7TN1FXR4KBW9H",
  "type": "customer.address_changed",
  "apiVersion": "2026-10-01",
  "createdOn": "2026-10-09T11:12:40.611Z",
  "storeId": 5,
  "livemode": true,
  "data": {
    "object": {
      "customerAddressId": 51730,
      "storeCustomerId": 88214,
      "firstName": "Jordan",
      "lastName": "Lee",
      "company": null,
      "streetLine1": "2100 Lake Austin Blvd",
      "streetLine2": "Unit 4",
      "city": "Austin",
      "stateProvince": "TX",
      "postalCode": "78703",
      "countryCode": "US",
      "isDefault": true,
      "isActive": true
    },
    "changes": { "streetLine2": { "old": null, "new": "Unit 4" } },
    "previousAttributes": null
  },
  "source": { "action": "customer.address_updated", "actorType": "CUSTOMER" }
}

Customer payment method

PublicCustomerPaymentMethod: the saved payment method that was added, updated, or removed. It carries only what a customer sees on their account page: never card numbers, gateway tokens, or vault ids.

Field	Type	Notes
customerPaymentMethodId	number
storeCustomerId	number	The customer the payment method belongs to.
paymentType	string	CARD, BANK, CRYPTO, or DIGITAL_WALLET.
brand	string	As the payment processor reports it, for example visa.
lastFour	string or null
expiryMonth	string or null
expiryYear	string or null
isDefault	boolean	Whether this is the customer’s default payment method.
isActive	boolean	false once the payment method is removed; a removal event carries the removed payment method.

This sample is the customer removing a card, so the payment method arrives with isActive: false.

customer.payment_method_changed

{
  "id": "evt_01JA3W6R3J9DX2HV5PKN8CTA1E",
  "type": "customer.payment_method_changed",
  "apiVersion": "2026-10-01",
  "createdOn": "2026-10-09T11:20:03.274Z",
  "storeId": 5,
  "livemode": true,
  "data": {
    "object": {
      "customerPaymentMethodId": 30417,
      "storeCustomerId": 88214,
      "paymentType": "CARD",
      "brand": "visa",
      "lastFour": "4242",
      "expiryMonth": "08",
      "expiryYear": "2028",
      "isDefault": false,
      "isActive": false
    },
    "changes": null,
    "previousAttributes": null
  },
  "source": { "action": "customer.payment_method_removed", "actorType": "CUSTOMER" }
}

The source block

Field	What it is
action	The internal action behind the event. Useful for logging and for telling apart actions that share a type; the set can grow.
actorType	Who caused the change.

actorType	Meaning
ADMIN	A store admin, in the Open Shop admin.
CUSTOMER	The customer, on the storefront or in their account.
API_TOKEN	An integration calling the API with an app token.
SYSTEM	Open Shop itself: scheduled renewals, carrier and fulfillment syncs, sweeps.
PLATFORM	Open Shop platform tooling acting on the store’s behalf.

Best Practices Deduplicate, cope with out-of-order delivery, and know when to re-fetch.