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

# Create Subscription Version

> Create a new version of a subscription

Creates a new version of an existing subscription. This is used when you need to change a subscription (upgrade, downgrade, add features, etc.).

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the subscription to create a new version for
</ParamField>

## Request

<RequestExample>
  ```json Request theme={null}
  {
    "prices": {
      "existingPriceIds": ["price_0000000000000001"],
      "newPrices": [
        {
          "productId": "prod_0000000000000001",
          "type": "unit",
          "feeType": "metered",
          "billingDirection": "arrears",
          "billingInterval": "monthly",
          "unitPricingModel": {
            "pricePerUnit": "59.99"
          }
        }
      ]
    },
    "priceBundles": [
      {
        "name": "Core Features",
        "description": "Essential platform capabilities",
        "bundleId": "bun_0000000000000001",
        "existingPriceIds": ["price_0000000000000002"],
        "newPrices": [
          {
            "productId": "prod_0000000000000002",
            "type": "unit",
            "feeType": "metered",
            "billingDirection": "arrears",
            "billingInterval": "monthly",
            "unitPricingModel": {
              "pricePerUnit": "29.99"
            }
          }
        ]
      }
    ],
    "changeDescription": "Added new features to enterprise plan",
    "startDate": "2024-02-01T00:00:00Z",
    "isMidCycle": false
  }
  ```
</RequestExample>

<ParamField body="prices" type="object">
  Details about individual prices to include in this subscription version

  <Expandable title="Prices Object Properties">
    <ParamField body="existingPriceIds" type="array">
      Array of existing price IDs to include in this subscription version
    </ParamField>

    <ParamField body="newPrices" type="array">
      Array of new prices to create and include in this subscription version.
      Each price must include the pricing model object matching the `type` field
      (e.g., `unitPricingModel` for type `unit`). See the [Pricing Models API
      Reference](/api-reference/subscription-versions/pricingModels) for all
      supported models and their parameters.

      <Expandable title="Common NewPrice Properties">
        <ParamField body="productId" type="string" required>
          The unique identifier of the product for this price
        </ParamField>

        <ParamField body="type" type="string" required>
          The pricing model type: `unit`, `fixed`, `tiered`, `graduated_tiered`, `prepaid_tiered`, `prepaid_fixed_tiered`, `tiered_percentage`, `graduated_percentage`, `volume_percentage`
        </ParamField>

        <ParamField body="feeType" type="string">
          Fee classification: `fixed` or `metered`. Defaults to the product's fee type if omitted.
        </ParamField>

        <ParamField body="billingDirection" type="string">
          When the charge is collected: `advance` (start of period) or `arrears` (end of period). Defaults to the product's payment terms if omitted.
        </ParamField>

        <ParamField body="billingInterval" type="string" required>
          Billing interval: `monthly`, `quarterly`, or `yearly`
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="priceBundles" type="array">
  Array of price bundles to include in this subscription version

  <Expandable title="PriceBundle Properties">
    <ParamField body="name" type="string" required>
      Name of the price bundle
    </ParamField>

    <ParamField body="description" type="string" required>
      Description of the price bundle
    </ParamField>

    <ParamField body="bundleId" type="string" required>
      Unique identifier of the bundle
    </ParamField>

    <ParamField body="existingPriceIds" type="array">
      Array of existing price IDs to include in this bundle
    </ParamField>

    <ParamField body="newPrices" type="array">
      Array of new prices to create and include in this bundle.
      Each price must include the pricing model object matching the `type` field
      (e.g., `unitPricingModel` for type `unit`). See the [Pricing Models API
      Reference](/api-reference/subscription-versions/pricingModels) for all
      supported models and their parameters.

      <Expandable title="Common NewPrice Properties">
        <ParamField body="productId" type="string" required>
          The unique identifier of the product for this price
        </ParamField>

        <ParamField body="type" type="string" required>
          The pricing model type: `unit`, `fixed`, `tiered`, `graduated_tiered`, `prepaid_tiered`, `prepaid_fixed_tiered`, `tiered_percentage`, `graduated_percentage`, `volume_percentage`
        </ParamField>

        <ParamField body="feeType" type="string">
          Fee classification: `fixed` or `metered`. Defaults to the product's fee type if omitted.
        </ParamField>

        <ParamField body="billingDirection" type="string">
          When the charge is collected: `advance` (start of period) or `arrears` (end of period). Defaults to the product's payment terms if omitted.
        </ParamField>

        <ParamField body="billingInterval" type="string" required>
          Billing interval: `monthly`, `quarterly`, or `yearly`
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="changeDescription" type="string">
  Optional description of what is changing in this version
</ParamField>

<ParamField body="startDate" type="datetime">
  Optional start date for when this version should become active
</ParamField>

<ParamField body="isMidCycle" type="boolean">
  Whether this version change is happening mid-billing cycle
</ParamField>

## Response

<Snippet file="subscription-version-response.mdx" />

<Snippet file="subscription-version-response-fields.mdx" />