# Create override

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

The API key must allow "Change subscriber data".

Creates an override on a customer or one of their subscriptions: a pause of the subscription or its deliveries for a period, delivery to another address for a period, or a change of the delivery address, billing address or fields at a future date.

See [the available override types](/api/docs/server/overridetypes.md) for what each of them does. If you need to change or delete an override, use the [update customer override](/api/docs/server/updateoverride.md) or [delete customer override](/api/docs/server/deleteoverride.md) endpoint. Some fields are locked once an override is active, and only overrides that have not taken effect yet can be deleted.

## Parameters

- `id` (string, required): ID of the customer.
- `subscription_id` (string): ID of the subscription. Required if the override concerns a subscription.
- `override_type` (string, required): The type of override.

  See the [available override types](/api/docs/server/overridetypes.md).
- `begin` (string): When the override takes effect, as `YYYY-MM-DDTHH:MM:SS`. The default is now.
- `end` (string): When the override ends, as `YYYY-MM-DDTHH:MM:SS`: the first moment it no longer applies, so a pause through 20 November ends at `2026-11-21T00:00:00`. Required for `alternative-delivery`, `pause-delivery`, `pause-delivery-donate` and `pause-subscription`, and not valid for the future change overrides.
- `address` (object): The new address, for the overrides that change the delivery or billing address or send to another address, e.g. `{"name": "John Doe", "address": "Main Street 12\n8000 Aarhus", "country": "DK"}`, where `address` is the address lines with postcode and city, without the country. `address`, `country` and `name` are required, or `company` instead of `name` for the address types that allow a company.

  The country must be the customer's own where the subscription's policy does not allow sending to another country.
- `new_values` (object): The fields to change and their new values, for a `change-fields` override, built-in fields by name and custom fields by their field ID, e.g. `{"name": "New Name", ":Membership level": "Gold"}`.

  The field ID is the field name with a colon prepended or, if defined, the external identifier of the field. See the custom fields set up for your account below.
- `pause_reason` (string): A reason for pausing, for a `pause-subscription` override, e.g. `"Vacation"`.
- `weekdays` (array): The weekdays the override applies to, for an address override, as numbers with 1 being Monday and 7 being Sunday, e.g. `[1, 3, 5]`. Only relevant for weekdays-based distribution.
- `skip_processing` (bool): Set to `true` to register the override without processing it, for importing older overrides. The effective date and overlapping checks are skipped in this mode.
- `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.

A `change-fields` override can change a built-in customer or subscription field, or a custom field.

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

[Log in](/login/?next=/api/docs/server/createoverride.md), or send your API key as a bearer token, to see the custom customer 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`.

A date and time field (type `datetime`) can be set up to follow other fields, so it is set to the time one of them changes. If the same update changes the date and time field itself, that value is kept.

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/createoverride.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

While the temporary subscription overrides can be used for several things, a common need is vacations.

### Vacation with pause

Pause the whole subscription for a period, e.g. because of a vacation. You can give a reason with `pause_reason`:

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

```json
{
  "id": "12345",
  "subscription_id": "34567",
  "override_type": "pause-subscription",
  "begin": "2026-11-23T13:56:58",
  "end": "2026-12-07T13:56:58",
  "pause_reason": "Vacation"
}
```

### Vacation with paused deliveries

Pause deliveries for a period, e.g. a vacation where there's still access to an online part, but no physical product:

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

```json
{
  "id": "12345",
  "subscription_id": "34567",
  "override_type": "pause-delivery",
  "begin": "2026-12-22T13:56:58",
  "end": "2026-12-29T13:56:58"
}
```

### Vacation with delivery to vacation destination

Send the subscription to another address for a period, e.g. a vacation destination. Optionally restrict it to certain weekdays:

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

```json
{
  "id": "12345",
  "subscription_id": "34567",
  "override_type": "alternative-delivery",
  "begin": "2026-11-24T13:56:58",
  "end": "2026-12-07T13:56:58",
  "address": {
    "name": "John Doe",
    "address": "Holiday Road 1\n8000 Aarhus",
    "country": "DK"
  },
  "weekdays": [1, 3, 5]
}
```

### Future changes

Change the delivery address at a future date:

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

```json
{
  "id": "12345",
  "override_type": "change-delivery-address",
  "begin": "2026-12-22T13:56:58",
  "address": {
    "name": "John Doe",
    "address": "Main Street 12\n8000 Aarhus",
    "country": "DK"
  }
}
```

Change field values at a future date:

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

```json
{
  "id": "12345",
  "override_type": "change-fields",
  "begin": "2026-12-06T13:56:58",
  "new_values": {
    "name": "New Name",
    ":Custom field": "Example text"
  }
}
```

## Return value

The endpoint returns the ID of the new override:

```json
{ "override_id": "77642" }
```

## Errors

Invalid requests due to programming error, e.g. invalid JSON, returns 400. This also covers giving neither `id` nor `subscription_id`, a missing `subscription_id` for a subscription-only override, an unknown `override_type`, a field with the wrong type, a field that does not belong to the override type, e.g. `new_values` for an address override or `end` for a future change override, and a missing required field, e.g. `new_values` for a `change-fields` override, `end` for a vacation override or `address` for an address override.

A well-formed operation where a supplied value is invalid is not executed and returns an HTTP 422 error. This covers an `end` that isn't later than `begin`, an invalid `new_values` or `address`, an override type the subscription's policy does not allow, an override that takes effect before the earliest possible delivery date or on a date blocked for delivery changes, and an override that overlaps an existing one. Errors that are not specific to a field are returned with the empty string as key, e.g. an unknown subscription:

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

A subscription that belongs to a different customer is reported under `subscription_id`:

```json
{
  "subscription_id": ["The subscription does not belong to the customer."]
}
```