> ## Documentation Index > Fetch the complete documentation index at: https://flowglad.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Adjust Subscription > 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. ## OpenAPI ````yaml https://app.flowglad.com/api/openapi post /api/v1/subscriptions/{id}/adjust openapi: 3.1.0 info: title: Flowglad API version: 0.0.1 servers: - url: https://app.flowglad.com security: [] externalDocs: url: https://docs.flowglad.com paths: /api/v1/subscriptions/{id}/adjust: post: tags: - Subscriptions summary: Adjust Subscription description: >- 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. operationId: subscriptions-adjust parameters: - in: path name: id schema: type: string required: true requestBody: required: true content: application/json: schema: type: object properties: adjustment: oneOf: - $ref: '#/components/schemas/AdjustSubscriptionImmediatelyInput' - $ref: >- #/components/schemas/AdjustSubscriptionAtEndOfCurrentBillingPeriodInput - $ref: '#/components/schemas/AdjustSubscriptionAutoTimingInput' type: object discriminator: propertyName: timing mapping: immediately: $ref: >- #/components/schemas/AdjustSubscriptionImmediatelyInput at_end_of_current_billing_period: $ref: >- #/components/schemas/AdjustSubscriptionAtEndOfCurrentBillingPeriodInput auto: $ref: '#/components/schemas/AdjustSubscriptionAutoTimingInput' required: - adjustment responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/AdjustSubscriptionOutput' '400': description: Invalid input data content: application/json: schema: $ref: '#/components/schemas/error.BAD_REQUEST' '401': description: Authorization not provided content: application/json: schema: $ref: '#/components/schemas/error.UNAUTHORIZED' '403': description: Insufficient access content: application/json: schema: $ref: '#/components/schemas/error.FORBIDDEN' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR' security: - ApiKeyAuth: [] components: schemas: AdjustSubscriptionImmediatelyInput: type: object properties: timing: description: Apply the adjustment immediately. type: string const: immediately newSubscriptionItems: type: array items: anyOf: - $ref: '#/components/schemas/SubscriptionItemInsert' - $ref: '#/components/schemas/SubscriptionItemRecord' - $ref: '#/components/schemas/SubscriptionItemWithPriceSlugInput' - $ref: '#/components/schemas/TerseSubscriptionItem' prorateCurrentBillingPeriod: description: >- Whether to prorate the current billing period. Defaults to true for immediate adjustments. default: true type: boolean required: - timing - newSubscriptionItems AdjustSubscriptionAtEndOfCurrentBillingPeriodInput: type: object properties: timing: type: string const: at_end_of_current_billing_period newSubscriptionItems: type: array items: anyOf: - $ref: '#/components/schemas/SubscriptionItemInsert' - $ref: '#/components/schemas/SubscriptionItemRecord' - $ref: '#/components/schemas/SubscriptionItemWithPriceSlugInput' - $ref: '#/components/schemas/TerseSubscriptionItem' required: - timing - newSubscriptionItems AdjustSubscriptionAutoTimingInput: type: object properties: timing: description: >- Automatically determine timing: upgrades happen immediately, downgrades at end of period. type: string const: auto newSubscriptionItems: type: array items: anyOf: - $ref: '#/components/schemas/SubscriptionItemInsert' - $ref: '#/components/schemas/SubscriptionItemRecord' - $ref: '#/components/schemas/SubscriptionItemWithPriceSlugInput' - $ref: '#/components/schemas/TerseSubscriptionItem' prorateCurrentBillingPeriod: description: >- Whether to prorate if the adjustment is applied immediately. Defaults to true. default: true type: boolean required: - timing - newSubscriptionItems AdjustSubscriptionOutput: type: object properties: subscription: $ref: '#/components/schemas/SubscriptionClientSelectSchema' subscriptionItems: type: array items: $ref: '#/components/schemas/SubscriptionItemRecordOutput' resolvedTiming: description: >- 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). type: string enum: - immediately - at_end_of_current_billing_period isUpgrade: description: >- 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. type: boolean required: - subscription - subscriptionItems - resolvedTiming - isUpgrade additionalProperties: false error.BAD_REQUEST: title: Invalid input data error (400) description: The error information example: code: BAD_REQUEST message: Invalid input data issues: [] type: object properties: message: description: The error message example: Invalid input data type: string code: description: The error code example: BAD_REQUEST type: string issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false error.UNAUTHORIZED: title: Authorization not provided error (401) description: The error information example: code: UNAUTHORIZED message: Authorization not provided issues: [] type: object properties: message: description: The error message example: Authorization not provided type: string code: description: The error code example: UNAUTHORIZED type: string issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false error.FORBIDDEN: title: Insufficient access error (403) description: The error information example: code: FORBIDDEN message: Insufficient access issues: [] type: object properties: message: description: The error message example: Insufficient access type: string code: description: The error code example: FORBIDDEN type: string issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false error.INTERNAL_SERVER_ERROR: title: Internal server error error (500) description: The error information example: code: INTERNAL_SERVER_ERROR message: Internal server error issues: [] type: object properties: message: description: The error message example: Internal server error type: string code: description: The error code example: INTERNAL_SERVER_ERROR type: string issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false SubscriptionItemInsert: $ref: '#/components/schemas/StaticSubscriptionItemClientInsertSchema' SubscriptionItemRecord: $ref: '#/components/schemas/StaticSubscriptionItemClientSelectSchema' SubscriptionItemWithPriceSlugInput: type: object properties: subscriptionId: type: string name: anyOf: - type: string - type: 'null' addedDate: description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 priceId: anyOf: - type: string - type: 'null' unitPrice: anyOf: - description: A positive integer type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: number const: 0 quantity: anyOf: - description: A positive integer type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: number const: 0 metadata: anyOf: - $ref: '#/components/schemas/Metadata' - type: 'null' type: type: string const: static externalId: anyOf: - type: string - type: 'null' expiredAt: description: >- 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. anyOf: - description: >- 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. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' manuallyCreated: type: boolean priceSlug: description: >- 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. type: string required: - subscriptionId - addedDate - unitPrice - quantity - type TerseSubscriptionItem: type: object properties: priceId: description: >- 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. type: string priceSlug: description: >- 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. type: string quantity: description: The quantity of units. Defaults to 1. default: 1 type: integer exclusiveMinimum: 0 maximum: 9007199254740991 SubscriptionClientSelectSchema: oneOf: - $ref: '#/components/schemas/StandardSubscriptionRecord' - $ref: '#/components/schemas/NonRenewingSubscriptionRecord' type: object discriminator: propertyName: renews mapping: 'true': $ref: '#/components/schemas/StandardSubscriptionRecord' 'false': $ref: '#/components/schemas/NonRenewingSubscriptionRecord' SubscriptionItemRecordOutput: $ref: '#/components/schemas/StaticSubscriptionItemClientSelectSchemaOutput' StaticSubscriptionItemClientInsertSchema: type: object properties: subscriptionId: type: string name: anyOf: - type: string - type: 'null' addedDate: description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 priceId: anyOf: - type: string - type: 'null' unitPrice: anyOf: - description: A positive integer type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: number const: 0 quantity: anyOf: - description: A positive integer type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: number const: 0 metadata: anyOf: - $ref: '#/components/schemas/Metadata' - type: 'null' type: type: string const: static externalId: anyOf: - type: string - type: 'null' expiredAt: description: >- 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. anyOf: - description: >- 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. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' manuallyCreated: type: boolean required: - subscriptionId - addedDate - unitPrice - quantity - type StaticSubscriptionItemClientSelectSchema: type: object properties: id: type: string createdAt: description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 updatedAt: description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 livemode: type: boolean subscriptionId: type: string name: anyOf: - type: string - type: 'null' addedDate: description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 priceId: anyOf: - type: string - type: 'null' unitPrice: anyOf: - description: A positive integer type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: number const: 0 quantity: anyOf: - description: A positive integer type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: number const: 0 metadata: anyOf: - $ref: '#/components/schemas/Metadata' - type: 'null' type: type: string const: static externalId: anyOf: - type: string - type: 'null' expiredAt: description: >- 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. anyOf: - description: >- 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. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' manuallyCreated: type: boolean pricingModelId: type: string required: - id - createdAt - updatedAt - livemode - subscriptionId - name - addedDate - priceId - unitPrice - quantity - type - externalId - manuallyCreated - pricingModelId Metadata: description: JSON object type: object propertyNames: type: string additionalProperties: anyOf: - type: string maxLength: 500 - type: number - type: boolean StandardSubscriptionRecord: type: object properties: id: type: string createdAt: description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 updatedAt: description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 livemode: type: boolean startDate: description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 customerId: type: string organizationId: type: string status: type: string enum: - trialing - active - past_due - unpaid - cancellation_scheduled - incomplete - incomplete_expired - canceled - paused defaultPaymentMethodId: anyOf: - type: string - type: 'null' backupPaymentMethodId: anyOf: - type: string - type: 'null' trialEnd: anyOf: - description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' currentBillingPeriodStart: anyOf: - description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' currentBillingPeriodEnd: anyOf: - description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' metadata: anyOf: - $ref: '#/components/schemas/Metadata' - type: 'null' canceledAt: anyOf: - description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' cancelScheduledAt: anyOf: - description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' cancellationReason: anyOf: - type: string - type: 'null' replacedBySubscriptionId: anyOf: - type: string - type: 'null' isFreePlan: anyOf: - type: boolean - type: 'null' doNotCharge: anyOf: - type: boolean - type: 'null' priceId: type: string runBillingAtPeriodStart: anyOf: - type: boolean - type: 'null' interval: type: string enum: - day - week - month - year intervalCount: description: A positive integer type: integer exclusiveMinimum: 0 maximum: 9007199254740991 billingCycleAnchorDate: anyOf: - description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' name: anyOf: - type: string - type: 'null' renews: type: boolean const: true pricingModelId: type: string scheduledAdjustmentAt: anyOf: - description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' current: description: >- Whether the subscription is current (statuses "active", "trialing", "past_due", or "cancellation_scheduled") type: boolean required: - id - createdAt - updatedAt - livemode - startDate - customerId - organizationId - status - defaultPaymentMethodId - backupPaymentMethodId - cancellationReason - replacedBySubscriptionId - isFreePlan - doNotCharge - priceId - runBillingAtPeriodStart - interval - intervalCount - name - renews - pricingModelId - current additionalProperties: false NonRenewingSubscriptionRecord: type: object properties: id: type: string createdAt: description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 updatedAt: description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 livemode: type: boolean startDate: description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 customerId: type: string organizationId: type: string status: type: string enum: - active - canceled - credit_trial defaultPaymentMethodId: anyOf: - type: string - type: 'null' backupPaymentMethodId: anyOf: - type: string - type: 'null' trialEnd: description: Omitted. type: 'null' currentBillingPeriodStart: description: Omitted. type: 'null' currentBillingPeriodEnd: description: Omitted. type: 'null' metadata: anyOf: - $ref: '#/components/schemas/Metadata' - type: 'null' canceledAt: anyOf: - description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' cancelScheduledAt: anyOf: - description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' cancellationReason: anyOf: - type: string - type: 'null' replacedBySubscriptionId: anyOf: - type: string - type: 'null' isFreePlan: anyOf: - type: boolean - type: 'null' doNotCharge: anyOf: - type: boolean - type: 'null' priceId: type: string runBillingAtPeriodStart: anyOf: - type: boolean - type: 'null' interval: description: Omitted. type: 'null' intervalCount: description: Omitted. type: 'null' billingCycleAnchorDate: description: Omitted. type: 'null' name: anyOf: - type: string - type: 'null' renews: type: boolean const: false pricingModelId: type: string scheduledAdjustmentAt: anyOf: - description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' current: description: >- Whether the subscription is current (statuses "active", "trialing", "past_due", "cancellation_scheduled", or "credit_trial") type: boolean required: - id - createdAt - updatedAt - livemode - startDate - customerId - organizationId - status - defaultPaymentMethodId - backupPaymentMethodId - trialEnd - currentBillingPeriodStart - currentBillingPeriodEnd - cancellationReason - replacedBySubscriptionId - isFreePlan - doNotCharge - priceId - runBillingAtPeriodStart - interval - intervalCount - billingCycleAnchorDate - name - renews - pricingModelId - current additionalProperties: false StaticSubscriptionItemClientSelectSchemaOutput: type: object properties: id: type: string createdAt: description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 updatedAt: description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 livemode: type: boolean subscriptionId: type: string name: anyOf: - type: string - type: 'null' addedDate: description: Epoch milliseconds. type: integer minimum: -9007199254740991 maximum: 9007199254740991 priceId: anyOf: - type: string - type: 'null' unitPrice: anyOf: - description: A positive integer type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: number const: 0 quantity: anyOf: - description: A positive integer type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: number const: 0 metadata: anyOf: - $ref: '#/components/schemas/Metadata' - type: 'null' type: type: string const: static externalId: anyOf: - type: string - type: 'null' expiredAt: description: >- 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. anyOf: - description: >- 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. type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' manuallyCreated: type: boolean pricingModelId: type: string required: - id - createdAt - updatedAt - livemode - subscriptionId - name - addedDate - priceId - unitPrice - quantity - type - externalId - manuallyCreated - pricingModelId additionalProperties: false securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization ````