Webhook Payloads

1. baFailure (Billing Attempt Failure)

Triggered when a billing attempt fails with a dunning-related error.

{
  "shopDomain": "example.myshopify.com",
  "action": "baFailure",
  "payload": {
    "subscriptionContractId": "12345",
    "customerId": "67890",
    "customerEmail": "[email protected]",
    "subscriptionStatus": "ACTIVE" | "CANCELLED" | "PAUSED" | "FAILED" | "EXPIRED",
    "isInDunning": true,
    "nextBillingDate": "2026-02-01T00:00:00Z",
    "billingAttemptId": "99999",
    "billingAttemptStatus": "FAILED",
    "billingAttemptAmount": "29.99",        // optional
    "billingAttemptCurrencyCode": "USD",    // optional
    "billingAttemptErrorCode": "PAYMENT_METHOD_DECLINED",  // optional
    "billingAttemptErrorMessage": "Card declined"          // optional
  }
}

2. cpmUpdated (Customer Payment Method Updated)

Triggered when a customer's payment method is updated.

{
  "shopDomain": "example.myshopify.com",
  "action": "cpmUpdated",
  "payload": {
    "subscriptionContractId": "12345",
    "customerId": "67890",
    "customerEmail": "[email protected]",
    "subscriptionStatus": "ACTIVE",
    "isInDunning": false,
    "nextBillingDate": "2026-02-01T00:00:00Z",
    "customerPaymentMethodId": "gid://shopify/CustomerPaymentMethod/123",  // or null
    "customerPaymentMethodInstrumentType": "CreditCard" | "ShopPay" | etc  // optional
  }
}

3. baSuccess (Billing Attempt Success)

Triggered when a billing attempt succeeds. Same structure as baFailure:

{
  "shopDomain": "example.myshopify.com",
  "action": "baSuccess",
  "payload": {
    "subscriptionContractId": "12345",
    "customerId": "67890",
    "customerEmail": "[email protected]",
    "subscriptionStatus": "ACTIVE",
    "isInDunning": false,
    "nextBillingDate": "2026-02-01T00:00:00Z",
    "billingAttemptId": "99999",
    "billingAttemptStatus": "SUCCESS",
    "orderId": "111111",
    "billingAttemptAmount": "29.99",
    "billingAttemptCurrencyCode": "USD"
  }
}

4. scCreated (Subscription Contract Created)

Triggered when a new subscription is created:

{
  "shopDomain": "example.myshopify.com",
  "action": "scCreated",
  "payload": {
    "subscriptionContractId": "12345",
    "customerId": "67890",
    "customerEmail": "[email protected]",
    "subscriptionStatus": "ACTIVE",
    "isInDunning": false,
    "nextBillingDate": "2026-02-01T00:00:00Z"
  }
}

5. scUpdated (Subscription Contract Updated)

Triggered when a subscription is updated. Same structure as scCreated:

{
  "shopDomain": "example.myshopify.com",
  "action": "scUpdated",
  "payload": {
    "subscriptionContractId": "12345",
    "customerId": "67890",
    "customerEmail": "[email protected]",
    "subscriptionStatus": "ACTIVE",
    "isInDunning": false,
    "nextBillingDate": "2026-02-01T00:00:00Z"
  }
}