Developer documentation

Switch subscription plan

POST https://app.iteras.dk/api/customers/switchsubscriptionplan/

The API key must allow "Change subscriber data".

Switches a subscription to another campaign of the same business entity, immediately: the ongoing period is stopped and a successor is created with the new campaign, credited and re-invoiced as needed.

Parameters

  • id string required

    ID of the customer the subscription belongs to.

  • subscription_id string required

    ID of the subscription to switch plan for.

  • new_campaign_id string required

    ID of the campaign to switch to.

  • renewed bool

    Set to false to treat the newly created period as if it was the first period of the subscription. Very rarely useful.

    For example, inside Iteras you can set up the invoice timing machinery to advance or delay invoicing of the first period.

  • 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.

Examples

POST /api/customers/switchsubscriptionplan/ HTTP/1.1
Content-Type: application/json{
  "id": "12345",
  "subscription_id": "32142532",
  "new_campaign_id": "3months"
}

Return value

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

{ "subscription_id": "32142532" }

Errors

Invalid requests due to programming error, e.g. invalid JSON, returns 400.

A well-formed operation where a supplied value is invalid is not executed and returns an HTTP 422 error. Errors that are not specific to a field are returned with the empty string as key, e.g. an unknown subscription, an unknown campaign, a subscription that is not active, or a campaign that cannot be used for the subscription:

{
  "": ["The subscription is not active."]
}