# Create subscription

The /api/customers/createsubscription/ endpoint creates a new subscription for a customer.

For situations where a customer is actually putting in an order, you can also use the place order API 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 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, e.g. [{ "campaign_id": "3months" }]. Usually you'll just specify one period. 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-11-09T01:35:09. 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 boolean 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. 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, e.g. {"external_id": "no_pause"}.

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

Log in, or send your API key as a bearer token, to see the custom subscription fields set up for your account.

# Examples

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

POST /api/customers/createsubscription/ HTTP/1.1
Content-Type: application/json{
  "id": "12345",
  "periods": [ {
    "campaign_id": "3months"
  } ],
  "data": {
    ":Custom subscription field": "Eksempeltekst"
  }
}

The endpoint returns the ID of the new subscription:

{ "subscription_id": "1300372" }

# Importing

When migrating subscriptions 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-10-09T01:35:09.
  • end string
    Override the time to end the period, e.g. 2027-10-09T01:35:09, 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 for details.
  • renewed boolean Defaults to false
    Can only be used on the first period given. Set to true to register the period as one that was renewed. Iteras uses renewal status of periods for analysis and you can also use it to time invoices. Otherwise the period is for a new subscription. Relevant when importing subscriptions that have already run for some time in another system.
• cancelled boolean 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-07-09T01:35:09, 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-08-09T01:35:09.
• invoiced_by string Defaults to email

  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. Besides email, you can choose one of the fallback methods:

  manual (always available)

  pingen (requires a Pingen agreement)

  netsdk (requires Betalingsservice Total agreement)

  maventa-letter (requires Maventa 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, 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:

{
  ":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:

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