Skip to main content
Every billing-related subscription mutation action in Orb is atomic and transactional. This is an extremely important property because it ensures that side-effects of your actions are all or nothing and all the relevant resources that are created are visible immediately to future callers. Depending on the action, this includes the creation (and deletion) of invoices, credit notes, credit blocks, and more. Often times, it’s useful to understand what resources changed as the result of an action you took. In combination with Orb’s dry run functionality, this can be even more powerful, allowing you to power flows like:
  • Subscription preview: When creating a new subscription, view the line items on the invoice that will be issued for a checkout flow
  • Upgrade preview: When executing a plan change, view the line items on invoices that will be issued, and credit notes that may be created (e.g. as the result of an in-advance fee credit). This can be useful for understanding charges on an upgrade or downgrade.
  • Internal assertions and testing: When executing a backdated subscription action, understand the invoices that will be voided and/or re-issued
Note that the invoices returned by this endpoint are expected to include quantity and usage values that reflect the current state of those resources.

​
Usage

To use this functionality, pass the following header into your subscription mutation call:
  • Key: Include-Changed-Resources
  • Value: true
This will now serialize an extra key on the serialized subscription called changed_resources with the following properties:
  • created_invoices : These are the invoices that Orb will create as the result of this mutation. Note that Orb automatically creates a few lookahead invoices, which are invoices that are expected to exist in the future, so this might include more than the first invoice.
  • voided_invoices: These are the invoices that Orb will void as the result of this mutation.
  • created_credit_notes: These are the credit note objects that Orb will create as the result of this mutation.
  • voided_credit_notes: These are the credit note objects that Orb will void as the result of this mutation.
Note that you should not rely on any IDs returned by these changed resources in the case that you’re using this functionality in combination with the Dry-Run: True header. In these cases, the non-dry-run mutation should create equivalent resources (modulo time drift) but with different IDs.
Currently, this list of changed resources is not exhaustive. Each individual entry is expected to be complete, but there may be other side effects (e.g. the removal of a draft invoice) that isn’t yet returned.

​
Payable invoices only

If you only need the invoices that require immediate payment, you can pass a lighter-weight header value:
  • Key: Include-Changed-Resources
  • Value: payable_invoices
This returns only the created_invoices where is_payable_now is true, skipping voided invoices, credit notes, and expensive metric recomputation. The response shape is the same changed_resources object, but only the created_invoices field will be populated, and only with the payable invoices. This is particularly useful for checkout flows where you only need to know the amount to charge upfront and don’t need the full set of side effects.