This feature is designed for powering checkout-like experiences and is currently available for all customers. The API and defaults may evolve slightly over time.

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.

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.

Use this when:

  • You want to preview billing charges before committing to a subscription or update
  • You want to collect payment or confirm user intent first
  • You want to track staged changes separately from active subscriptions

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

  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

​
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

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 optionally pass:

{
  "previously_collected_amount": "2999",
  "description": "Stripe PaymentIntent confirmed"
}

This lets you track what was already paid for externally.

​
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. (We may expose configurable expiry in the future.)

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

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.

Was this page helpful?