Introducing our brand new Rules Engine —
Read the docs
Changelog

Updating the subscriptions

How to customize the next subscription occurrences

Problem

You have generated one or more subscriptions from a source order, based on the subscription model configuration. 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 subscription model 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 order subscription itself or the related order subscription items. 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
      }
    }
  }'

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
      }
    }
  }'

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
      }
    }
  }'

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"
      }
    }
  }'

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"
      }
    }
  }'

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 subscription reactivation).

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"
      }
    }
  }'

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"
        }
      }
    }
    }
  }'

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

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

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
      }
    }
  }'

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
      }
    }
  }'

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
      }
    }
  }'

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 manually set the desired price at the moment of the update.

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.

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'

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

More to read

See our API reference if you need more information on how to create or update or delete an order subscription item and update an order subscription.

PreviousGenerating the subscriptionsNextPayments

Last updated