# Assign product

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

The API key must allow "Change subscriber data".

Assigns a product to a customer or one of their subscriptions, e.g. a gift or a book. A product sold on its own is invoiced right away.

If you have a subscription with products, you can assign a product to one of the periods of the subscription by filling in `subscription_id` and `period`. The assigned product must belong to the same category as what the subscription subscribes to.

You can also assign an individual product directly to a customer, e.g. if signing up a customer to an event. Here you should not fill `subscription_id`.

## Parameters

- `id` (string, required): ID of the customer.
- `subscription_id` (string): ID of the subscription to assign the product to, if any.
- `period` (string): The period to assign the product to, `current` for the running one or the index of the period with the oldest first, e.g. `1` for the first period. Required when `subscription_id` is given.
- `name` (string): The name of the product to assign. Either `name` or `external_id` must be given.
- `external_id` (string): The external ID of the product to assign. Either `name` or `external_id` must be given.
- `data` (object): Any attributes to attach to the product assignment, by field ID. The valid attributes are the fields that are associated with the product assignment.
- `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 product assignment field, using its field id (the field name with a colon prepended, or its external identifier).

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

Assign an individual product to a period, using `external_id` as key:

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

```json
{
  "id": "12345",
  "subscription_id": "32142532",
  "period": "current",
  "external_id": "example_product"
}
```

Assign an event product directly to a customer:

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

```json
{
  "id": "12345",
  "external_id": "example_product",
  "data": {
    ":Custom product assignment field": "Example text",
    ":Custom date field": "2026-10-23"
  }
}
```

## Return value

On success the endpoint returns the ID of the new product assignment:

```json
{ "product_assignment_id": "9989892798" }
```

## Errors

Invalid requests due to programming error, e.g. invalid JSON, returns 400. This also covers giving neither `name` nor `external_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 product assignment field:

```json
{
  ":Custom product assignment 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 product, subscription or period, a product that doesn't match the category the subscription subscribes to, and a recurring product:

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