Summary webhook payloads

Last updated: March 20, 2026

As of March 2026, Orb is rolling out summary webhook payloads as our recommended integration pattern. To opt-in to summary payloads, please coordinate with your Orb CSM.

Overview

Summary webhooks reduce the size of invoice and subscription webhook payloads by sending a lightweight version of the core resource. When enabled, invoice payloads exclude line items and pricing details, and subscription payloads include only essential identification and status fields.

This feature is enabled per-account. All invoice and subscription webhook event types are affected.

Affected Event Types

Invoice Events

invoice.issued, invoice.edited, invoice.invoice_date_elapsed, invoice.issue_failed, invoice.payment_processing, invoice.payment_succeeded, invoice.payment_failed, invoice.manually_marked_as_paid, invoice.manually_marked_as_void, invoice.undo_mark_as_paid, invoice.sync_succeeded, invoice.sync_failed, invoice.accounting_sync_succeeded, invoice.accounting_sync_failed, invoice.dunning_schedule_created, invoice.dunning_schedule_ended, invoice.dunning_schedule_reset, invoice.dunning_schedule_step_executed

Subscription Events

subscription.created, subscription.edited, subscription.started, subscription.ended, subscription.plan_changed, subscription.plan_version_change_scheduled, subscription.plan_version_changed, subscription.fixed_fee_quantity_updated, subscription.usage_exceeded, subscription.cost_exceeded, subscription.trial_ended, subscription.plan_change_scheduled, subscription.cancellation_scheduled, subscription.cancellation_unscheduled, subscription.accounting_sync_succeeded, subscription.accounting_sync_failed

Invoice summary payload

The invoice summary payload will continue to include:

| Field | Type | Description |
|---|---|---|
| `id` | string | Invoice ID |
| `invoice_number` | string | Auto-generated invoice number |
| `invoice_date` | datetime | The scheduled date of the invoice |
| `currency` | string | ISO 4217 currency string or `credits` |
| `status` | string | `draft`, `issued`, `paid`, `synced`, or `void` |
| `invoice_source` | string | `subscription`, `partial`, or `one_off` |
| `total` | string | Total after discounts and minimums |
| `amount_due` | string | Final amount to be charged |
| `due_date` | datetime | When payment is due |
| `customer` | object | Minified customer (`id`, `external_customer_id`) |
| `subscription` | object | Minified subscription (`id`) |
| `created_at` | datetime | When the invoice was created |
| `hosted_invoice_url` | string | Customer-facing invoice portal URL |
| `invoice_pdf` | string | Link to download the invoice PDF |
| `memo` | string | Free-form text on the invoice PDF |
| `will_auto_issue` | boolean | Whether the invoice will be automatically issued |
| `eligible_to_issue_at` | datetime | When the invoice becomes eligible to issue |
| `shipping_address` | object | Shipping address |
| `billing_address` | object | Billing address |
| `customer_tax_id` | object | Customer tax ID |
| `customer_balance_transactions` | array | Customer balance transactions |
| `credit_notes` | array | Associated credit note summaries |
| `payment_attempts` | array | Payment attempt history |
| `metadata` | object | Custom metadata |
| `issued_at` | datetime | When the invoice was issued |
| `paid_at` | datetime | When the invoice was paid |
| `voided_at` | datetime | When the invoice was voided |
| `scheduled_issue_at` | datetime | Scheduled issue time |
| `auto_collection` | object | Auto-collection configuration |
| `issue_failed_at` | datetime | When the invoice failed to issue |
| `sync_failed_at` | datetime | When external sync failed |
| `payment_failed_at` | datetime | Most recent payment failure time |
| `payment_started_at` | datetime | Most recent payment attempt start time |

The following fields will now be excluded:


| Field | Type | Description |
|---|---|---|
| `line_items` | array | The full breakdown of prices — this is the primary source of payload bloat |
| `subtotal` | string | Total before discounts and minimums |
| `discount` | object | Deprecated invoice-level discount |
| `discounts` | array | Invoice-level discounts |
| `minimum` | object | Invoice-level minimum |
| `minimum_amount` | string | Minimum amount |
| `maximum` | object | Invoice-level maximum |
| `maximum_amount` | string | Maximum amount |

To retrieve the full invoice including line items, fetch the invoice directly.

Subscription summary payload

| Field | Type | Description |
|---|---|---|
| `id` | string | Subscription ID |
| `name` | string | Subscription name |
| `status` | string | `active`, `ended`, or `upcoming` |
| `start_date` | datetime | When billing starts |
| `end_date` | datetime | When billing ends (null if ongoing) |
| `created_at` | datetime | When the subscription was created |
| `plan` | object | Plan summary: `id`, `external_plan_id`, `name` |
| `customer` | object | Customer summary: `id`, `external_customer_id` |
| `metadata` | object | Custom metadata |

The following fields will now be excluded:

| Field | Type | Description |
|---|---|---|
| `current_billing_period_start_date` | datetime | Current billing period start |
| `current_billing_period_end_date` | datetime | Current billing period end |
| `trial_info` | object | Trial configuration |
| `active_plan_phase_order` | integer | Current plan phase |
| `fixed_fee_quantity_schedule` | array | Fixed fee quantity schedule |
| `default_invoice_memo` | string | Default memo for invoices |
| `auto_collection` | boolean | Auto-collection setting |
| `net_terms` | integer | Payment terms |
| `redeemed_coupon` | object | Coupon redemption |
| `billing_cycle_day` | integer | Billing cycle anchor day |
| `billing_cycle_anchor_configuration` | object | Billing cycle anchor config |
| `invoicing_threshold` | string | Invoicing threshold amount |
| `price_intervals` | array | Price intervals — expensive to compute |
| `adjustment_intervals` | array | Adjustment intervals |
| `discount_intervals` | array | Discount intervals (deprecated) |
| `minimum_intervals` | array | Minimum intervals (deprecated) |
| `maximum_intervals` | array | Maximum intervals (deprecated) |
| `pending_subscription_change` | object | Pending subscription change |
| `customer` | object | Full customer object (replaced with minified version) |
| `plan` | object | Full plan object (replaced with minified version) |

To retrieve the full subscription, use the fetch subscription endpoint.

Recommended Integration Pattern

With summary webhooks enabled, we recommend the following pattern for webhook handlers:

1. Receive the webhook event

2. Read the event type and resource id from the payload

3. Fetch the full resource via API if detailed data is needed

4. Process accordingly

This ensures your handler always acts on the most current state of the resource, avoiding issues with stale data in webhook payloads.