> ## 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. # Preview Subscription Adjustment > Returns a preview of what a subscription adjustment would look like, including proration amount, payment method, and whether the adjustment can be made. This endpoint does not make any changes to the subscription. Use this to show users what will happen before they commit to an adjustment. ## OpenAPI ````yaml https://app.flowglad.com/api/openapi post /api/v1/subscriptions/{id}/preview-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}/preview-adjust: post: tags: - Subscriptions summary: Preview Subscription Adjustment description: >- Returns a preview of what a subscription adjustment would look like, including proration amount, payment method, and whether the adjustment can be made. This endpoint does not make any changes to the subscription. Use this to show users what will happen before they commit to an adjustment. operationId: subscriptions-previewAdjust 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/PreviewAdjustSubscriptionOutput' '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 PreviewAdjustSubscriptionOutput: type: object properties: canAdjust: description: >- Whether the adjustment can be made. If false, the reason field will contain the explanation. type: boolean reason: description: The reason the adjustment cannot be made, if canAdjust is false. type: string previewGeneratedAt: description: >- Epoch milliseconds when this preview was generated. Useful for staleness detection. type: integer minimum: -9007199254740991 maximum: 9007199254740991 prorationAmount: description: The proration amount that will be charged, if applicable. type: number currentPlanTotal: description: >- The total price of the current plan (sum of unitPrice * quantity for all items). type: number newPlanTotal: description: >- The total price of the new plan (sum of unitPrice * quantity for all items). type: number resolvedTiming: description: >- The resolved timing for the adjustment. When auto timing is requested, this indicates whether it resolved to immediate or end-of-period. type: string enum: - immediately - at_end_of_current_billing_period effectiveDate: description: Epoch milliseconds when the adjustment will take effect. type: integer minimum: -9007199254740991 maximum: 9007199254740991 isUpgrade: description: >- Whether this adjustment is an upgrade (true) or downgrade/lateral move (false). type: boolean percentThroughBillingPeriod: description: The percentage through the current billing period (0-1). type: number billingPeriodEnd: description: Epoch milliseconds when the current billing period ends. type: integer minimum: -9007199254740991 maximum: 9007199254740991 paymentMethod: $ref: '#/components/schemas/PreviewPaymentMethod' description: >- The payment method that will be charged for immediate adjustments with proration. currentSubscriptionItems: description: The current subscription items. type: array items: $ref: '#/components/schemas/PreviewSubscriptionItem' newSubscriptionItems: description: The new subscription items that will be applied. type: array items: $ref: '#/components/schemas/PreviewSubscriptionItem' required: - canAdjust - previewGeneratedAt additionalProperties: false if: required: - canAdjust properties: canAdjust: const: false then: required: - reason 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 PreviewPaymentMethod: type: object properties: id: type: string type: type: string last4: type: string brand: type: string required: - id - type additionalProperties: false PreviewSubscriptionItem: type: object properties: name: type: string unitPrice: type: number quantity: type: number priceId: type: string required: - name - unitPrice - quantity - priceId additionalProperties: false 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 securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization ````