> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stora.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Schedule a subscription price adjustment

> Draft a percentage change, check customer notice, schedule the adjustment, and track its outcome.

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.

> [!WARNING]
>
> 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:

```bash theme={null}
ADJUSTMENT_KEY="$(uuidgen)"
```

[Create the draft](https://docs.stora.co/2025-09/api-reference/price-adjustments/create-a-price-adjustment.md) with the charge types you want to change. This example requests immediate customer notice when you later schedule it:

```bash theme={null}
curl --request POST \
	'https://public-api.stora.co/2025-09/price_adjustments' \
	--header "Authorization: Bearer $STORA_ACCESS_TOKEN" \
	--header 'Content-Type: application/json' \
	--header "Idempotency-Key: $ADJUSTMENT_KEY" \
	--data '{
		"subscription": {"id": "sub_REPLACE"},
		"percentage": 5,
		"effective_from": "next_billing_period",
		"schedule": false,
		"applies_to": {
			"unit_types": true,
			"protection_levels": false,
			"products": false
		},
		"notification": {"notice_period": "send_immediately"}
	}'
```

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](https://docs.stora.co/2025-09/api-reference/price-adjustments/update-a-price-adjustment.md) 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:

```bash theme={null}
SCHEDULE_KEY="$(uuidgen)"

curl --request POST \
	"https://public-api.stora.co/2025-09/price_adjustments/$PRICE_ADJUSTMENT_ID/schedule" \
	--header "Authorization: Bearer $STORA_ACCESS_TOKEN" \
	--header "Idempotency-Key: $SCHEDULE_KEY"
```

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](https://docs.stora.co/2025-09/api-reference/price-adjustments/show-a-price-adjustment.md) by ID, or configure [webhooks](https://docs.stora.co/2025-09/guides/webhooks.md) 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](https://docs.stora.co/2025-09/api-reference/price-adjustments/delete-a-price-adjustment.md) to call it off:

```bash theme={null}
curl --request DELETE \
	"https://public-api.stora.co/2025-09/price_adjustments/$PRICE_ADJUSTMENT_ID" \
	--header "Authorization: Bearer $STORA_ACCESS_TOKEN"
```

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](https://docs.stora.co/2025-09/guides/requests.md#idempotent-requests).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.