> ## Documentation Index
> Fetch the complete documentation index at: https://docs.withorb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Summary webhooks

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.

<Note>
  This feature is enabled per-account. Contact your Orb representative to enable summary webhooks for your account. All invoice and subscription webhook event types are affected when this feature is turned on.
</Note>

## Affected event types

### Invoice events

The following invoice event types will send summary payloads when summary webhooks are enabled:

* `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

The following subscription event types will send summary payloads when summary webhooks are enabled:

* `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 payload

### Fields included

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

### Fields excluded

The following fields are omitted from the summary invoice payload. Notably, `line_items` is the primary source of payload bloat for invoice webhooks.

| Field            | Type   | Description                         |
| ---------------- | ------ | ----------------------------------- |
| `line_items`     | array  | The full breakdown of prices        |
| `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, use the [GET /invoices/\{id}](/api-reference/invoice/fetch-invoice) endpoint.

## Subscription payload

### Fields included

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

### Fields excluded

The following fields are omitted from the summary subscription payload. The `customer` and `plan` fields are replaced with minified versions containing only identification fields.

| 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                 |
| `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     |

To retrieve the full subscription, use the [GET /subscriptions/\{id}](/api-reference/subscription/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.

<Note>
  Even without summary webhooks, fetching the latest resource state via API before processing is a best practice. Webhook payloads represent the resource state at the time the event was emitted, which may differ from the current state if subsequent changes have occurred.
</Note>