Skip to main content

Create Subscription Line Items

The Create Line Items endpoint enables you to add line items to a customer's existing subscriptions.

You can call the Create Line Items endpoint as an integration, or you can call it on behalf of a customer (such as in response to selections in a customer portal). The endpoint behaves slightly different in each scenario.

This document contains reference information to help you call the Create Line Items endpoint in either scenario.

note

Adding line items to multi-currency subscriptions is not supported at this time. To add line items with this endpoint, the subscription's base_currency and charged_currency must match.

Adding line items as an integration​

To call the Create Line Items endpoint as an integration, include the following information in your request for each line item you want to add:

  • platform_product_id
  • platform_variant_id
  • quantity
  • (Optional) price
  • (Optional) subscription_group_id

Set line item price​

When directly setting the price of the line item, the price value must be in the charged_currency of the subscription, and it must be in the base currency unit (i.e., cents). This price is the final output price of the line item on this order; any applicable subscription group discounts or price changes are not applied.

For example, if you include price: 4000 in the request body, and the charged_currency of the subscription is CAD, then the line item price is set to $40.00 CAD per-unit for all upcoming orders.

If you do not give a price in the request body, Bold sets the price of the line item to the product variant's price. If you do not give a price or subscription group ID in the request body, then any applicable discounts are taken from the subscription group that the product was most recently added to. Learn more about setting the subscription group discount in the next section.

For example, if you do not include a price in the request body and the product variant's price with subscription group discounts applied is $20.00 CAD, then the line item price is set to $20.00 CAD per unit for all upcoming orders.

Set subscription group discount​

note

If you include price in the request body, then subscription_group_id will be ignored.

If you would like to apply a discount to the line item from a specific subscription group, you must include the subscription_group_id of the subscription group in the request body. Learn more about finding subscription group IDs.

If you do not give a subscription group in the request body, then any applicable discounts are taken from the subscription group that the product was most recently added to.

Adding line items on behalf of a customer​

To call the Create Line Items endpoint on behalf of a customer (such as in response to selections in a customer portal), your request must include the following for each line item you want to add:

  • platform_product_id
  • platform_variant_id
  • quantity

If you are calling the endpoint on behalf of a customer, you cannot set price or subscription_group_id from the request body. Bold sets the price of the line item to the product variant's price. Any applicable discounts are taken from the subscription group that the product was most recently added to.

For example, if the product variant's price with subscription group discounts applied is $20.00 CAD, then the line item price is set to $20.00 CAD per-unit for all upcoming orders.