# Configuring a subscription model

## 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

{% tabs %}
{% tab title="Request" %}
The following request creates a new subscription model that allows five subscription frequencies:

<pre class="language-sh"><code class="lang-sh">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",
<strong>      "frequencies": [
</strong><strong>        "hourly",
</strong><strong>        "30 10 * * *",
</strong><strong>        "weekly",
</strong><strong>        "monthly",
</strong><strong>        "two-month"
</strong><strong>      ]
</strong>    }
  }
}'
</code></pre>

{% hint style="info" %}
To create a new subscription model you need an [integration](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/api-credentials#integration) token of type **admin** (or a custom role with the necessary permissions).
{% endhint %}
{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `201 Created` status code, returning the newly created subscription model object (since the subscription strategy wasn't specified in the request, the default one — `by_frequency` — is used):

<pre class="language-json"><code class="lang-json">{
  "data": {
    "id": "AavWRUbbMQ",
    "type": "subscription_models",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ"
    },
    "attributes": {
      "name": "US Subscription Model",
<strong>      "strategy": "by_frequency",
</strong>      "frequencies": [
        "hourly",
        "30 10 * * *",
        "weekly",
        "monthly",
        "two-month"
      ],
      "auto_activate": true,
      "auto_cancel": false,
      "created_at": "2023-03-21T16:25:18.162Z",
      "updated_at": "2023-03-21T16:25:18.162Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "markets": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/relationships/markets",
          "related": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/markets"
        }
      },
      "order_subscriptions": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/relationships/order_subscriptions",
          "related": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/order_subscriptions"
        }
      },
      "attachments": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/relationships/attachments",
          "related": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/attachments"
        }
      }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}
</code></pre>

{% endtab %}
{% endtabs %}

#### 2. Associate the new subscription model with an existing market

{% tabs %}
{% tab title="Request" %}
The following request associates the subscription model identified by the "AavWRUbbMQ" ID with the market identified by the "bgOEQhznoZ" ID:

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

{% hint style="info" %}
To update a market you need an [integration](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/api-credentials#integration) token of type **admin** (or a custom role with the necessary permissions).
{% endhint %}
{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the updated market object:

<pre class="language-json"><code class="lang-json">{
  "data": {
    "id": "bgOEQhznoZ",
    "type": "markets",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ"
    },
    "attributes": {
      "number": 795,
      "name": "USA",
      "facebook_pixel_id": null,
      "checkout_url": "https://your-checkout-url/:order_id",
      "external_prices_url": null,
      "external_order_validation_url": null,
      "shared_secret": "y0ur_sh4r3dS3c_r3T",
      "private": false,
      "disabled_at": null,
      "created_at": "2019-05-14T10:36:53.010Z",
      "updated_at": "2023-03-21T16:54:43.188Z",
      "reference": "",
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "merchant": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/relationships/merchant",
          "related": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/merchant"
        }
      },
      "price_list": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/relationships/price_list",
          "related": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/price_list"
        }
      },
      "inventory_model": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/relationships/inventory_model",
          "related": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/inventory_model"
        }
      },
<strong>      "subscription_model": {
</strong><strong>        "links": {
</strong><strong>          "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/relationships/subscription_model",
</strong><strong>          "related": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/subscription_model"
</strong><strong>        }
</strong>      },
      "tax_calculator": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/relationships/tax_calculator",
          "related": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/tax_calculator"
        }
      },
      "customer_group": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/relationships/customer_group",
          "related": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/customer_group"
        }
      },
      "attachments": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/relationships/attachments",
          "related": "https://yourdomain.commercelayer.io/api/markets/bgOEQhznoZ/attachments"
        }
      }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}
</code></pre>

{% endtab %}
{% endtabs %}

## Additional notes

### Updating the subscription model

You may want to add some new frequencies to an existing subscription model or remove some of the allowed ones, change the subscription strategy or the default behavior in terms of [automatic subscription activation and cancellation](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/subscription_models#automatic-subscription-activation-and-cancellation), and more. To do that, you just need to send a `PATCH` request to the `/api/subscription_models/:id` endpoint, properly setting the related attributes.&#x20;

{% hint style="warning" %}
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](https://docs.commercelayer.io/how-tos/placing-orders/subscriptions/generating-the-subscriptions) only. If you try to [update](https://docs.commercelayer.io/how-tos/placing-orders/subscriptions/updating-the-subscriptions) 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.
{% endhint %}

#### Example

{% tabs %}
{% tab title="Request" %}
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:

<pre class="language-sh"><code class="lang-sh">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": {
<strong>        "strategy": "by_line_items",
</strong>        "frequencies": [
          "hourly",
          "30 10 * * *",
          "weekly",
          "monthly",
          "two-month",
<strong>          "six-month"
</strong>        ],
<strong>        "auto_activate": false,
</strong><strong>        "auto_cancel": true
</strong>      }
    }
  }'
</code></pre>

{% hint style="info" %}
To update a subscription model you need an [integration](https://app.gitbook.com/s/-LgByaSP8eKjad-MIuHE/api-credentials#integration) token of type **admin** (or a custom role with the necessary permissions).
{% endhint %}
{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the updated subscription model object:

<pre class="language-json"><code class="lang-json">{
  "data": {
    "id": "AavWRUbbMQ",
    "type": "subscription_models",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ"
    },
    "attributes": {
      "name": "US Subscription Model",
<strong>      "strategy": "by_line_items",
</strong>      "frequencies": [
        "hourly",
        "30 10 * * *",
        "weekly",
        "monthly",
        "two-month",
<strong>        "six-month"
</strong>      ],
<strong>      "auto_activate": false,
</strong><strong>      "auto_cancel": true,
</strong>      "created_at": "2023-03-21T16:25:18.162Z",
      "updated_at": "2023-03-21T18:18:42.386Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "markets": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/relationships/markets",
          "related": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/markets"
        }
      },
      "order_subscriptions": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/relationships/order_subscriptions",
          "related": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/order_subscriptions"
        }
      },
      "attachments": {
        "links": {
          "self": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/relationships/attachments",
          "related": "https://yourdomain.commercelayer.io/api/subscription_models/AavWRUbbMQ/attachments"
        }
      }
    },
    "meta": {
      "mode": "test",
      "organization_id": "EnAvaFOrRe"
    }
  }
}
</code></pre>

{% endtab %}
{% endtabs %}

## More to read

See our API reference if you need more information on how to [create](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/subscription_models/create) and [update a subscription model](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/subscription_models/update), or [update a market](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/markets/update).