Introducing our brand new Rules Engine —
Read the docs
LogoLogo
Core APIOther APIsChangelog
How-tos
How-tos
  • Introduction
  • Product discovery
    • Product listing page
    • Product page
  • Placing orders
    • Shopping cart
      • Creating a shopping cart
      • Adding products to cart
      • Updating cart quantities
      • Removing products from cart
      • Displaying the cart summary
    • Checkout
      • Adding the customer
      • Adding a billing address
      • Adding a shipping address
      • Selecting a shipping method
      • Selecting a payment method
      • Adding a payment source
      • Adding a gift card or coupon
      • Placing the order
    • Subscriptions
      • Configuring a subscription model
      • Selecting the source order
      • Generating the subscriptions
      • Updating the subscriptions
    • Payments
      • Adyen
        • Adding the payment source
        • Sending back the payment details
        • Configuring the notification webhooks
        • Reusing the payment source
      • Axerve
        • Adding the payment source
        • Updating the payment intent
      • Braintree
        • Adding the payment source
        • Sending back the payment method nonce
        • Accepting local payments
        • Reusing the payment source
      • Checkout.com
        • Adding the payment source
        • Getting the payment details
        • Refreshing pending transactions
        • Reusing the payment source
      • Klarna
        • Adding the payment source
        • Sending back the authorization token
        • Reusing the payment source
      • PayPal
        • Adding the payment source
        • Preparing the payment for execution
      • Stripe
        • Adding the payment source
        • Refreshing the payment source
        • Reusing the payment source
      • Manual payments
        • Adding a wire transfer payment source
      • External payments
        • Adding the payment source
        • Reusing the payment source
    • Auto-capture
      • Enabling the auto-capture
      • Limiting the auto-capture amount
  • inventory
    • Inventory strategies
      • No split
      • Split shipments
      • Split by line items
      • Ship from first available (or primary)
      • Ship from primary
  • FAQ
    • Environments and initial setup
    • Authentication and access tokens
On this page
  • Problem
  • Solution
  • Updating the order subscription
  • Suspending, activating, and cancelling an order subscription
  • Changing the subscription frequency
  • Changing the subscription expiration date
  • Changing the subscription next run date
  • Changing the customer payment source
  • Updating the order subscription items
  • Changing the quantity of a product belonging to a subscription
  • Changing the price of a product belonging to a subscription
  • Changing one of the subscription products
  • Adding a new product to a subscription
  • Removing a product from a subscription
  • More to read
  1. Placing orders
  2. Subscriptions

Updating the subscriptions

How to customize the next subscription occurrences

PreviousGenerating the subscriptionsNextPayments

Last updated 1 year ago

Problem

You have one or more subscriptions from a , based on the . At some point, you may want to suspend some of them, re-activate them, or even change the next subscription occurrences in terms of frequency, items, expiration date, and more.

Solution

Once generated, automatic order subscriptions live a life of their own, meaning that any changes to the associated or source order won't affect the already generated order subscriptions and will eventually apply starting from the next subscription generation only.

To update an already generated subscription you need to edit the itself or the related . You can do it any time in between each run.

Updating the order subscription

Suspending, activating, and cancelling an order subscription

Active order subscriptions can be deactivated (temporarily suspended) and eventually re-activated, or cancelled.

Deactivate

To deactivate an order subscription, send a PATCH request to the /api/order_subscriptions/:id setting the _deactivate trigger attribute to true:

The following request deactivates the subscription identified by the "BkMdJFGdjX" ID:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/order_subscriptions/BkMdJFGdjX' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "order_subscriptions",
      "id": "BkMdJFGdjX",
      "attributes": {
        "_deactivate": true
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated order subscription object with the status set to inactive:

{
  "data": {
    "id": "BkMdJFGdjX",
    "type": "order_subscriptions",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/order_subscriptions/BkMdJFGdjX"
    },
    "attributes": {
      "number": "825",
      "status": "inactive",
      "frequency": "two-month",
      "activate_by_source_order": true,
      "customer_email": "bob@example.com",
      "starts_at": "2023-03-23T14:47:21.136Z",
      "expires_at": "2023-12-31T23:59:59.000Z",
      "next_run_at": "2023-03-30T17:30:00.000Z",
      "occurrencies": 0,
      "errors_count": 0,
      "succeeded_on_last_run": true,
      "options": {
        "activate_by_source_order": true,
        "place_target_order": true
      },
      "created_at": "2023-03-23T14:47:21.138Z",
      "updated_at": "2023-03-23T16:55:19.649Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "market": { ... },
      "subscription_model": { ... },
      "source_order": { ... },
      "customer": { ... },
      "customer_payment_source": { ... },
      "order_subscription_items": { ... },
      "order_factories": { ... },
      "order_copies": { ... },
      "recurring_order_copies": { ... },
      "orders": { ... },
      "events": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}

Activate / Reactivate

To activate an order subscription, send a PATCH request to the /api/order_subscriptions/:id setting the _activate trigger attribute to true:

The following request (re)activates the subscription identified by the "BkMdJFGdjX" ID:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/order_subscriptions/BkMdJFGdjX' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "order_subscriptions",
      "id": "BkMdJFGdjX",
      "attributes": {
        "_activate": true
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated order subscription object with the status set to active:

{
  "data": {
    "id": "BkMdJFGdjX",
    "type": "order_subscriptions",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/order_subscriptions/BkMdJFGdjX"
    },
    "attributes": {
      "number": "825",
      "status": "active",
      "frequency": "two-month",
      "activate_by_source_order": true,
      "customer_email": "bob@example.com",
      "starts_at": "2023-03-23T14:47:21.136Z",
      "expires_at": "2023-12-31T23:59:59.000Z",
      "next_run_at": "2023-03-23T16:55:19.649Z",
      "occurrencies": 0,
      "errors_count": 0,
      "succeeded_on_last_run": true,
      "options": {
        "activate_by_source_order": true,
        "place_target_order": true
      },
      "created_at": "2023-03-23T14:47:21.138Z",
      "updated_at": "2023-03-23T16:55:19.649Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "market": { ... },
      "subscription_model": { ... },
      "source_order": { ... },
      "customer": { ... },
      "customer_payment_source": { ... },
      "order_subscription_items": { ... },
      "order_factories": { ... },
      "order_copies": { ... },
      "recurring_order_copies": { ... },
      "orders": { ... },
      "events": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}

When reactivating an inactive order subscription the next run date could be automatically recomputed to avoid date inconsistencies (e.g. a next occurrence scheduled at a time when the subscription was inactive, in which case is set to be equal to the order subscription's updated_at — i.e. the next run happens as soon as the subscription is reactivated). If needed, you can still update the next_run_at value when passing the _activate trigger attribute to set the next run at the desired date.

Cancel

To cancel an order subscription, send a PATCH request to the /api/order_subscriptions/:id setting the _cancel trigger attribute to true:

The following request cancels the subscription identified by the "mPbnqFvRPN" ID:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/order_subscriptions/mPbnqFvRPN' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "order_subscriptions",
      "id": "mPbnqFvRPN",
      "attributes": {
        "_cancel": true
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated order subscription object with the status set to cancelled:

{
  "data": {
    "id": "mPbnqFvRPN",
    "type": "order_subscriptions",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/order_subscriptions/mPbnqFvRPN"
    },
    "attributes": {
      "number": "826",
      "status": "cancelled",
      "frequency": "weekly",
      "activate_by_source_order": true,
      "customer_email": "bob@example.com",
      "starts_at": "2023-03-23T22:48:18.647Z",
      "expires_at": null,
      "next_run_at": "2023-03-30T22:48:00.000Z",
      "occurrencies": 0,
      "errors_count": 0,
      "succeeded_on_last_run": true,
      "options": {
        "activate_by_source_order": true,
        "place_target_order": true
      },
      "created_at": "2023-03-23T22:48:18.649Z",
      "updated_at": "2023-03-23T22:49:23.289Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "market": { ... },
      "subscription_model": { ... },
      "source_order": { ... },
      "customer": { ... },
      "customer_payment_source": { ... },
      "order_subscription_items": { ... },
      "order_factories": { ... },
      "order_copies": { ... },
      "recurring_order_copies": { ... },
      "orders": { ... },
      "events": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}

Changing the subscription frequency

To update the frequency of an order subscription, send a PATCH request to the /api/order_subscriptions/:id setting the frequency attribute:

The following request changes the frequency of the subscription identified by the "BkMdJFGdjX" ID:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/order_subscriptions/BkMdJFGdjX' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "order_subscriptions",
      "id": "BkMdJFGdjX",
      "attributes": {
        "frequency": "two-month",
        "next_run_at": "2023-05-23T17:30:00.000Z"
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated order subscription object:

{
  "data": {
    "id": "BkMdJFGdjX",
    "type": "order_subscriptions",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/order_subscriptions/BkMdJFGdjX"
    },
    "attributes": {
      "number": "825",
      "status": "active",
      "frequency": "two-month",
      "activate_by_source_order": true,
      "customer_email": "bob@example.com",
      "starts_at": "2023-03-23T14:47:21.136Z",
      "expires_at": "2023-12-31T23:59:59.000Z",
      "next_run_at": "2023-05-23T17:30:00.000Z",
      "occurrencies": 0,
      "errors_count": 0,
      "succeeded_on_last_run": true,
      "options": {
        "activate_by_source_order": true,
        "place_target_order": true
      },
      "created_at": "2023-03-23T14:47:21.138Z",
      "updated_at": "2023-03-23T16:30:19.649Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "market": { ... },
      "subscription_model": { ... },
      "source_order": { ... },
      "customer": { ... },
      "customer_payment_source": { ... },
      "order_subscription_items": { ... },
      "order_factories": { ... },
      "order_copies": { ... },
      "recurring_order_copies": { ... },
      "orders": { ... },
      "events": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}
```

When changing the frequency of an already generated subscription the next run date is not re-computed. That's why we strongly recommend passing also the next_run_at attribute to set the new desired next run date accordingly and avoid possible date inconsistencies (e.g. if you change a subscription frequency from yearly to weekly without setting the next_run_at attribute, the next occurrence will happen next year and not next week as probably expected).

Changing the subscription expiration date

Adding an expiration date to an order subscription is optional. To set or change the expiration date of an order subscription, send a PATCH request to the /api/order_subscriptions/:id setting the expires_at attribute:

The following request changes the expiration date of the subscription identified by the "BkMdJFGdjX" ID:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/order_subscriptions/BkMdJFGdjX' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "order_subscriptions",
      "id": "BkMdJFGdjX",
      "attributes": {
        "expires_at": "2023-12-31T23:59:59.000Z"
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated order subscription object:

{
  "data": {
    "id": "BkMdJFGdjX",
    "type": "order_subscriptions",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/order_subscriptions/BkMdJFGdjX"
    },
    "attributes": {
      "number": "825",
      "status": "active",
      "frequency": "weekly",
      "activate_by_source_order": true,
      "customer_email": "bob@example.com",
      "starts_at": "2023-03-23T14:47:21.136Z",
      "expires_at": "2023-12-31T23:59:59.000Z",
      "next_run_at": "2023-04-07T14:30:00.000Z",
      "occurrencies": 0,
      "errors_count": 0,
      "succeeded_on_last_run": true,
      "options": {
        "activate_by_source_order": true,
        "place_target_order": true
      },
      "created_at": "2023-03-23T14:47:21.138Z",
      "updated_at": "2023-03-23T15:04:57.602Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "market": { ... },
      "subscription_model": { ... },
      "source_order": { ... },
      "customer": { ... },
      "customer_payment_source": { ... },
      "order_subscription_items": { ... },
      "order_factories": { ... },
      "order_copies": { ... },
      "recurring_order_copies": { ... },
      "orders": { ... },
      "events": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}
```

Changing the subscription next run date

To update an order subscription's next occurrence date, send a PATCH request to the /api/order_subscriptions/:id setting the next_run_at attribute:

The following request changes the next occurrence date of the subscription identified by the "BkMdJFGdjX" ID:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/order_subscriptions/BkMdJFGdjX' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "order_subscriptions",
      "id": "BkMdJFGdjX",
      "attributes": {
        "next_run_at": "2023-04-07T14:30:00.000Z"
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated order subscription object:

{
  "data": {
    "id": "BkMdJFGdjX",
    "type": "order_subscriptions",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/order_subscriptions/BkMdJFGdjX"
    },
    "attributes": {
      "number": "825",
      "status": "active",
      "frequency": "weekly",
      "activate_by_source_order": true,
      "customer_email": "bob@example.com",
      "starts_at": "2023-03-23T14:47:21.136Z",
      "expires_at": null,
      "next_run_at": "2023-04-07T14:30:00.000Z",
      "occurrencies": 0,
      "errors_count": 0,
      "succeeded_on_last_run": true,
      "options": {
        "activate_by_source_order": true,
        "place_target_order": true
      },
      "created_at": "2023-03-23T14:47:21.138Z",
      "updated_at": "2023-03-23T14:51:44.646Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "market": { ... },
      "subscription_model": { ... },
      "source_order": { ... },
      "customer": { ... },
      "customer_payment_source": { ... },
      "order_subscription_items": { ... },
      "order_factories": { ... },
      "order_copies": { ... },
      "recurring_order_copies": { ... },
      "orders": { ... },
      "events": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}

The new value for the next_run_at attribute can't be before the moment of the update. Once changed the next run, the subsequent occurrences will be scheduled from the new next_run_at value, based on the order subscription frequency.

Changing the customer payment source

The recurring orders associated to a subscription are placed using the saved customer payment source (if still valid). If you need or want to update it, send a PATCH request to the /api/order_subscriptions/:id setting the customer_payment_source relationship:

The following request associates the customer payment source identified by the "OvEOysMVAD" ID with the order subscription identified by the "BkMdJFGdjX" ID:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/order_subscriptions/BkMdJFGdjX' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "order_subscriptions",
      "id": "BkMdJFGdjX",
      "relationships": {
      "customer_payment_source": {
        "data": {
          "type": "customer_payment_sources",
          "id": "OvEOysMVAD"
        }
      }
    }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated order subscription object:

{
  "data": {
    "id": "BkMdJFGdjX",
    "type": "order_subscriptions",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/order_subscriptions/BkMdJFGdjX"
    },
    "attributes": {
      "number": "825",
      "status": "active",
      "frequency": "weekly",
      "activate_by_source_order": true,
      "customer_email": "bob@example.com",
      "starts_at": "2023-03-23T14:47:21.136Z",
      "expires_at": null,
      "next_run_at": "2023-04-07T14:30:00.000Z",
      "occurrencies": 0,
      "errors_count": 0,
      "succeeded_on_last_run": true,
      "options": {
        "activate_by_source_order": true,
        "place_target_order": true
      },
      "created_at": "2023-03-23T14:47:21.138Z",
      "updated_at": "2023-03-23T14:51:44.646Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "market": { ... },
      "subscription_model": { ... },
      "source_order": { ... },
      "customer": { ... },
      "customer_payment_source": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/order_subscriptions/BkMdJFGdjX/relationships/customer_payment_source",
          "related": "https://yourdomain.commercelayer.io/api/order_subscriptions/BkMdJFGdjX/customer_payment_source"
        }
      },
      "order_subscription_items": { ... },
      "order_factories": { ... },
      "order_copies": { ... },
      "recurring_order_copies": { ... },
      "orders": { ... },
      "events": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}

The new payment source must be one of the available payment sources for the customer (saved in their customer wallet).

Updating the order subscription items

Changing the quantity of a product belonging to a subscription

To change the quantity of a product belonging to a subscription, send a PATCH request to the /api/order_subscriptions_item/:id setting the quantity attribute:

The following request updates the quantity of the order subscription items identified by the "adkLKwFVzG" ID:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/order_subscription_items/adkLKwFVzG' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "order_subscription_items",
      "id": "adkLKwFVzG",
      "attributes": {
        "quantity": 3
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated order subscription item object:

{
  "data": {
    "id": "adkLKwFVzG",
    "type": "order_subscription_items",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/order_subscription_items/adkLKwFVzG"
    },
    "attributes": {
      "quantity": 3,
      "unit_amount_cents": 1490,
      "unit_amount_float": 14.9,
      "formatted_unit_amount": "$14.90",
      "total_amount_cents": 4470,
      "total_amount_float": 44.7,
      "formatted_total_amount": "$44.70",
      "created_at": "2023-03-22T17:56:38.198Z",
      "updated_at": "2023-03-24T16:43:00.807Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "order_subscription": { ... },
      "item": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}

Changing the price of a product belonging to a subscription

To change the unit price of a product belonging to a subscription, send a PATCH request to the /api/order_subscriptions_item/:id setting the unit_amount_cents attribute:

The following request updates the unit price of the order subscription items identified by the "adkLKwFVzG" ID:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/order_subscription_items/adkLKwFVzG' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "order_subscription_items",
      "id": "adkLKwFVzG",
      "attributes": {
        "unit_amount_cents": 1790
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated order subscription item object:

{
  "data": {
    "id": "adkLKwFVzG",
    "type": "order_subscription_items",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/order_subscription_items/adkLKwFVzG"
    },
    "attributes": {
      "quantity": 3,
      "unit_amount_cents": 1790,
      "unit_amount_float": 17.9,
      "formatted_unit_amount": "$17.90",
      "total_amount_cents": 5370,
      "total_amount_float": 53.7,
      "formatted_total_amount": "$53.70",
      "created_at": "2023-03-22T17:56:38.198Z",
      "updated_at": "2023-03-24T16:52:22.968Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "order_subscription": { ... },
      "item": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}

Changing the price of a product belonging to an ongoing subscription overrides the original source order line item price (even if computed from a price tier). The new price will be used for all the next subscription occurrences until further updates.

Changing one of the subscription products

To change one of the products belonging to a subscription, send a PATCH request to the /api/order_subscriptions_item/:id setting the sku_code or bundle_code attribute:

The following request changes the SKU code of the order subscription items identified by the "adkLKwFVzG" ID:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/order_subscription_items/adkLKwFVzG' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "order_subscription_items",
      "id": "adkLKwFVzG",
      "attributes": {
        "sku_code": "TOOTHPASTEMINT150G",
        "unit_amount_cents": null
      }
    }
  }'

On success, the API responds with a 200 OK status code, returning the updated order subscription item object with the correct price:

{
  "data": {
    "id": "adkLKwFVzG",
    "type": "order_subscription_items",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/order_subscription_items/adkLKwFVzG"
    },
    "attributes": {
      "quantity": 3,
      "unit_amount_cents": 890,
      "unit_amount_float": 8.9,
      "formatted_unit_amount": "$8.90",
      "total_amount_cents": 2670,
      "total_amount_float": 26.7,
      "formatted_total_amount": "$26.70",
      "created_at": "2023-03-22T17:56:38.198Z",
      "updated_at": "2023-03-24T18:45:38.876Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "order_subscription": { ... },
      "item": { ... }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}

Adding a new product to a subscription

To manually add a new product to an already generated subscription you just need to create a new order subscription item. To do that, send a POST request to the /api/subscription_items endpoint specifying the quantity attribute and setting the order_subscription and item relationships:

The following request creates a new order subscription item from the item identified by the "nJoqSzPEAq" ID and associates it with the order subscription identified by the "DPAwmFnYkJ" ID:

curl -g -X POST \
  'https://yourdomain.commercelayer.io/api/order_subscription_items' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "order_subscription_items",
      "attributes": {
        "quantity": 1
      },
      "relationships": {
        "order_subscription": {
          "data": {
            "type": "order_subscriptions",
            "id": "DPAwmFnYkJ"
          }
        },
        "item": {
          "data": {
            "type": "skus",
            "id": "nJoqSzPEAq"
          }
        }
      }
    }
  }'

Being part of an order subscription, the allowed item types are skus, bundles, and adjustments only.

On success, the API responds with a 201 Created status code, returning the newly created order subscription item object (since the unit price wasn't specified in the request, it is inherited from the item):

{
  "data": {
    "id": "LZzggoFWzp",
    "type": "order_subscription_items",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/order_subscription_items/LZzggoFWzp"
    },
    "attributes": {
      "quantity": 1,
      "unit_amount_cents": 890,
      "unit_amount_float": 8.9,
      "formatted_unit_amount": "$8.90",
      "total_amount_cents": 890,
      "total_amount_float": 8.9,
      "formatted_total_amount": "$8.90",
      "created_at": "2023-03-28T11:10:37.991Z",
      "updated_at": "2023-03-28T11:10:37.991Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "order_subscription": {
      "links": {
        "self": "https://yourdomain.commercelayer.io/api/order_subscription_items/LZzggoFWzp/relationships/order_subscription",
        "related": "https://yourdomain.commercelayer.io/api/order_subscription_items/LZzggoFWzp/order_subscription"
      }
      },
      "item": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/order_subscription_items/LZzggoFWzp/relationships/item",
          "related": "https://yourdomain.commercelayer.io/api/order_subscription_items/LZzggoFWzp/item"
        }
      }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}

Removing a product from a subscription

To manually remove a product from an already generated subscription you just need to delete the related order subscription item. To do that, send a DELETE request /api/subscription_items/:id endpoint:

The following request deletes the order subscription item identified by the "ydzZAyFpNb" ID:

curl -g -X DELETE \
  'https://yourdomain.commercelayer.io/api/order_subscription_items/ydzZAyFpNb' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'

On success, the API responds with a 204 No Content status code. The corresponding product is removed from the associated order subscription.

More to read

Expired subscription, if still in the active status, can be resumed by moving the expiration date to a future time. In this case, the next run date could be automatically recomputed to avoid date inconsistencies (with the same logic as in the case of a ).

To avoid any possible issue or date inconsistency (especially in the case of high-frequency subscriptions) we suggest the order subscription before making any changes to the associated order subscription items and it right after.

If you simply update the SKU code without nullifying the unit amount you're just changing the product in the subscription, keeping the price of the old one. Setting the unit_amount_cents to null guarantees that the price is recomputed using the price associated with that product in that market (price tiers, if any, are honored as well). The other option is to at the moment of the update.

To delete an order subscription item you need an token of type admin (or a custom role with the necessary permissions).

See our API reference if you need more information on how to or or and .

subscription reactivation
deactivating
reactivating
manually set the desired price
generated
source order
subscription model configuration
order subscription
order subscription items
integration
create
update
delete an order subscription item
update an order subscription
subscription model