> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperline.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create subscription updates

> Create multiple updates to apply at once to an existing subscription.



## OpenAPI

````yaml post /v1/subscriptions/{id}/update-many
openapi: 3.1.0
info:
  title: Hyperline API
  version: 0.0.0
servers:
  - url: https://api.hyperline.co
  - url: https://sandbox.api.hyperline.co
security: []
paths:
  /v1/subscriptions/{id}/update-many:
    post:
      tags:
        - Subscriptions
      summary: Create subscription updates
      description: Create multiple updates to apply at once to an existing subscription.
      operationId: createSubscriptionUpdates
      parameters:
        - schema:
            type: string
          required: true
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSubscriptionUpdates'
      responses:
        '201':
          description: Subscription updates created
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                  required:
                    - id
        '404':
          description: Subscription not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
      security:
        - bearer: []
components:
  schemas:
    CreateSubscriptionUpdates:
      type: object
      properties:
        application_schedule:
          type: string
          enum:
            - immediately
            - scheduled
        apply_at:
          type: string
          format: date-time
          description: >-
            The date when the update should be applied. Required when
            application_schedule is 'scheduled'.
          example: '2024-12-20T16:04:11Z'
        payment_schedule:
          type: string
          enum:
            - immediately
            - next_invoice
            - custom
        charge_at:
          type: string
          format: date-time
          description: >-
            The date when the resulting subscription update should be charged.
            Required when payment_schedule is 'custom'. Must be in the future.
          example: '2024-12-20T16:04:11Z'
        calculation_method:
          type: string
          enum:
            - pro_rata
            - pay_in_full
            - do_not_charge
        precision:
          type: string
          enum:
            - calendar_days
            - milliseconds
          description: >-
            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.
          example: calendar_days
        refund_method:
          type: string
          enum:
            - wallet
            - original_payment_method
            - external
          description: >-
            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:
          type: array
          items:
            anyOf:
              - type: object
                properties:
                  type:
                    anyOf:
                      - type: string
                        enum:
                          - add_product
                      - type: string
                        enum:
                          - add_item
                        deprecated: true
                        description: Deprecated field, please use `add_product`.
                  payload:
                    oneOf:
                      - type: object
                        properties:
                          product_id:
                            type: string
                          product_name:
                            type: string
                          product_description:
                            type: string
                          count:
                            type: number
                            default: 1
                          billing_interval_period:
                            type: string
                            enum:
                              - days
                              - weeks
                              - quarters
                              - months
                              - years
                              - once
                              - all
                          billing_interval_count:
                            type: number
                          start_or_end:
                            type: string
                            enum:
                              - start
                              - end
                          display_interval_dates_in_description:
                            type: boolean
                          type:
                            type: string
                            enum:
                              - fee
                          prices:
                            type: array
                            items:
                              type: object
                              properties:
                                type:
                                  type: string
                                  enum:
                                    - fee
                                amount:
                                  type: number
                                  description: >-
                                    Monetary amount. Expressed in currency's
                                    smallest unit.
                              required:
                                - type
                                - amount
                        required:
                          - product_id
                          - billing_interval_period
                          - billing_interval_count
                          - start_or_end
                          - type
                      - type: object
                        properties:
                          product_id:
                            type: string
                          product_name:
                            type: string
                          product_description:
                            type: string
                          count:
                            type: number
                          billing_interval_period:
                            type: string
                            enum:
                              - days
                              - weeks
                              - quarters
                              - months
                              - years
                              - once
                              - all
                          billing_interval_count:
                            type: number
                          start_or_end:
                            type: string
                            enum:
                              - start
                              - end
                          display_interval_dates_in_description:
                            type: boolean
                          type:
                            type: string
                            enum:
                              - seat
                          prices:
                            type: array
                            items:
                              oneOf:
                                - type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - volume
                                    amount:
                                      type: number
                                      description: >-
                                        Monetary amount. Expressed in currency's
                                        smallest unit.
                                    from:
                                      type: number
                                    to:
                                      type:
                                        - number
                                        - 'null'
                                    on_bucket_incomplete:
                                      type: string
                                      enum:
                                        - pro_rata
                                        - pay_in_full
                                        - do_not_charge
                                      default: pro_rata
                                    unit_count:
                                      type: number
                                      default: 1
                                  required:
                                    - type
                                    - amount
                                    - from
                                    - to
                                  title: Volume price
                                - type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - packaged
                                    amount:
                                      type: number
                                      description: >-
                                        Monetary amount. Expressed in currency's
                                        smallest unit.
                                    from:
                                      type: number
                                    to:
                                      type:
                                        - number
                                        - 'null'
                                    on_bucket_incomplete:
                                      type: string
                                      enum:
                                        - pro_rata
                                        - pay_in_full
                                        - do_not_charge
                                      default: pro_rata
                                    unit_count:
                                      type: number
                                      default: 1
                                  required:
                                    - type
                                    - amount
                                    - from
                                    - to
                                  title: Packaged price
                                - type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - bulk
                                    amount:
                                      type: number
                                      description: >-
                                        Monetary amount. Expressed in currency's
                                        smallest unit.
                                    to:
                                      type:
                                        - number
                                        - 'null'
                                    on_bucket_incomplete:
                                      type:
                                        - string
                                        - 'null'
                                      enum:
                                        - pro_rata
                                        - pay_in_full
                                        - do_not_charge
                                      default: pro_rata
                                    unit_count:
                                      type: number
                                      default: 1
                                  required:
                                    - type
                                    - amount
                                    - to
                                  title: Bulk price
                                - type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - bundle
                                    amount:
                                      type: number
                                      description: >-
                                        Monetary amount. Expressed in currency's
                                        smallest unit.
                                    unit_count:
                                      type: number
                                  required:
                                    - type
                                    - amount
                                    - unit_count
                                  title: Bundle price
                            description: >-
                              Prices of the product. If not specified, the
                              matching prices (depending on the currency,
                              interval, etc) of the product defined in the
                              products catalog/plan are used.
                        required:
                          - product_id
                          - count
                          - billing_interval_period
                          - billing_interval_count
                          - start_or_end
                          - type
                      - type: object
                        properties:
                          product_id:
                            type: string
                          product_name:
                            type: string
                          product_description:
                            type: string
                          count:
                            type: number
                            default: 1
                          billing_interval_period:
                            type: string
                            enum:
                              - days
                              - weeks
                              - quarters
                              - months
                              - years
                              - once
                              - all
                          billing_interval_count:
                            type: number
                          start_or_end:
                            type: string
                            enum:
                              - start
                              - end
                          display_interval_dates_in_description:
                            type: boolean
                          type:
                            type: string
                            enum:
                              - dynamic
                          unit_name:
                            type:
                              - string
                              - 'null'
                          min_amount:
                            type:
                              - number
                              - 'null'
                            description: >-
                              Minimum amount billed. If the final computed
                              amount from the usage for this product is less
                              than this amount, then this value will be used.
                          max_amount:
                            type:
                              - number
                              - 'null'
                            description: >-
                              Maximum amount billed. If the final computed
                              amount from the usage for this product is greater
                              than this amount, then this value will be used.
                          committed_count:
                            type:
                              - number
                              - 'null'
                            description: >-
                              Minimum of units committed. If usage is less than
                              this number, then this value will be used.
                          usage_interval_type:
                            type:
                              - string
                              - 'null'
                            enum:
                              - subscription_commitment
                              - item_payment_interval
                              - full_database
                              - phase_duration
                              - subscription_duration
                              - custom
                            description: >

                              Indicates on which type of interval the usage
                              should be aggregated.


                              - `subscription_commitment`: For the usage
                              contained within the subscription commitment
                              period.

                              - `item_payment_interval`: For the usage contained
                              within the payment interval of the product.

                              - `full_database`: For all the usage we ingested
                              for this product, no matter the period.

                              - `phase_duration`: For the usage contained within
                              the subscription phase.

                              - `custom`: For the usage contained within a
                              custom interval that starts with the phase and
                              renews independently of the billing interval.
                              Requires `usage_interval_count` and
                              `usage_interval_period` to be set.

                              - `subscription_duration`: Deprecated, use
                              `subscription_commitment` instead.
                          usage_interval_count:
                            type:
                              - number
                              - 'null'
                            description: >-
                              Number of `usage_interval_period` units in the
                              custom metering interval. Required when
                              `usage_interval_type` is `custom`.
                          usage_interval_period:
                            type:
                              - string
                              - 'null'
                            enum:
                              - days
                              - weeks
                              - quarters
                              - months
                              - years
                              - once
                              - all
                            description: >-
                              Period unit of the custom metering interval.
                              Required when `usage_interval_type` is `custom`.
                          usage_interval_period_start:
                            type:
                              - string
                              - 'null'
                            description: >-
                              Start date of the first custom metering interval.
                              Defaults to the phase start date when omitted. UTC
                              date time string in the [ISO
                              8601](https://en.wikipedia.org/wiki/ISO_8601)
                              format.
                          only_bill_usage_difference:
                            type:
                              - boolean
                              - 'null'
                            description: >-
                              Only bill the usage difference comparing to the
                              previous period (i.e. actual amount minus last
                              invoice amount). Doesn't apply to the
                              `item_payment_interval` metering interval type.
                          children_usage_aggregation:
                            type:
                              - string
                              - 'null'
                            enum:
                              - sum
                              - max
                            description: >

                              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:
                            type:
                              - number
                              - 'null'
                            description: >-
                              Usage amount already billed on the previous
                              period. Used as the baseline when
                              `only_bill_usage_difference` is enabled.
                          prices:
                            type: array
                            items:
                              oneOf:
                                - type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - volume
                                    amount:
                                      type: number
                                      description: >-
                                        Monetary amount. Expressed in currency's
                                        smallest unit.
                                    from:
                                      type: number
                                    to:
                                      type:
                                        - number
                                        - 'null'
                                    on_bucket_incomplete:
                                      type: string
                                      enum:
                                        - pro_rata
                                        - pay_in_full
                                        - do_not_charge
                                      default: pro_rata
                                    unit_count:
                                      type: number
                                      default: 1
                                  required:
                                    - type
                                    - amount
                                    - from
                                    - to
                                  title: Volume price
                                - type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - packaged
                                    amount:
                                      type: number
                                      description: >-
                                        Monetary amount. Expressed in currency's
                                        smallest unit.
                                    from:
                                      type: number
                                    to:
                                      type:
                                        - number
                                        - 'null'
                                    on_bucket_incomplete:
                                      type: string
                                      enum:
                                        - pro_rata
                                        - pay_in_full
                                        - do_not_charge
                                      default: pro_rata
                                    unit_count:
                                      type: number
                                      default: 1
                                  required:
                                    - type
                                    - amount
                                    - from
                                    - to
                                  title: Packaged price
                                - type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - bulk
                                    amount:
                                      type: number
                                      description: >-
                                        Monetary amount. Expressed in currency's
                                        smallest unit.
                                    to:
                                      type:
                                        - number
                                        - 'null'
                                    on_bucket_incomplete:
                                      type:
                                        - string
                                        - 'null'
                                      enum:
                                        - pro_rata
                                        - pay_in_full
                                        - do_not_charge
                                      default: pro_rata
                                    unit_count:
                                      type: number
                                      default: 1
                                  required:
                                    - type
                                    - amount
                                    - to
                                  title: Bulk price
                                - type: object
                                  properties:
                                    type:
                                      type: string
                                      enum:
                                        - bps
                                    from:
                                      type: number
                                    to:
                                      type:
                                        - number
                                        - 'null'
                                    percentage:
                                      type: number
                                    per_unit_cap:
                                      type:
                                        - number
                                        - 'null'
                                      description: >-
                                        Monetary amount. Expressed in currency's
                                        smallest unit.
                                    per_unit_floor:
                                      type:
                                        - number
                                        - 'null'
                                      description: >-
                                        Monetary amount. Expressed in currency's
                                        smallest unit.
                                    per_unit_fee:
                                      type:
                                        - number
                                        - 'null'
                                      description: >-
                                        Monetary amount. Expressed in currency's
                                        smallest unit.
                                  required:
                                    - type
                                    - from
                                    - to
                                    - percentage
                                    - per_unit_cap
                                    - per_unit_floor
                                    - per_unit_fee
                                  title: BPS price
                            description: >-
                              Prices of the product. If not specified, the
                              matching prices (depending on the currency,
                              interval, etc) of the product defined in the
                              products catalog/plan are used.
                        required:
                          - product_id
                          - billing_interval_period
                          - billing_interval_count
                          - start_or_end
                          - type
                required:
                  - type
                  - payload
                description: Add a new product to bill as part of the subscription.
                title: Add product
              - type: object
                properties:
                  type:
                    anyOf:
                      - type: string
                        enum:
                          - remove_product
                      - type: string
                        enum:
                          - remove_item
                        deprecated: true
                        description: Deprecated field, please use `remove_product`.
                  payload:
                    type: object
                    properties:
                      product_id:
                        type: string
                        description: Product ID.
                        example: itm_FJKlqUb8COXw55
                    required:
                      - product_id
                required:
                  - type
                  - payload
                description: Remove a product from a subscription.
                title: Remove product
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - add_coupon
                  payload:
                    type: object
                    properties:
                      repeat:
                        type: string
                        enum:
                          - once
                          - forever
                          - custom
                          - duration
                        description: >

                          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:
                        type: string
                        description: Coupon ID.
                        example: cou_DKL4Xcb5VSa8CQ
                      apply_at:
                        type: string
                        format: date-time
                        description: >-
                          Coupon first application date. UTC date time string in
                          the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)
                          format.
                        example: '2024-12-20T16:04:11Z'
                      expires_at:
                        type: string
                        format: date-time
                        description: >-
                          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.
                        example: '2024-12-20T16:04:11Z'
                      duration_period:
                        type: string
                        enum:
                          - days
                          - weeks
                          - months
                          - years
                        description: >-
                          Period of time for which the coupon will be applied.
                          Only applies to the `duration` coupon frequency.
                      duration_count:
                        type: number
                        description: >-
                          Number of periods for which the coupon will be
                          applied. Only applies to the `duration` coupon
                          frequency.
                      product_ids:
                        type:
                          - array
                          - 'null'
                        items:
                          type: string
                        description: >-
                          Products the coupon is scoped to on this subscription,
                          read together with `product_scope`: the only
                          discounted products when `include`, the products never
                          discounted when `exclude`, null when `all`. When sent
                          without `product_scope`, it is an `include` list,
                          except that a coupon already stored as `exclude` keeps
                          `exclude` when its phase is updated; when empty or
                          omitted, the catalog coupon's scope is copied.
                        example:
                          - itm_FJKlqUb8COXw55
                      product_scope:
                        type:
                          - string
                          - 'null'
                        enum:
                          - all
                          - include
                          - exclude
                        description: >-
                          Which products the coupon discounts on this
                          subscription. `all`: every product (`product_ids` must
                          be empty). `include`: only the products in
                          `product_ids`. `exclude`: every product except those
                          in `product_ids` (lines without a product stay
                          discounted). When sent, it replaces the catalog
                          coupon's scope together with `product_ids`. When
                          omitted, it is inferred: `include` if `product_ids` is
                          non-empty, else the catalog coupon's scope. On a phase
                          update, a coupon already stored as `exclude` keeps
                          `exclude` when `product_ids` is sent without
                          `product_scope`.
                        example: include
                      billing_item_ids:
                        type: array
                        items:
                          type: string
                        deprecated: true
                        description: Deprecated field, please use `product_ids`.
                    required:
                      - repeat
                      - coupon_id
                required:
                  - type
                  - payload
                description: Add a coupon to a subscription.
                title: Add coupon
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - remove_coupon
                  payload:
                    type: object
                    properties:
                      subscription_coupon_id:
                        type: string
                        description: Coupon identifier in the context of the subscription.
                        example: coos_d9pVekhjoGppuX
                    required:
                      - subscription_coupon_id
                required:
                  - type
                  - payload
                description: Remove a coupon from a subscription.
                title: Remove coupon
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - update_count
                  payload:
                    type: object
                    properties:
                      product_id:
                        type: string
                        description: Product ID.
                        example: itm_FJKlqUb8COXw55
                      count:
                        type: number
                        exclusiveMinimum: 0
                    required:
                      - product_id
                      - count
                required:
                  - type
                  - payload
                description: Update the quantity of a product in a subscription.
                title: Update count
              - type: object
                properties:
                  type:
                    type: string
                    enum:
                      - update_prices
                  payload:
                    type: object
                    properties:
                      product_id:
                        type: string
                        description: Product ID.
                        example: itm_FJKlqUb8COXw55
                      prices:
                        type: array
                        items:
                          $ref: '#/components/schemas/CreatePrice'
                    required:
                      - product_id
                      - prices
                required:
                  - type
                  - payload
                description: Update the pricing of a product in a subscription.
                title: Update prices
      required:
        - application_schedule
        - payment_schedule
        - calculation_method
        - updates
    CreatePrice:
      oneOf:
        - $ref: '#/components/schemas/CreatePriceFee'
        - $ref: '#/components/schemas/CreatePriceVolume'
        - $ref: '#/components/schemas/CreatePricePackaged'
        - $ref: '#/components/schemas/CreatePriceBulk'
        - $ref: '#/components/schemas/CreatePriceBps'
        - $ref: '#/components/schemas/CreatePriceBundle'
      discriminator:
        propertyName: type
        mapping:
          fee: '#/components/schemas/CreatePriceFee'
          volume: '#/components/schemas/CreatePriceVolume'
          packaged: '#/components/schemas/CreatePricePackaged'
          bulk: '#/components/schemas/CreatePriceBulk'
          bps: '#/components/schemas/CreatePriceBps'
          bundle: '#/components/schemas/CreatePriceBundle'
    CreatePriceFee:
      type: object
      properties:
        type:
          type: string
          enum:
            - fee
        amount:
          type: number
          description: Monetary amount. Expressed in currency's smallest unit.
      required:
        - type
        - amount
      title: Fee
    CreatePriceVolume:
      type: object
      properties:
        type:
          type: string
          enum:
            - volume
        amount:
          type: number
          description: Monetary amount. Expressed in currency's smallest unit.
        from:
          type: number
        to:
          type:
            - number
            - 'null'
        on_bucket_incomplete:
          type: string
          enum:
            - pro_rata
            - pay_in_full
            - do_not_charge
          default: pro_rata
        unit_count:
          type: number
          default: 1
      required:
        - type
        - amount
        - from
        - to
      title: Volume
    CreatePricePackaged:
      type: object
      properties:
        type:
          type: string
          enum:
            - packaged
        amount:
          type: number
          description: Monetary amount. Expressed in currency's smallest unit.
        from:
          type: number
        to:
          type:
            - number
            - 'null'
        on_bucket_incomplete:
          type: string
          enum:
            - pro_rata
            - pay_in_full
            - do_not_charge
          default: pro_rata
        unit_count:
          type: number
          default: 1
      required:
        - type
        - amount
        - from
        - to
      title: Packaged
    CreatePriceBulk:
      type: object
      properties:
        type:
          type: string
          enum:
            - bulk
        amount:
          type: number
          description: Monetary amount. Expressed in currency's smallest unit.
        to:
          type:
            - number
            - 'null'
        on_bucket_incomplete:
          type:
            - string
            - 'null'
          enum:
            - pro_rata
            - pay_in_full
            - do_not_charge
          default: pro_rata
        unit_count:
          type: number
          default: 1
      required:
        - type
        - amount
        - to
      title: Bulk
    CreatePriceBps:
      type: object
      properties:
        type:
          type: string
          enum:
            - bps
        from:
          type: number
        to:
          type:
            - number
            - 'null'
        percentage:
          type: number
        per_unit_cap:
          type:
            - number
            - 'null'
          description: Monetary amount. Expressed in currency's smallest unit.
        per_unit_floor:
          type:
            - number
            - 'null'
          description: Monetary amount. Expressed in currency's smallest unit.
        per_unit_fee:
          type:
            - number
            - 'null'
          description: Monetary amount. Expressed in currency's smallest unit.
      required:
        - type
        - from
        - to
        - percentage
        - per_unit_cap
        - per_unit_floor
        - per_unit_fee
      title: BPS
    CreatePriceBundle:
      type: object
      properties:
        type:
          type: string
          enum:
            - bundle
        amount:
          type: number
          description: Monetary amount. Expressed in currency's smallest unit.
        unit_count:
          type: number
      required:
        - type
        - amount
        - unit_count
      title: Bundle
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.