---
title: "Simulate subscription updates"
method: POST
path: "/v1/subscriptions/{id}/simulate-updates"
tags: ["Subscriptions"]
---

# Simulate subscription updates

`POST /v1/subscriptions/{id}/simulate-updates`

Simulate the effect of updates on a subscription without actually applying them.

## Path parameters

- `id` string, required

## Request body

- CreateSubscriptionUpdates
  - `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.
  - `updates` union[], required
    - union
      - object — Add a new product to bill as part of the subscription.
        - `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[]
              - …
          - 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[]
              - …
          - 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[]
              - …
      - object — Remove a product from a subscription.
        - `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.
        - `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.
        - `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.
        - `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.
        - `type` 'update_prices', required
        - `payload` object, required
          - `product_id` string, required — Product ID.
          - `prices` union[], required
            - union
              - …

## Response `200`

Simulation results

- object
  - `amount` number, 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)