# Create subscription

POST `https://app.iteras.dk/api/customers/createsubscription/`

The API key must allow "Change subscriber data".

Creates a subscription for a customer on a campaign. It is invoiced and renewed by the campaign and its business policy, so the customer can be sent an invoice.

For situations where a customer is actually putting in an order, you can also use the [place order API](/api/docs/server/placeorder.md) instead to get an order registered in Iteras and let that create the subscription.

## Parameters

These are the base parameters. Below [are some extra parameters](#importing) that can be useful when importing subscriptions from another system.

- `id` (string, required): ID of the customer to create the subscription for.
- `periods` (array, required): The periods to create, usually just one, each an object with the `campaign_id` of the campaign and optionally `begin` and `invoicing`.

  For example `[{ "campaign_id": "3months" }]`. Each period to create is an object with the following parameters:

  - `campaign_id` (string, required): ID of the campaign, e.g. `1300` or `3months`.
  - `begin` (string, Defaults to `current time`): Override the time to begin the period, e.g. `2026-12-22T13:56:57`. You can use a time in the future to have the subscription stand by in an awaiting state. The default is the current time.
  - `invoicing` (string): Set to `none` if the period should not be invoiced. The default is invoicing the period with the amount specified in the campaign.
- `group_subscription_id` (string): ID of the group subscription controlling this recipient subscription, e.g. `1300312`.
- `addon_base_subscription_id` (string): ID of the base subscription controlling this add-on subscription, e.g. `1300313`.
- `create_mandatory_addon_subscriptions` (bool, Defaults to `true`): If this is a subscription on a campaign with mandatory add-on subscriptions, Iteras creates these additional subscriptions automatically. Set to `false` to prevent that.
- `quantity` (integer, Defaults to `1`): The quantity of the subscription, e.g. `15`.
- `data` (object): Any fields to set on the subscription, by field ID. The valid fields are the subscription fields associated with the products that the subscription is subscribed to.
- `policy` (object): An object containing an `id` or `external_id` of the business policy to attach to the subscription.

  For example `{"external_id": "no_pause"}`.
- `exclude_from_webhooks` (bool, Defaults to `false`): Set to `true` to keep every event the request causes from being sent to webhooks, invoice and payment events included, e.g. `"exclude_from_webhooks": true`. The events are still added to the history.

You can set any custom subscription field, using its field id (the field name with a colon prepended, or its external identifier).

[Log in](/login/?next=/api/docs/server/createsubscription.md), or send your API key as a bearer token, to see the custom subscription fields set up for your account.

A yes/no field (type `bool`) is `true` or `false`, and has no value when it isn't set. Set it with `true` or `false`, and clear it with `null`.

## Examples

Create a subscription with a single period on the given campaign:

```http
POST /api/customers/createsubscription/ HTTP/1.1
Content-Type: application/json
```

```json
{
  "id": "12345",
  "periods": [ {
    "campaign_id": "3months"
  } ],
  "data": {
    ":Custom subscription field": "Example text"
  }
}
```

## Return value

On success the endpoint returns the ID of the new subscription:

```json
{ "subscription_id": "1300372" }
```

## Importing

When [migrating subscriptions](/api/docs/guides/migrations.md) from another system, it can be necessary to setup the subscription differently or to adjust periods. There are some extra parameters that are mostly only useful for imports.

- `periods` (array): `periods` have some extra parameters that are useful when importing:
  - `begin` (string, Defaults to `current time`): Override the time to period began with a time in the past, e.g. `2025-11-22T13:56:57`.
  - `end` (string): Override the time to end the period, e.g. `2027-11-22T13:56:57`, instead of using the duration specified in the campaign.
  - `remaining_assignments` (integer): Override the remaining assignments in the period, e.g. `3`, instead of using the full amount specified in the campaign.
  - `invoicing` (string): Set to `none` to not invoice the period, or set to `adjusted_begin` or `adjusted_end` if you adjusted the duration by moving the beginning or the end of the period and want the invoicing decrease/increase to reflect that. The default is invoicing the period with the amount specified in the campaign.
  - `external_invoicing` (object): Invoicing from the previous system for this period, e.g. `{"invoiced": 10000, "currency": "DKK", "tax_rate": 0.25}`. See the [migration guide](/api/docs/guides/migrations.md) for details.
  - `renewed` (bool, Defaults to `false`): Can only be set on the first period. Set to `true` to register the first period as one that was renewed. Iteras uses renewal status of periods for analysis and you can also use it to time invoices. Later periods are always registered as renewed. Relevant when importing subscriptions that have already run for some time in another system.
- `cancelled` (bool, Defaults to `false`): Set to `true` if the subscription has been cancelled and should not be renewed.
- `stop_requested` (string): The time the cancellation was requested, e.g. 2026-08-22T13:56:57, for subscriptions imported from another system. Only used together with `cancelled`. The default is the current time.
- `created` (string, Defaults to `current time`): Override the time the subscription was created, e.g. `2026-09-22T13:56:57`.
- `invoiced_by` (string): The fallback invoicing method preferred by the subscription. Usually it only makes sense to set this in case the customer used to get invoices through a certain channel and you wish to keep that if possible. If you leave it out, Iteras uses the preferred invoicing method of the business policy. Besides `email`, you can choose one of the fallback methods:
  - `manual` (always available)
  - `pingen` (requires a Pingen agreement)
  - `netsdk` (requires Betalingsservice Total agreement)
  - `inexchange-letter` (requires Inexchange agreement)

## Errors

Invalid requests due to programming error, e.g. invalid JSON, returns 400. This also covers a missing or empty `periods` array, a period without a `campaign_id`, setting `renewed` on a period after the first, and specifying both `group_subscription_id` and `addon_base_subscription_id`.

A well-formed operation where a supplied value is invalid is not executed and returns an HTTP 422 error. The response is a JSON object with the errors keyed by the field they concern, e.g. a custom subscription field:

```json
{
  ":Custom subscription field": ["Enter a valid value."]
}
```

Errors that are not specific to a field are returned with the empty string as key. This covers an unknown campaign, group subscription or add-on base subscription, and period validation, e.g. a period that starts after it ends or overlaps another period:

```json
{
  "": ["Campaign does not exist."]
}
```