This feature is still in beta - although it is publicly exposed, we expect to iterate on its exact functionality until generally available.
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.