Orb’s Pending Changes feature lets you stage a subscription change—like creating a new subscription or editing an existing one—without applying it immediately. This gives you full control over when the change takes effect, usually after payment is collected or other validation is complete. This makes it possible to persist subscription changes in Orb without applying them, giving you access to the full power of Orb’s billing model—including invoice generation and change tracking—even before you commit to a subscription. That means you can use pending changes to power your application’s billing UI or confirmation flows in out-of-band workflows, such as signup experiences or manual payment collection flows. It’s especially useful for powering checkout flows, where you want to preview charges, collect payment, and only then commit to the subscription or mutation. You’d use a pending change instead of creating a subscription directly when:
  • You want to treat the subscription as unentitled until payment is confirmed.
  • You need to control the first payment flow yourself, especially if you don’t want Orb to immediately issue a fixed fee invoice.
  • You want to show your user an invoice preview before creating the subscription — which makes this ideal for powering checkout flows.
  • These benefits apply both to creating new subscriptions and mutating existing ones.

​
Example use case: Checkout flow

pending-change
  1. Backend calls POST /subscriptions with header Create-Pending-Subscription-Change: true
  2. Orb returns the subscription preview and a pending_subscription_change ID
  3. Backend uses the invoice preview to create a PaymentIntent with Stripe
  4. Frontend collects + confirms payment
  5. Backend calls /subscription_changes/{id}/apply once payment is successful, usually providing the previously_collected_amount to cover the initial invoice.

​
Usage

To stage a pending change, pass this header on any subscription mutation endpoint: 
Create-Pending-Subscription-Change: true
This applies to the following subscription mutations: The mutation will:
  • Return a pending_subscription_change in the subscription response
  • Show the post-change state of the subscription (acts as a preview)
  • Prevent further changes until this change is applied or canceled
You can only have one pending change at a time per subscription.

​
Follow-up actions

Once you’ve staged a change, use the following endpoints to manage it:

​
Fetch the pending change

GET /subscription_changes/{subscription_change_id}
Returns full metadata, including the intended post-change subscription and customer info. This can be used to:
  • View what will be changed
  • Extract associated invoice amounts
  • Display checkout UI to your user

​
Apply the change

You should explicitly pass previously_collected_amount when applying a change if payment has been collected for the initial invoice to ensure that Orb’s initial invoice is a $0 charge that is automatically marked as paid.
POST /subscription_changes/{subscription_change_id}/apply
Applies the change. If an invoice was created with in-advance charges, it will be issued immediately. You can pass: 
{
  "previously_collected_amount": "2999",
  "description": "Stripe PaymentIntent confirmed"
}
This lets you track what was already paid for externally, and is in terms of the customer currency. The previously_collected_amount will be added to the customer balance, and is important if you’d like to avoid a double charge for the initial invoice (or any subsequent invoices that should be covered by the balance).

​
Cancel the change

POST /subscription_changes/{subscription_change_id}/cancel
Cancels the pending change. This is required if you want to mutate the subscription again or if the user drops off.

​
Expiration

Pending changes expire automatically after 1 day. This prevents abandoned sessions from blocking further changes.

​
Previewing charges

The subscription returned when a pending change is staged reflects the intended state. To understand the associated invoices:
  • Inspect the changed_resources field on the subscription
  • Look at created_invoices, which include both immediate and lookahead (upcoming beyond that) invoices
Resources within changed_resources are a preview of the invoicing changes that will be made. After applying, you can expect the shape of newly created invoices to match but not the id.
This can help:
  • Identify the invoice to pay in your integration
  • Validate invoice totals before confirmation
Subscriptions with a pending change cannot be mutated again until the change is applied or canceled.

​
Additional behavior notes

  • Pending changes can be used on existing subscriptions, not just new ones. This includes actions like plan changes or price updates. Just note that you cannot perform another mutation while a pending change exists.
  • If you’re using pending changes to create a new subscription, you won’t be able to fetch it by ID until the change is applied.
  • Pending subscriptions are skipped in migrations. They must be confirmed before they’re considered active.
  • Pending subscriptions do not appear in data exports. This avoids polluting analytics or reporting pipelines with draft states.
In Orb, you’ll see these resource events for pending changes when:
  • A new pending change is created
  • A pending change expires
  • A pending change is applied
  • A pending change is canceled
These events appear on the customer timeline, and are attached to either the customer or subscription depending on whether the change is for a new subscription or an existing one.

​
Frequently asked questions

​
Can I change the expiration time for a pending change?

Not today — all pending changes expire after 24 hours by default. We may expose a configurable expiration in the future.

​
Can I apply a pending change if no invoice was generated?

Yes. If the change doesn’t result in a charge (e.g. only free metered prices were added), you can still apply the change without issue.

​
What happens if I try to apply the same change twice?

Pending changes are single-use. Once applied or canceled, they cannot be reused — you’ll receive an error if you try.

​
What happens if a payment fails after I apply the change?

Orb has no built-in rollback for this case. You’re expected to confirm payment externally before calling the apply endpoint. If the payment fails after applying, you’ll need to cancel the subscription or issue a refund manually.