Tags
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.
- Call
GET /tag-typeswith thetargetof the entity to get the types that your API key can create. - For a type with the value shape
OPTION, use one of theoptionsof 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.