Manage Subscription Line Items
The Update Line Items endpoint is flexible and offers several ways for you to manage the line items on a subscription. The following sections outline the ways you can leverage this endpoint to create, modify, and delete line items from a subscription.
Prerequisites
Before making any changes, retrieve the existing list of line items on the subscription using the Get Subscription endpoint. In each of the following scenarios, update the line_items array.
When creating or modifying line items, you must include all line items that exist on that subscription. Any omitted line items will be considered deleted and removed from the subscription.
For the purposes of the examples in this document, imagine that you currently have a single line item on your subscription:
Expand to see example.
{
"subscription": {
"line_items": [
{
"id": 18731,
"subscription_id": 8970,
"platform_id": "1234",
"platform_product_id": "6827217387660",
"platform_variant_id": "39977452273804",
"subscription_group_id": 0,
"subscription_group_billing_rules_id": 0,
"title": "Mini Soy Candle",
"product_name": "Mini Soy Candle",
"variant_name": "black",
"sku": "",
"url": "/products/mini-soy-candle",
"image": "https://example.com/s/files/1/0569/5291/4060/products/mini-soy-candle.jpg?v=1642654190",
"quantity": 1,
"price": 1550,
"price_charged": 1550,
"discounted_price": 1550,
"discounted_price_charged": 1550,
"full_price": 1550,
"full_price_charged": 1550,
"requires_shipping": true,
"grams": 247,
"weight": 0,
"weight_unit": "g",
"taxable": true,
"discounts": [],
"prepaid_metadata": null,
"line_item_attributes": [],
"created_at": "2022-01-20T05:17:57Z",
"updated_at": "2022-02-03T19:37:43Z"
}
]
}
}
Add a new line item
To add a new line item using this endpoint, append the object to the existing line_items array. Refer to the Update Line Items specification for which fields are required.
When adding a new line item using this endpoint, you can ignore the read-only marker and include the appropriate information in each field.
Exclude the id of the new line item, because this value is created by Bold when the line item is saved to Bold's database.
For example, the following snippet shows the request body you would pass to the Update Subscription Line Items endpoint if you wanted to add a "Frog Fishing Lure":
Expand to see example.
{
"subscription": {
"line_items": [
{
"id": 18731,
"subscription_id": 8970,
"platform_id": "1234",
"platform_product_id": "6827217387660",
"platform_variant_id": "39977452273804",
"subscription_group_id": 0,
"subscription_group_billing_rules_id": 0,
"title": "Mini Soy Candle",
"product_name": "Mini Soy Candle",
"variant_name": "black",
"sku": "",
"url": "/products/mini-soy-candle",
"image": "https://example.com/s/files/1/0569/5291/4060/products/mini-soy-candle.jpg?v=1642654190",
"quantity": 1,
"price": 1550,
"price_charged": 1550,
"discounted_price": 1550,
"discounted_price_charged": 1550,
"full_price": 1550,
"full_price_charged": 1550,
"requires_shipping": true,
"grams": 247,
"weight": 0,
"weight_unit": "g",
"taxable": true,
"discounts": [],
"prepaid_metadata": null,
"line_item_attributes": [],
"created_at": "2022-01-20T05:17:57Z",
"updated_at": "2022-02-03T19:37:43Z"
},
{
"subscription_id": 8970,
"platform_id": "4321",
"platform_product_id": "6827282268300",
"platform_variant_id": "39977533571212",
"subscription_group_id": 0,
"subscription_group_billing_rules_id": 0,
"title": "Frog Fishing Lure",
"product_name": "Frog Fishing Lure",
"variant_name": "Steel",
"sku": "",
"url": "/products/frog-fishing-lure",
"image": "https://cdn.shopify.com/s/files/1/0569/5291/4060/products/frog-fishing-lure.jpg?v=1642656541",
"quantity": 1,
"price": 2500,
"price_charged": 2500,
"discounted_price": 2500,
"discounted_price_charged": 2500,
"full_price": 2500,
"full_price_charged": 2500,
"requires_shipping": true,
"grams": 0,
"weight": 0,
"weight_unit": "g",
"taxable": true,
"discounts": null,
"prepaid_metadata": null
}
]
}
}
Alternatively, if you would like to add a new line item without retrieving the list of existing line items, refer to Create Subscription Line Items.
Update an existing line item
To modify an existing line item, simply edit the fields you would like to modify in the existing line_items array.
Some fields are read-only and cannot be modified using this endpoint. Refer to the Update Line Items specification to determine which fields you can and cannot modify. Use the property's existing values for those fields.
For example, the following code snippet shows the request body you would pass to the Update Subscription Line Items endpoint to make a change to the title and price of the "Frog Fishing Lure":
Expand to see example.
{
"subscription": {
"line_items": [
{
"id": 18731,
"subscription_id": 8970,
"platform_id": "1234",
"platform_product_id": "6827217387660",
"platform_variant_id": "39977452273804",
"subscription_group_id": 0,
"subscription_group_billing_rules_id": 0,
"title": "Mini Soy Candle",
"product_name": "Mini Soy Candle",
"variant_name": "black",
"sku": "",
"url": "/products/mini-soy-candle",
"image": "https://example.com/s/files/1/0569/5291/4060/products/mini-soy-candle.jpg?v=1642654190",
"quantity": 1,
"price": 1550,
"price_charged": 1550,
"discounted_price": 1550,
"discounted_price_charged": 1550,
"full_price": 1550,
"full_price_charged": 1550,
"requires_shipping": true,
"grams": 247,
"weight": 0,
"weight_unit": "g",
"taxable": true,
"discounts": [],
"prepaid_metadata": null,
"line_item_attributes": [],
"created_at": "2022-01-20T05:17:57Z",
"updated_at": "2022-02-03T19:37:43Z"
},
{
"id": 14354,
"subscription_id": 8970,
"platform_id": "4321",
"platform_product_id": "6827282268300",
"platform_variant_id": "39977533571212",
"subscription_group_id": 0,
"subscription_group_billing_rules_id": 0,
"title": "*NEW* Frog Fishing Lure",
"product_name": "Frog Fishing Lure",
"variant_name": "Steel",
"sku": "",
"url": "/products/frog-fishing-lure",
"image": "https://example.com/s/files/1/0569/5291/4060/products/frog-fishing-lure.jpg?v=1642656541",
"quantity": 1,
"price": 5000,
"price_charged": 5000,
"discounted_price": 5000,
"discounted_price_charged": 5000,
"full_price": 5000,
"full_price_charged": 5000,
"requires_shipping": true,
"grams": 0,
"weight": 0,
"weight_unit": "g",
"taxable": true,
"discounts": null,
"prepaid_metadata": null
}
]
}
}
Delete a line item
To delete a line item from a subscription, omit the item from the line_items array. A subscription requires at least one line item, so you cannot delete all line items from an active subscription.
For example, the following code snippet shows the request body you would pass to the Update Subscription Line Items endpoint to delete the "Frog Fishing Lure":
Expand to see example.
{
"subscription": {
"line_items": [
{
"id": 18731,
"subscription_id": 8970,
"platform_id": "1234",
"platform_product_id": "6827217387660",
"platform_variant_id": "39977452273804",
"subscription_group_id": 0,
"subscription_group_billing_rules_id": 0,
"title": "Mini Soy Candle",
"product_name": "Mini Soy Candle",
"variant_name": "black",
"sku": "",
"url": "/products/mini-soy-candle",
"image": "https://example.com/s/files/1/0569/5291/4060/products/mini-soy-candle.jpg?v=1642654190",
"quantity": 1,
"price": 1550,
"price_charged": 1550,
"discounted_price": 1550,
"discounted_price_charged": 1550,
"full_price": 1550,
"full_price_charged": 1550,
"requires_shipping": true,
"grams": 247,
"weight": 0,
"weight_unit": "g",
"taxable": true,
"discounts": [],
"prepaid_metadata": null,
"line_item_attributes": [],
"created_at": "2022-01-20T05:17:57Z",
"updated_at": "2022-02-03T19:37:43Z"
}
]
}
}