Skip to main content
Use a price adjustment to change selected recurring charges on an existing subscription at a future renewal. This guide stages a 5% rent increase as a draft before scheduling it.
Scheduling can send a customer notification immediately. Test the flow on a test operator first. Check the resolved adjustment date and notice settings before scheduling against a real subscription.

​
Before you start

Use a token with public.price_adjustment:read and public.price_adjustment:write. Add public.subscription:read if you retrieve the subscription first. To schedule an adjustment, the subscription must be active, have a Stripe subscription ID, and not be archived or scheduled to end. It must have a future renewal date. The resolved adjustment date must be later than today in the operator’s timezone. Only one scheduled adjustment can await application for a subscription at a time. Drafts do not reserve that slot. A draft can be created before all scheduling conditions are met, so a successful draft does not prove that it can be scheduled. To run this guide’s curl examples, set STORA_ACCESS_TOKEN in your shell to your access token. STORA_ACCESS_TOKEN is an example variable name, not an API requirement. Replace sub_REPLACE below with the subscription ID.

​
Create a draft

Generate an idempotency key once for this adjustment:
Create the draft with the charge types you want to change. This example requests immediate customer notice when you later schedule it:
The response contains price_adjustment. Save its id and set PRICE_ADJUSTMENT_ID to that returned ID for the later requests. Use a negative percentage for a decrease. The percentage must be non-zero and greater than -100. The applies_to flags default to false, so explicitly select at least one charge type before scheduling.

​
Check the date, estimate, and notice

Inspect the returned adjustment before you schedule it:
  1. Check adjust_on. Stora resolves effective_from to the first renewal on or after that date. next_billing_period selects the next renewal.
  2. Check applies_to and percentage against the intended change.
  3. Check estimation.pre_amount and estimation.post_amount. These are estimates from the subscription’s current billing data, not a fixed quote.
  4. Check notification.notice_period, notification.scheduled_at, and notification.sent_at.
Dates use the operator’s timezone. If you need a later renewal, supply a calendar date in effective_from instead of next_billing_period. The example sends no notice while it remains a draft. Its send_immediately setting takes effect only when you schedule it. To give advance notice, use a positive number of days, such as "notice_period": 30. If that explicit period puts the notice date in the past, the request returns 422 with code invalid_notice_period. Choose a later renewal, shorten the period, or request immediate notice if appropriate. If the notice date is today, Stora returns send_immediately. If you omit notification, Stora uses the operator’s default notice period. Unlike an explicit period that would notify in the past, a default that no longer fits resolves to send_immediately. To skip Stora’s customer notification, set "notice_period": null. This requires public.price_adjustment:skip_notifications in addition to the write scope. The extra scope is also required if the operator’s default resolves to no notification, or if you update or schedule a draft that already skips notification.

​
Edit the draft if needed

Use Update a Price Adjustment to change the draft. Omitted fields stay unchanged. You cannot change its subscription. Create a different adjustment for another subscription. If you change effective_from, inspect the newly resolved adjust_on and notice settings again. Estimates are recalculated on each write. A scheduled adjustment cannot be edited. Delete it and create a replacement if the date, percentage, or charge types need to change.

​
Schedule the adjustment

Before scheduling, confirm that the subscription still has the selected charge types and that the estimate reflects the intended change. Scheduling does not guarantee rejection when a selected charge type is absent. If the draft is stale, update it to refresh the estimate. Once you have checked the draft, generate a separate idempotency key for scheduling:
The status becomes pending. Stora checks subscription eligibility again and recalculates the estimate from current prices. Compare the returned estimate with the change you intended. Notifications become active when you schedule. A send_immediately notice is sent then. If the notice period no longer fits before the adjustment date, Stora sends the notice today and reports send_immediately. If scheduling returns 409, retrieve the current adjustment and subscription before trying again. Check for an ineligible subscription, a date that is today or in the past, or another scheduled adjustment. Do not retry a lifecycle conflict indefinitely.

​
Track the outcome

Retrieve the adjustment by ID, or configure webhooks for price-adjustment events. A scheduled adjustment starts as pending. During application it becomes processing, then adjusted when the prices have been applied. The later invoiced state records invoicing, not payment collection. Check billing events separately if you need payment confirmation. Handle price_adjustment.scheduled, price_adjustment.rescheduled, price_adjustment.cancelled, price_adjustment.invoiced, and price_adjustment.failed events. On failure, retrieve the adjustment and investigate before creating another one. Once an adjustment has been applied, it no longer holds the scheduled slot. You can schedule the next one even if the previous adjustment is still awaiting its invoice.

​
Call off a scheduled adjustment

Before it starts processing, delete a pending adjustment to call it off:
Only draft, pending, and cancelled adjustments can be deleted. Deletion does not send a customer cancellation notice. If Stora has already sent the original notice, communicate the cancellation or replacement through your own customer-support process. For timeouts on a create or schedule request, retry with that action’s original idempotency key. See Idempotent requests.