Adjust Subscription Orders

The Subscription Adjustments endpoints enable you to modify upcoming orders in single or recurring instances.

This document includes concepts and examples specific to subscription adjustments.

Adjustments

An adjustment is a scheduled change for any subscription or its upcoming orders. Adjustments have three components: the trigger, the action, and the target.

Refer to the Subscription Adjustments endpoints for API examples.

Triggers

The trigger is when the change to the target occurs.

Define the kind of trigger in the type field of the trigger object. You can define a trigger by either the order_count (i.e., the change occurs when the number of successful orders equals or exceeds a designated value) or the order_datetime (i.e., the change occurs on the set date.)

order_count triggers can be further defined using specific values, relative values, and step functions.

Specific value: the exact order count of the order you want to change.
Relative value: the desired order count calculated based on the current order.
- Example: if the desired change happens on the next order, set the relative order count to 1.
Step functions: the desired order count calculated using step size and offset. Step size is the number of orders between each change and offset is the number of orders to skip before adjustments begin. The offset defaults to 0.

Triggers use the target's order_count or order_datetime fields to determine if an action applies. The order_count is the number of successful orders, including the current order. The order_datetime is the date and time the order occurs.

The Create Subscription Adjustments endpoint includes details for each trigger type.

Actions

When trigger criteria are met, the action describes the changes to the target.

The following table lists available actions and their functions:

Name	Function
`add_line_item`	Add a line item to the target.
`update_line_item_quantity`	Updates line item quantity for the target.

The Create Subscription Adjustments endpoint includes details for each action type.

Targets

The target is the subscription or order you want to change.

If the target is order, changes apply to only the order. If the target is subscription, changes apply to the subscription and its subsequent orders.

Adjustment use case examples

The following diagram shows an example of a subscription with four total orders:

Assume the first order has already occurred, making the order_count 1. "Current time" is any time between the first order date (January 1st, 2023) and the second order date (February 1st, 2023).

Let's also define an example line item, Product B, with platform_product_id of "123" and platform_variant_id of "456". Using add_line_item to add one Product B line item, the action payload object becomes:

"action": {
  "type": "add_line_item",
  "platform_product_id": "123",
  "platform_variant_id": "456",
  "quantity": 1
}

For the following sections, refer to the Create Subscription Adjustments endpoint for full example request payloads.

Use the Future Orders endpoints to verify adjusted orders changed as intended. Refer to the View Future Orders guide for more information.

Add a line item to the third order

To add Product B to the third order in the subscription, the adjustment components are defined as shown:

{
  "adjustments": [
    {
      "name": "Product B",
      "description": "Alternate to Product A",
      "target": "order",
      "trigger": {
        "type": "order_count",
        "count": 3
      },
      "action": {
        "type": "add_line_item",
        "platform_variant_id": "123",
        "platform_product_id": "456",
        "quantity": 1
      }
    }
  ]
}