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

# Subscription Items API — add and update plan items

> Add, update, and remove items on an active subscription. Supports proration to credit or charge the customer for mid-cycle plan changes.

A subscription item represents a single price on a subscription. Each item links a price to the subscription and tracks its quantity and billing settings. You can add, update, or remove items at any time — proration ensures the customer is charged or credited fairly for changes mid-cycle.

<Note>
  When you add a new item or change an existing item's quantity mid-billing-cycle, Borga can automatically create proration invoice items. These adjust the customer's next invoice to account for the partial period already used. Control this behavior with the `proration_behavior` parameter.
</Note>

***

## Add a subscription item

`POST /v1/subscription_items`

Adds a new item to an existing subscription.

### Request parameters

<ParamField body="subscription" type="string" required>
  ID of the subscription to add this item to.
</ParamField>

<ParamField body="price" type="string" required>
  ID of the price to bill on this item.
</ParamField>

<ParamField body="quantity" type="number">
  Quantity of the price to bill. Defaults to `1`.
</ParamField>

<ParamField body="proration_behavior" type="string">
  How to handle proration when adding this item mid-cycle. One of:

  * `create_prorations` — Create proration invoice items to adjust the next invoice.
  * `always_invoice` — Create proration invoice items and immediately invoice the customer.
  * `none` — Do not create any proration items.
</ParamField>

<ParamField body="credit_rollover" type="boolean">
  When `true`, unused credits from the current period roll over to the next period.
</ParamField>

<ParamField body="included_units" type="number">
  Number of units included in the base price before metered charges apply.
</ParamField>

<ParamField body="metadata" type="object">
  Key-value pairs to attach to this item. Values must be strings.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.borga.is/v1/subscription_items \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx" \
    --header "Content-Type: application/json" \
    --data '{
      "subscription": "sub_01hx9z3k2mfq7nbvd4cw8ej5rt",
      "price": "pri_addon_storage",
      "quantity": 2,
      "proration_behavior": "create_prorations",
      "metadata": {
        "add_on": "storage"
      }
    }'
  ```
</RequestExample>

### Response fields

<ResponseField name="id" type="string" required>
  Unique identifier for the subscription item (e.g. `si_xxx`).
</ResponseField>

<ResponseField name="subscription" type="string" required>
  ID of the subscription this item belongs to.
</ResponseField>

<ResponseField name="price" type="string" required>
  ID of the price being billed.
</ResponseField>

<ResponseField name="quantity" type="number" required>
  Quantity being billed.
</ResponseField>

<ResponseField name="credit_rollover" type="boolean">
  Whether unused credits roll over to the next period.
</ResponseField>

<ResponseField name="included_units" type="number">
  Units included in the base price before metered charges apply.
</ResponseField>

<ResponseField name="metadata" type="object">
  Key-value pairs attached to this item.
</ResponseField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "si_01hx9z3k2mfq7nbvd4cw8ej002",
    "subscription": "sub_01hx9z3k2mfq7nbvd4cw8ej5rt",
    "price": "pri_addon_storage",
    "quantity": 2,
    "credit_rollover": false,
    "included_units": null,
    "metadata": {
      "add_on": "storage"
    }
  }
  ```
</ResponseExample>

***

## Retrieve a subscription item

`GET /v1/subscription_items/{id}`

Retrieves the details of a single subscription item.

### Path parameters

<ParamField path="id" type="string" required>
  The ID of the subscription item to retrieve.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.borga.is/v1/subscription_items/si_01hx9z3k2mfq7nbvd4cw8ej002 \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>

***

## Update a subscription item

`POST /v1/subscription_items/{id}`

Updates an existing subscription item. Only the fields you include are changed.

### Path parameters

<ParamField path="id" type="string" required>
  The ID of the subscription item to update.
</ParamField>

### Request parameters

<ParamField body="quantity" type="number">
  New quantity to bill.
</ParamField>

<ParamField body="proration_behavior" type="string">
  How to handle proration for this change. One of `create_prorations`, `always_invoice`, or `none`.
</ParamField>

<ParamField body="credit_rollover" type="boolean">
  Whether unused credits roll over to the next period.
</ParamField>

<ParamField body="included_units" type="number">
  Units included in the base price before metered charges apply.
</ParamField>

<ParamField body="metadata" type="object">
  Replace the item's metadata. Pass `null` values to remove specific keys.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url https://api.borga.is/v1/subscription_items/si_01hx9z3k2mfq7nbvd4cw8ej002 \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx" \
    --header "Content-Type: application/json" \
    --data '{
      "quantity": 5,
      "proration_behavior": "always_invoice"
    }'
  ```
</RequestExample>

***

## Remove a subscription item

`DELETE /v1/subscription_items/{id}`

Removes an item from a subscription. The item is deleted immediately.

### Path parameters

<ParamField path="id" type="string" required>
  The ID of the subscription item to remove.
</ParamField>

### Query parameters

<ParamField query="proration_behavior" type="string">
  How to handle proration for the removal. One of `create_prorations`, `always_invoice`, or `none`. Defaults to `none`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url "https://api.borga.is/v1/subscription_items/si_01hx9z3k2mfq7nbvd4cw8ej002?proration_behavior=create_prorations" \
    --header "Authorization: Bearer sk_live_..." \
    --header "X-Merchant-Id: mer_xxx"
  ```
</RequestExample>