Breeze sends webhook events of type "INVOICE_STATUS_UPDATED" whenever an invoice’s status changes. This is especially useful if you would like to track successful recurring payments for a subscription.

Each invoice event includes a JSON payload structured in the following manner:

{
  "type": "INVOICE_STATUS_UPDATED",
  "data": {
    "id": "invc_bc896e7c60bf8176",
    "customerId": "cus_9147c9be8f25092c",
    "dueAt": 1758704906025,
    "expiredAt": 1763887106025,
    "livemode": false,
    "merchantId": "mch_cd239603802d7b4e",
    "statusUpdatedAt": 1758703144521,
    "status": "PAID",
    "amount": 301,
    "currency": "USD",
    "subscriptionId": "subs_6e7a052c4ad6e90d",
    "paymentPageId": "page_a1a96e93877b899a",
    "billingPeriod": {
      "start": 1758703144521, 
      "end": 1763887106025
    }
  },
  "signature": "webhook_signature"
}

{
  "type": "INVOICE_STATUS_UPDATED",
  "data": {
    "id": "invc_12345",
    "customerId": "cus_67890",
    "dueAt": 1758704906025,
    "expiredAt": 1763887106025,
    "livemode": true,
    "merchantId": "mch_abc123",
    "statusUpdatedAt": 1758703100000,
    "status": "PENDING",
    "amount": 0,
    "currency": "USD",
    "subscriptionId": "subs_trial123",
    "paymentPageId": "page_trial123",
    "billingPeriod": {
      "start": 1758703144521, 
      "end": 1763887106025
    }
  },
  "signature": "webhook_signature"
}

{
  "type": "INVOICE_STATUS_UPDATED",
  "data": {
    "id": "invc_exp123",
    "customerId": "cus_exp456",
    "dueAt": 1758704906025,
    "expiredAt": 1758791306025,
    "livemode": true,
    "merchantId": "mch_expired123",
    "statusUpdatedAt": 1758791306025,
    "status": "EXPIRED",
    "amount": 500,
    "currency": "USD",
    "subscriptionId": "subs_expired789",
    "paymentPageId": "page_expired001",
    "billingPeriod": {
      "start": 1758703144521, 
      "end": 1763887106025
    }
  },
  "signature": "webhook_signature"
}

{
  "type": "INVOICE_STATUS_UPDATED",
  "data": {
    "id": "invc_gp123",
    "customerId": "cus_gp456",
    "dueAt": 1758704906025,
    "expiredAt": 1763887106025,
    "livemode": true,
    "merchantId": "mch_gp123",
    "statusUpdatedAt": 1758705000000,
    "status": "GRACE_PERIOD",
    "amount": 499,
    "currency": "USD",
    "subscriptionId": "subs_gp789",
    "paymentPageId": "page_gp001",
    "billingPeriod": {
      "start": 1758703144521, 
      "end": 1763887106025
    }
  },
  "signature": "webhook_signature"
}

{
  "type": "INVOICE_STATUS_UPDATED",
  "data": {
    "id": "invc_cancel123",
    "customerId": "cus_cancel456",
    "dueAt": 1758704906025,
    "expiredAt": 1763887106025,
    "livemode": true,
    "merchantId": "mch_cancel123",
    "statusUpdatedAt": 1758705200000,
    "status": "CANCELED",
    "amount": 400,
    "currency": "USD",
    "subscriptionId": "subs_cancel789",
    "paymentPageId": "page_cancel001",
    "billingPeriod": {
      "start": 1758703144521, 
      "end": 1763887106025
    },
    "canceledAt": 1763887106025
  },
  "signature": "webhook_signature"
}

Webhook payloads always include:

type – Event type
data – Invoice object
signature – HMAC signature for verification

📓 Core Invoice Statuses

Status	Descriptions
`PENDING`	A new invoice has been generated for the subscription and is awaiting payment. Breeze pre-generates pending invoices up to 14 days prior to the due date.
`PAID`	The invoice was successfully paid by the customer. This occurs after a successful one-time or recurring charge.
`EXPIRED`	The invoice was not paid by its expiration time. No further payment attempts will be made for this invoice.
`GRACE_PERIOD`	The invoice payment failed after the due date (e.g., card declined). The invoice remains in a grace period, during which retry attempts may be made.
`CANCELED`	The invoice was voided by the system or merchant. It will no longer be collected or retried

⚠️ Breeze emits webhook events at each of these state transitions