---
title: "Create subscription update"
method: POST
path: "/v1/subscriptions/{id}/update"
tags: ["Subscriptions"]
---

# Create subscription update

`POST /v1/subscriptions/{id}/update`

Create an update to apply on an existing subscription.

## Path parameters

- `id` string, required

## Request body

- union
  - object — Add a new product to bill as part of the subscription.
    - `application_schedule` 'immediately' | 'scheduled', required
    - `apply_at` string, date-time — The date when the update should be applied. Required when application_schedule is 'scheduled'.
    - `payment_schedule` 'immediately' | 'next_invoice' | 'custom', required
    - `charge_at` string, date-time — The date when the resulting subscription update should be charged. Required when payment_schedule is 'custom'. Must be in the future.
    - `calculation_method` 'pro_rata' | 'pay_in_full' | 'do_not_charge', required
    - `precision` 'calendar_days' | 'milliseconds' — Granularity used to prorate the update amount. Defaults to 'calendar_days' when omitted, prorating on whole calendar days; 'milliseconds' prorates on the exact elapsed time, charging the precise partial period.
    - `refund_method` 'wallet' | 'original_payment_method' | 'external' — Override the refund destination when the update generates a refund credit note (e.g. seat reduction). When omitted, falls back to the invoicing entity's `creditNoteWalletRefundEnabled` setting.
    - `type` union, required
      - 'add_product'
      - 'add_item' — Deprecated field, please use `add_product`.
    - `payload` union, required
      - object
        - `product_id` string, required
        - `product_name` string
        - `product_description` string
        - `count` number
        - `billing_interval_period` 'days' | 'weeks' | 'quarters' | 'months' | 'years' | 'once' | 'all', required
        - `billing_interval_count` number, required
        - `start_or_end` 'start' | 'end', required
        - `display_interval_dates_in_description` boolean
        - `type` 'fee', required
        - `prices` object[]
          - `type` 'fee', required
          - `amount` number, required
      - object
        - `product_id` string, required
        - `product_name` string
        - `product_description` string
        - `count` number, required
        - `billing_interval_period` 'days' | 'weeks' | 'quarters' | 'months' | 'years' | 'once' | 'all', required
        - `billing_interval_count` number, required
        - `start_or_end` 'start' | 'end', required
        - `display_interval_dates_in_description` boolean
        - `type` 'seat', required
        - `prices` union[]
          - union
            - object
              - …
            - object
              - …
      - object
        - `product_id` string, required
        - `product_name` string
        - `product_description` string
        - `count` number
        - `billing_interval_period` 'days' | 'weeks' | 'quarters' | 'months' | 'years' | 'once' | 'all', required
        - `billing_interval_count` number, required
        - `start_or_end` 'start' | 'end', required
        - `display_interval_dates_in_description` boolean
        - `type` 'dynamic', required
        - `unit_name` string, nullable
        - `min_amount` number
        - `max_amount` number
        - `committed_count` number
        - `usage_interval_type` 'subscription_commitment' | 'item_payment_interval' | 'full_database' | 'phase_duration' | 'subscription_duration' | 'custom', nullable
        - `usage_interval_count` number, nullable
        - `usage_interval_period` 'days' | 'weeks' | 'quarters' | 'months' | 'years' | 'once' | 'all', nullable
        - `usage_interval_period_start` string, nullable
        - `only_bill_usage_difference` boolean, nullable
        - `children_usage_aggregation` 'sum' | 'max', nullable — Controls whether a parent organization's metered usage is billed on the combined usage of the parent and its direct children, and how per-member values are combined. - `null`: Organization-based usage is disabled. Only the subscription customer's own usage is billed. - `sum`: The usage values of the parent and each direct child are added together (organization total). - `max`: Only the single highest-consuming member (parent or one direct child) is billed.
        - `last_usage_billed` number
        - `prices` union[]
          - union
            - object
              - …
            - object
              - …
            - object
              - …
  - object — Remove a product from a subscription.
    - `application_schedule` 'immediately' | 'scheduled', required
    - `apply_at` string, date-time — The date when the update should be applied. Required when application_schedule is 'scheduled'.
    - `payment_schedule` 'immediately' | 'next_invoice' | 'custom', required
    - `charge_at` string, date-time — The date when the resulting subscription update should be charged. Required when payment_schedule is 'custom'. Must be in the future.
    - `calculation_method` 'pro_rata' | 'pay_in_full' | 'do_not_charge', required
    - `precision` 'calendar_days' | 'milliseconds' — Granularity used to prorate the update amount. Defaults to 'calendar_days' when omitted, prorating on whole calendar days; 'milliseconds' prorates on the exact elapsed time, charging the precise partial period.
    - `refund_method` 'wallet' | 'original_payment_method' | 'external' — Override the refund destination when the update generates a refund credit note (e.g. seat reduction). When omitted, falls back to the invoicing entity's `creditNoteWalletRefundEnabled` setting.
    - `type` union, required
      - 'remove_product'
      - 'remove_item' — Deprecated field, please use `remove_product`.
    - `payload` object, required
      - `product_id` string, required — Product ID.
  - object — Add a coupon to a subscription.
    - `application_schedule` 'immediately' | 'scheduled', required
    - `apply_at` string, date-time — The date when the update should be applied. Required when application_schedule is 'scheduled'.
    - `payment_schedule` 'immediately' | 'next_invoice' | 'custom', required
    - `charge_at` string, date-time — The date when the resulting subscription update should be charged. Required when payment_schedule is 'custom'. Must be in the future.
    - `calculation_method` 'pro_rata' | 'pay_in_full' | 'do_not_charge', required
    - `precision` 'calendar_days' | 'milliseconds' — Granularity used to prorate the update amount. Defaults to 'calendar_days' when omitted, prorating on whole calendar days; 'milliseconds' prorates on the exact elapsed time, charging the precise partial period.
    - `refund_method` 'wallet' | 'original_payment_method' | 'external' — Override the refund destination when the update generates a refund credit note (e.g. seat reduction). When omitted, falls back to the invoicing entity's `creditNoteWalletRefundEnabled` setting.
    - `type` 'add_coupon', required
    - `payload` object, required
      - `repeat` 'once' | 'forever' | 'custom' | 'duration', required — Coupon frequency. Required for inline coupons. Optional when an existing coupon `id` is provided: if omitted, defaults to the catalog coupon's repeat value. - `once`: Will apply the coupon only to the first one invoice. - `forever`: Will apply the coupon to all invoices. - `custom`: Will apply to coupon until a specified expiration date. - `duration`: Will apply the coupon for a specific duration (e.g., 3 months).
      - `coupon_id` string, required — Coupon ID.
      - `apply_at` string, date-time — Coupon first application date. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
      - `expires_at` string, date-time — Coupon expiration date. Only applies to the `custom` coupon frequency. UTC date time string in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format.
      - `duration_period` 'days' | 'weeks' | 'months' | 'years' — Period of time for which the coupon will be applied. Only applies to the `duration` coupon frequency.
      - `duration_count` number — Number of periods for which the coupon will be applied. Only applies to the `duration` coupon frequency.
      - `product_ids` string[] — Product IDs to which the coupon will be applied.
      - `billing_item_ids` string[] — Deprecated field, please use `product_ids`.
  - object — Remove a coupon from a subscription.
    - `application_schedule` 'immediately' | 'scheduled', required
    - `apply_at` string, date-time — The date when the update should be applied. Required when application_schedule is 'scheduled'.
    - `payment_schedule` 'immediately' | 'next_invoice' | 'custom', required
    - `charge_at` string, date-time — The date when the resulting subscription update should be charged. Required when payment_schedule is 'custom'. Must be in the future.
    - `calculation_method` 'pro_rata' | 'pay_in_full' | 'do_not_charge', required
    - `precision` 'calendar_days' | 'milliseconds' — Granularity used to prorate the update amount. Defaults to 'calendar_days' when omitted, prorating on whole calendar days; 'milliseconds' prorates on the exact elapsed time, charging the precise partial period.
    - `refund_method` 'wallet' | 'original_payment_method' | 'external' — Override the refund destination when the update generates a refund credit note (e.g. seat reduction). When omitted, falls back to the invoicing entity's `creditNoteWalletRefundEnabled` setting.
    - `type` 'remove_coupon', required
    - `payload` object, required
      - `subscription_coupon_id` string, required — Coupon identifier in the context of the subscription.
  - object — Update the quantity of a product in a subscription.
    - `application_schedule` 'immediately' | 'scheduled', required
    - `apply_at` string, date-time — The date when the update should be applied. Required when application_schedule is 'scheduled'.
    - `payment_schedule` 'immediately' | 'next_invoice' | 'custom', required
    - `charge_at` string, date-time — The date when the resulting subscription update should be charged. Required when payment_schedule is 'custom'. Must be in the future.
    - `calculation_method` 'pro_rata' | 'pay_in_full' | 'do_not_charge', required
    - `precision` 'calendar_days' | 'milliseconds' — Granularity used to prorate the update amount. Defaults to 'calendar_days' when omitted, prorating on whole calendar days; 'milliseconds' prorates on the exact elapsed time, charging the precise partial period.
    - `refund_method` 'wallet' | 'original_payment_method' | 'external' — Override the refund destination when the update generates a refund credit note (e.g. seat reduction). When omitted, falls back to the invoicing entity's `creditNoteWalletRefundEnabled` setting.
    - `type` 'update_count', required
    - `payload` object, required
      - `product_id` string, required — Product ID.
      - `count` number, required
  - object — Update the pricing of a product in a subscription.
    - `application_schedule` 'immediately' | 'scheduled', required
    - `apply_at` string, date-time — The date when the update should be applied. Required when application_schedule is 'scheduled'.
    - `payment_schedule` 'immediately' | 'next_invoice' | 'custom', required
    - `charge_at` string, date-time — The date when the resulting subscription update should be charged. Required when payment_schedule is 'custom'. Must be in the future.
    - `calculation_method` 'pro_rata' | 'pay_in_full' | 'do_not_charge', required
    - `precision` 'calendar_days' | 'milliseconds' — Granularity used to prorate the update amount. Defaults to 'calendar_days' when omitted, prorating on whole calendar days; 'milliseconds' prorates on the exact elapsed time, charging the precise partial period.
    - `refund_method` 'wallet' | 'original_payment_method' | 'external' — Override the refund destination when the update generates a refund credit note (e.g. seat reduction). When omitted, falls back to the invoicing entity's `creditNoteWalletRefundEnabled` setting.
    - `type` 'update_prices', required
    - `payload` object, required
      - `product_id` string, required — Product ID.
      - `prices` union[], required
        - union
          - object
            - `type` 'fee', required
            - `amount` number, required
          - object
            - `type` 'volume', required
            - `amount` number, required
            - `from` number, required
            - `to` number, nullable, required
            - `on_bucket_incomplete` 'pro_rata' | 'pay_in_full' | 'do_not_charge'
            - `unit_count` number
          - object
            - `type` 'packaged', required
            - `amount` number, required
            - `from` number, required
            - `to` number, nullable, required
            - `on_bucket_incomplete` 'pro_rata' | 'pay_in_full' | 'do_not_charge'
            - `unit_count` number
          - object
            - `type` 'bulk', required
            - `amount` number, required
            - `to` number, nullable, required
            - `on_bucket_incomplete` 'pro_rata' | 'pay_in_full' | 'do_not_charge', nullable
            - `unit_count` number
          - object
            - `type` 'bps', required
            - `from` number, required
            - `to` number, nullable, required
            - `percentage` number, required
            - `per_unit_cap` number, nullable, required
            - `per_unit_floor` number, nullable, required
            - `per_unit_fee` number, nullable, required
          - object
            - `type` 'bundle', required
            - `amount` number, required
            - `unit_count` number, required

## Response `201`

Subscription update created

- object
  - `id` string, required

## Other responses

- `404` — Subscription not found

---

[API](https://skmtc.dev/hyperline/apis/hyperline-api.md) · [All operations](https://skmtc.dev/hyperline/apis/hyperline-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hyperline/hyperline-api/revisions/19fa5f22e39b/schema)