---
title: Tags
description: Attach sales, rebate, charge, billing and support data to a subscription, a customer or a license
---

A tag attaches a typed value to a subscription, a customer or a license for a period. Invoicing,
reports and the support team read the tags. For example, a `MANUAL_CHARGE` tag adds a charge to
each invoice while the tag is valid, and a `CHURN` tag records why the customer left.

## The entity of a tag

A tag attaches to exactly one entity. Give exactly one of `subscriptionId`, `customerId` and
`licenseId` when you create or list tags. Not every type attaches to every kind of entity. For
example, `INVOICE_VAT` attaches only to a customer, and `CHURN` does not attach to a customer.

## The type decides the value

Each tag has a `type`. The type decides the shape of the value:

| Value shape            | Field                                   | Example types                           |
| ---------------------- | --------------------------------------- | --------------------------------------- |
| Text                   | `value`, a string                       | `DISCOUNT`, `DIRECT_SALE`, `CUSTOM`     |
| Number                 | `value`, a number                       | `REBATE_PERCENTAGE`, `INVOICE_VAT`      |
| Option                 | `value`, one of the options of the type | `CHURN`, `CALL_SERVICE`, `PROVISIONING` |
| Flag                   | no value                                | `INVOICE_IGNORE_CUSTOMER`               |
| Reference              | `value`, the identifier of an entity    | `PRICE_LIST`, `PRODUCT_CATALOG`         |
| Manual charge          | `manualCharge`                          | `MANUAL_CHARGE`                         |
| One-time manual charge | `manualCharge` and `chargeDate`         | `MANUAL_CHARGE_ONCE`                    |

We add new tag types without notice. Your client must accept a type that it does not know. A
tag that the API cannot show in its typed form has the type `CUSTOM`, with the full tag text
as the `value`.

## Which types your API key can use

The roles of the API key decide which tag types it can create, end and delete. An
environment can also turn off a type for all callers.

1. Call `GET /tag-types` with the `target` of the entity to get the types that your API key can create.
2. For a type with the value shape `OPTION`, use one of the `options` of that type.

The API answers these refusals with a reason:

| Status | Reason                   | Condition                                        |
| ------ | ------------------------ | ------------------------------------------------ |
| `403`  | `tag_type_not_permitted` | The roles of the API key cannot manage the type. |
| `422`  | `tag_type_disabled`      | The environment turned off the type.             |
| `422`  | `tag_type_not_on_target` | The type does not attach to this kind of entity. |
| `400`  | `tag_target_ambiguous`   | The request names no entity, or more than one.   |

## End or delete

- To stop a tag, end it with `POST /tags/{tagId}/end`. The tag stays in the history of its
  entity. An end can only move the last valid date earlier.
- To remove a tag that is not correct, delete it with `DELETE /tags/{tagId}`. An invoice that
  already includes a charge of the tag does not change.