--- title: "Adjust Subscription" method: POST path: "/api/v1/subscriptions/{id}/adjust" tags: ["Subscriptions"] --- # Adjust Subscription `POST /api/v1/subscriptions/{id}/adjust` Adjust an active subscription by changing its plan or quantity. Supports immediate adjustments with proration, end-of-billing-period adjustments for downgrades, and auto timing that automatically chooses based on whether it's an upgrade or downgrade. Also supports priceSlug for referencing prices by slug instead of id. For immediate adjustments with proration, this endpoint waits for the billing run to complete before returning, ensuring the subscription is fully updated. ## Path parameters - `id` string, required ## Request body - object - `adjustment` union, required - object - `timing` 'immediately', required — Apply the adjustment immediately. - `newSubscriptionItems` union[], required - union - SubscriptionItemInsert - `subscriptionId` string, required - `name` string, nullable - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean - SubscriptionItemRecord - `id` string, required - `createdAt` integer, required — Epoch milliseconds. - `updatedAt` integer, required — Epoch milliseconds. - `livemode` boolean, required - `subscriptionId` string, required - `name` string, nullable, required - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable, required - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable, required - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean, required - `pricingModelId` string, required - SubscriptionItemWithPriceSlugInput - `subscriptionId` string, required - `name` string, nullable - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean - `priceSlug` string — The slug of the price to subscribe to. If not provided, priceId is required. Price slugs are scoped to the customer's pricing model. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - TerseSubscriptionItem - `priceId` string — The id of the price to subscribe to. If not provided, priceSlug is required. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - `priceSlug` string — The slug of the price to subscribe to. If not provided, priceId is required. Price slugs are scoped to the customer's pricing model. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - `quantity` integer — The quantity of units. Defaults to 1. - `prorateCurrentBillingPeriod` boolean — Whether to prorate the current billing period. Defaults to true for immediate adjustments. - object - `timing` 'at_end_of_current_billing_period', required - `newSubscriptionItems` union[], required - union - SubscriptionItemInsert - `subscriptionId` string, required - `name` string, nullable - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean - SubscriptionItemRecord - `id` string, required - `createdAt` integer, required — Epoch milliseconds. - `updatedAt` integer, required — Epoch milliseconds. - `livemode` boolean, required - `subscriptionId` string, required - `name` string, nullable, required - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable, required - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable, required - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean, required - `pricingModelId` string, required - SubscriptionItemWithPriceSlugInput - `subscriptionId` string, required - `name` string, nullable - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean - `priceSlug` string — The slug of the price to subscribe to. If not provided, priceId is required. Price slugs are scoped to the customer's pricing model. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - TerseSubscriptionItem - `priceId` string — The id of the price to subscribe to. If not provided, priceSlug is required. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - `priceSlug` string — The slug of the price to subscribe to. If not provided, priceId is required. Price slugs are scoped to the customer's pricing model. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - `quantity` integer — The quantity of units. Defaults to 1. - object - `timing` 'auto', required — Automatically determine timing: upgrades happen immediately, downgrades at end of period. - `newSubscriptionItems` union[], required - union - SubscriptionItemInsert - `subscriptionId` string, required - `name` string, nullable - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean - SubscriptionItemRecord - `id` string, required - `createdAt` integer, required — Epoch milliseconds. - `updatedAt` integer, required — Epoch milliseconds. - `livemode` boolean, required - `subscriptionId` string, required - `name` string, nullable, required - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable, required - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable, required - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean, required - `pricingModelId` string, required - SubscriptionItemWithPriceSlugInput - `subscriptionId` string, required - `name` string, nullable - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable - `unitPrice` union, required - … - `quantity` union, required - … - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean - `priceSlug` string — The slug of the price to subscribe to. If not provided, priceId is required. Price slugs are scoped to the customer's pricing model. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - TerseSubscriptionItem - `priceId` string — The id of the price to subscribe to. If not provided, priceSlug is required. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - `priceSlug` string — The slug of the price to subscribe to. If not provided, priceId is required. Price slugs are scoped to the customer's pricing model. Used to determine whether the subscription is usage-based or not, and set other defaults such as trial period and billing intervals. - `quantity` integer — The quantity of units. Defaults to 1. - `prorateCurrentBillingPeriod` boolean — Whether to prorate if the adjustment is applied immediately. Defaults to true. ## Response `200` Successful response - AdjustSubscriptionOutput - `subscription` union, required - object - `id` string, required - `createdAt` integer, required — Epoch milliseconds. - `updatedAt` integer, required — Epoch milliseconds. - `livemode` boolean, required - `startDate` integer, required — Epoch milliseconds. - `customerId` string, required - `organizationId` string, required - `status` 'trialing' | 'active' | 'past_due' | 'unpaid' | 'cancellation_scheduled' | 'incomplete' | 'incomplete_expired' | 'canceled' | 'paused', required - `defaultPaymentMethodId` string, nullable, required - `backupPaymentMethodId` string, nullable, required - `trialEnd` integer, nullable — Epoch milliseconds. - `currentBillingPeriodStart` integer, nullable — Epoch milliseconds. - `currentBillingPeriodEnd` integer, nullable — Epoch milliseconds. - `metadata` Metadata — JSON object - `canceledAt` integer, nullable — Epoch milliseconds. - `cancelScheduledAt` integer, nullable — Epoch milliseconds. - `cancellationReason` string, nullable, required - `replacedBySubscriptionId` string, nullable, required - `isFreePlan` boolean, nullable, required - `doNotCharge` boolean, nullable, required - `priceId` string, required - `runBillingAtPeriodStart` boolean, nullable, required - `interval` 'day' | 'week' | 'month' | 'year', required - `intervalCount` integer, required — A positive integer - `billingCycleAnchorDate` integer, nullable — Epoch milliseconds. - `name` string, nullable, required - `renews` true, required - `pricingModelId` string, required - `current` boolean, required — Whether the subscription is current (statuses "active", "trialing", "past_due", or "cancellation_scheduled") - object - `id` string, required - `createdAt` integer, required — Epoch milliseconds. - `updatedAt` integer, required — Epoch milliseconds. - `livemode` boolean, required - `startDate` integer, required — Epoch milliseconds. - `customerId` string, required - `organizationId` string, required - `status` 'active' | 'canceled' | 'credit_trial', required - `defaultPaymentMethodId` string, nullable, required - `backupPaymentMethodId` string, nullable, required - `trialEnd` unknown, required - `currentBillingPeriodStart` unknown, required - `currentBillingPeriodEnd` unknown, required - `metadata` Metadata — JSON object - `canceledAt` integer, nullable — Epoch milliseconds. - `cancelScheduledAt` integer, nullable — Epoch milliseconds. - `cancellationReason` string, nullable, required - `replacedBySubscriptionId` string, nullable, required - `isFreePlan` boolean, nullable, required - `doNotCharge` boolean, nullable, required - `priceId` string, required - `runBillingAtPeriodStart` boolean, nullable, required - `interval` unknown, required - `intervalCount` unknown, required - `billingCycleAnchorDate` unknown, required - `name` string, nullable, required - `renews` false, required - `pricingModelId` string, required - `current` boolean, required — Whether the subscription is current (statuses "active", "trialing", "past_due", "cancellation_scheduled", or "credit_trial") - `subscriptionItems` SubscriptionItemRecordOutput[], required - `id` string, required - `createdAt` integer, required — Epoch milliseconds. - `updatedAt` integer, required — Epoch milliseconds. - `livemode` boolean, required - `subscriptionId` string, required - `name` string, nullable, required - `addedDate` integer, required — Epoch milliseconds. - `priceId` string, nullable, required - `unitPrice` union, required - integer — A positive integer - 0 - `quantity` union, required - integer — A positive integer - 0 - `metadata` Metadata — JSON object - `type` 'static', required - `externalId` string, nullable, required - `expiredAt` integer, nullable — Used as a flag to soft delete a subscription item without losing its history for auditability. If set, it will be removed from the subscription items list and will not be included in the billing period item list. Epoch milliseconds. - `manuallyCreated` boolean, required - `pricingModelId` string, required - `resolvedTiming` 'immediately' | 'at_end_of_current_billing_period', required — The actual timing applied. When 'auto' timing is requested, this indicates whether the adjustment was applied immediately (for upgrades) or at the end of the billing period (for downgrades). - `isUpgrade` boolean, required — Whether this adjustment is an upgrade (true) or downgrade/lateral move (false). An upgrade means the new plan total is greater than the old plan total. ## Other responses - `400` — Invalid input data - `401` — Authorization not provided - `403` — Insufficient access - `500` — Internal server error ## Changes - **2026-01-11** `599bbd902d65` — 14 info - added `#/components/schemas/SubscriptionItemWithPriceSlugInput, #/components/schemas/TerseSubscriptionItem` to the `adjustment/oneOf[#/components/schemas/AdjustSubscriptionAtEndOfCurrentBillingPeriodInput]/newSubscriptionItems/items/` request property `anyOf` list - added `#/components/schemas/SubscriptionItemWithPriceSlugInput, #/components/schemas/TerseSubscriptionItem` to the `adjustment/oneOf[#/components/schemas/AdjustSubscriptionImmediatelyInput]/newSubscriptionItems/items/` request property `anyOf` list - the request property `adjustment/oneOf[#/components/schemas/AdjustSubscriptionImmediatelyInput]/prorateCurrentBillingPeriod` became optional - the `prorateCurrentBillingPeriod` request property default value `true` was added - …10 more - **2025-10-18** `a1eeb4fac4d6` — 4 breaking, 9 info - removed `subschema #1, subschema #2` from the `adjustment` request property `anyOf` list - the `adjustment` request property type/format changed from ``/`` to `object`/`` - added `#/components/schemas/StandardSubscriptionRecord, #/components/schemas/NonRenewingSubscriptionRecord` to the `subscription` response property `oneOf` list for the response status `200` - the `subscription` response's property type/format changed from ``/`` to `object`/`` for status `200` - …9 more - …earlier changes not shown [Full history](https://skmtc.dev/flowglad/apis/flowglad-api/changes/api/v1/subscriptions/:id/adjust/post.md) --- [API](https://skmtc.dev/flowglad/apis/flowglad-api.md) · [All operations](https://skmtc.dev/flowglad/apis/flowglad-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/flowglad/flowglad-api/revisions/06c4dd78e137/schema)