---
title: "Adjust Subscription"
method: POST
path: "/api/v1/subscriptions/{id}/adjust"
tags: ["Subscriptions"]
---

# Adjust Subscription

`POST /api/v1/subscriptions/{id}/adjust`

Note: Immediate adjustments are in private preview (Please let us know you use this feature: https://github.com/flowglad/flowglad/issues/616). Adjustments at the end of the current billing period are generally available.

## Path parameters

- `id` string, required

## Request body

- object
  - `adjustment` union, required
    - object
      - `timing` 'immediately', required — Note: Immediate adjustments are in private preview. Please let us know you use this feature: https://github.com/flowglad/flowglad/issues/616.
      - `newSubscriptionItems` union[], required
        - union
          - SubscriptionItemInsert
            - `subscriptionId` string, required
            - `name` string, nullable
            - `addedDate` integer, required — Epoch milliseconds.
            - `priceId` string, required
            - `unitPrice` union, required
              - …
            - `quantity` integer, required — A positive integer
            - `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.
          - 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, required
            - `unitPrice` union, required
              - …
            - `quantity` integer, required — A positive integer
            - `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.
      - `prorateCurrentBillingPeriod` boolean, required
    - 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, required
            - `unitPrice` union, required
              - …
            - `quantity` integer, required — A positive integer
            - `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.
          - 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, required
            - `unitPrice` union, required
              - …
            - `quantity` integer, required — A positive integer
            - `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.

## Response `200`

Successful response

- object
  - `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
      - `priceId` string, nullable, 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
      - `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
      - `priceId` string, nullable, required
      - `runBillingAtPeriodStart` boolean, nullable, required
      - `interval` unknown, required
      - `intervalCount` unknown, required
      - `billingCycleAnchorDate` unknown, required
      - `name` string, nullable, required
      - `renews` false, 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, required
    - `unitPrice` union, required
      - integer — A positive integer
      - 0
    - `quantity` integer, required — A positive integer
    - `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.

## Other responses

- `400` — Invalid input data
- `401` — Authorization not provided
- `403` — Insufficient access
- `500` — Internal server error

## Changes

- **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 changed from no type 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 changed from no type to `object` for status `200`
  - …9 more
- **2025-06-25** `0cf7bce0c17d` — 42 breaking, 3 info
  - removed `subschema #1, subschema #2` from the `adjustment` request property `anyOf` list
  - the `subscription` response's property type changed from `object` to no type for status `200`
  - the `subscriptionItems/items/` response's property type changed from `object` to no type for status `200`
  - removed the required property `subscription/backupPaymentMethodId` from the response with the `200` status
  - …41 more
- **2025-04-28** `00982324965d` — 1 breaking, 5 info
  - removed `subschema #1, subschema #2` from the `adjustment` request property `anyOf` list
  - added `subschema #1, subschema #2` to the `adjustment` request property `anyOf` list
  - added the required property `subscription/createdByCommit` to the response with the `200` status
  - added the required property `subscription/updatedByCommit` to the response with the `200` status
  - …2 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/d53efdb1a902/schema)