Configuring a subscription model

How to create a subscription model to set the available subscription frequencies and the subscription strategy for a market

Problem

It's time to start providing subscription features in one of your Commerce Layer markets. You want to define the available subscription frequencies for the market in question and set the subscription strategy based on which the necessary order subscriptions will be automatically generated.

Solution

You need to create and configure a subscription model and associate it with your market. To do that:

  1. Send a POST request to the /api/subscription_models endpoint, setting the frequencies and strategy attributes.

  2. Send a PATCH request to the /api/markets/:id endpoint, setting the subscription_model relationship.

Example

1. Create a new subscription model

The following request creates a new subscription model that allows five subscription frequencies:

curl -g -X POST \
  'https://yourdomain.commercelayer.io/api/subscription_models' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "subscription_models",
    "attributes": {
      "name": "US Subscription Model",
      "frequencies": [
        "hourly",
        "30 10 * * *",
        "weekly",
        "monthly",
        "two-month"
      ]
    }
  }
}'

To create a new subscription model you need an integration token of type admin (or a custom role with the necessary permissions).

2. Associate the new subscription model with an existing market

The following request associates the subscription model identified by the "AavWRUbbMQ" ID with the market identified by the "bgOEQhznoZ" ID:

curl -g -X PATCH \
 'https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "markets",
      "id": "bgOEQhznoZ",
      "relationships": {
        "subscription_model": {
          "data": {
            "type": "subscription_models",
            "id": "AavWRUbbMQ"
          }
        }
      }
    }
  }'

To update a market you need an integration token of type admin (or a custom role with the necessary permissions).

Additional notes

Updating the subscription model

Please note that any changes to an existing subscription model don't affect already generated subscriptions. The changes will apply starting from the next subscription generation only. If you try to update some of the already generated subscriptions in a way that's not consistent with the new changes to the subscription model you will receive a validation error.

Example

The following request updates the subscription model identified by the ID "AavWRUbbMQ", adding an additional allowed frequency and changing both the default subscription strategy and auto-activate / auto-cancel behavior:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "subscription_models",
      "id": "AavWRUbbMQ",
      "attributes": {
        "strategy": "by_line_items",
        "frequencies": [
          "hourly",
          "30 10 * * *",
          "weekly",
          "monthly",
          "two-month",
          "six-month"
        ],
        "auto_activate": false,
        "auto_cancel": true
      }
    }
  }'

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

More to read

Last updated