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.Add a subscription item
POST /v1/subscription_items
Adds a new item to an existing subscription.
Request parameters
string
required
ID of the subscription to add this item to.
string
required
ID of the price to bill on this item.
number
Quantity of the price to bill. Defaults to
1.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.
boolean
When
true, unused credits from the current period roll over to the next period.number
Number of units included in the base price before metered charges apply.
object
Key-value pairs to attach to this item. Values must be strings.
Response fields
string
required
Unique identifier for the subscription item (e.g.
si_xxx).string
required
ID of the subscription this item belongs to.
string
required
ID of the price being billed.
number
required
Quantity being billed.
boolean
Whether unused credits roll over to the next period.
number
Units included in the base price before metered charges apply.
object
Key-value pairs attached to this item.
Retrieve a subscription item
GET /v1/subscription_items/{id}
Retrieves the details of a single subscription item.
Path parameters
string
required
The ID of the subscription item to retrieve.
Update a subscription item
POST /v1/subscription_items/{id}
Updates an existing subscription item. Only the fields you include are changed.
Path parameters
string
required
The ID of the subscription item to update.
Request parameters
number
New quantity to bill.
string
How to handle proration for this change. One of
create_prorations, always_invoice, or none.boolean
Whether unused credits roll over to the next period.
number
Units included in the base price before metered charges apply.
object
Replace the item’s metadata. Pass
null values to remove specific keys.Remove a subscription item
DELETE /v1/subscription_items/{id}
Removes an item from a subscription. The item is deleted immediately.
Path parameters
string
required
The ID of the subscription item to remove.
Query parameters
string
How to handle proration for the removal. One of
create_prorations, always_invoice, or none. Defaults to none.