Adding One-Time (à la Carte) Items on Subscriptions

5 min

Operators can add one-time or à la carte items to customer subscriptions. These items can either be added to your next installment order along with your subscribed items or can replace the subscribed items in your next installment order. In both cases, these items will automatically be removed afterwards.

This is useful if, for example, you want to add free items to a customer’s upcoming subscription renewal. Or can be used to allow for customers to deviate from their regularly scheduled programming briefly to try a new line item.

The options are outlined below:

Via Chord OMS

Including Line Items to Add

As an Admin user, you can add and edit one-time items when viewing a customer's subscription page in the line items section. Scroll to the For Next Installment Only section, select the variant to add, the "Add" option, specify the quantity, and click Update.

Once added, the item will be present on the Subscription and added to the next upcoming installment:

Including Line Items to Replace

As an Admin user, you can include items and specify which subscribed items to replace in a given subscription when viewing a customer's subscription page in the line items section. Scroll to the For Next Installment Only section, select the variant(s) to include, select the "Replace" option, specify which product the new lien item will replace (or as a shortcut select "All"), specify the quantity, and click Update.

When the "Replace" option is selected, the Replaces option will populate with all of the current subscription line items. This way, you can specifically pinpoint which particular line item the line item you are adding will replace. If you are looking to replace all current subscribed line items, select "All Items."

Via API

You can also add one-time add or one-time replacement items via API here:

PATCH /api/users/:user_id/subscriptions/:id

An example payload would be:

{
  subscription: {
    line_items_attributes: [
      {
        subscribable_id: 999,     
        quantity: 1,
        one_time: true,
        one_time_replace: false,
        replaces_subscribable_id: null //only required when one_time_replace is true
      }
    ]
  }
}

Relevant Attributes

one_time will flag whether the item is a new addition

one_time_replace will flag whether the item is a replacment item

replaces_subscribable_id is only required when one_time_replace is true.

NOTE: The API will fail with a validation error if one_time_replace and one_time share the same value.

Should you have any questions or need further assistance, please do not hesitate to reach out to [email protected]!