--- title: Tags description: Manage the tags of subscriptions, customers and licenses. --- # Tags Manage the tags of subscriptions, customers and licenses. ## [GET /tag-types](/api-reference/tags#tag/tags/GET/tag-types) List the tag types Get the tag types that the API key can create on a kind of entity, with the shape of the value of each type. The roles of the API key decide which types it can create. A type with the value shape `OPTION` also gives its options. For example, the options of `CHURN` are the cancel reasons of the brand. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Query parameters - `target` (`enum`, required, one of SUBSCRIPTION, CUSTOMER, LICENSE) — The kind of entity that the tags attach to. — The kind of entity that a tag attaches to. ### Responses #### 200 The tag types that the API key can create on the kind of entity. Type: `object` - `items` (`array of CreatableTagType`, required) - `type` (`enum`, required, one of DIRECT_SALE, PARTNER_SALE, PARTNER_LEAD, MARKETING_SALE, SUPPORT_SALE, ONLINE_SALE, COMPANY_OWNER, INVITE_SALE, REFERRAL_SALE, SALES, ABROAD, DISCOUNT, ENABLE_FEATURE, CUSTOM, REBATE_FIXED, REBATE_PERCENTAGE, REBATE_CREDIT_FIXED, REBATE_CREDIT_PERCENTAGE, CUSTOMER_BOUND_COST_PER_MONTH, INVOICE_DAY_OF_MONTH, INVOICE_DUE_IN_DAYS, INVOICE_VAT, CLOUD_COM_BAS, CALL_SERVICE, CHURN, SUPPORT, PROVISIONING, CHARITY, INVOICE_PERIOD_TYPE, REMOVE_FEE, BILLING_IGNORE_CUSTOMER, INVOICE_IGNORE_CUSTOMER, INVOICE_PROTECTED_IDENTITY, PRICE_LIST, PRODUCT_CATALOG, MANUAL_CHARGE, MANUAL_CHARGE_ONCE) — The type of a tag. We add new types without notice. Your client must accept a type that it does not know. - `valueShape` (`enum`, required, one of TEXT, NUMBER, OPTION, FLAG, REFERENCE, MANUAL_CHARGE, ONE_TIME_MANUAL_CHARGE) — The shape of the value of a tag type. - `options` (`array of string`, required) — The permitted values of a type with the value shape `OPTION`. It is empty for the other shapes. #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl 'https://apiv2.example.com/api/v2/tag-types?target=SUBSCRIPTION' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [GET /tags](/api-reference/tags#tag/tags/GET/tags) List tags Get the tags of a subscription, a customer or a license: the tags that are valid now, the tags that ended, and the tags that start later. A deleted tag is not in the list. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Query parameters - `subscriptionId` (`string`, optional) — Get the tags of this subscription. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `customerId` (`string`, optional) — Get the tags of this customer. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `licenseId` (`string`, optional) — Get the tags of this license. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `type` (`array of TagTypeName`, optional) — Get only the tags of these types. ### Responses #### 200 The tags of the entity. Type: `object` - `items` (`array of Tag`, required) - One of: `CUSTOM` - `tagId` (`string`, required, example 3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f) — The unique identifier of the tag. - `createdAt` (`string`, required, date-time, example 2026-10-29T08:30:00Z) — The time when the tag was created. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier of the subscription that the tag attaches to. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier of the customer that the tag attaches to. - `licenseId` (`string`, optional, example b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e) — The unique identifier of the license that the tag attaches to. - `type` (`enum`, required, one of DIRECT_SALE, PARTNER_SALE, PARTNER_LEAD, MARKETING_SALE, SUPPORT_SALE, ONLINE_SALE, COMPANY_OWNER, INVITE_SALE, REFERRAL_SALE, SALES, ABROAD, DISCOUNT, ENABLE_FEATURE, CUSTOM) — The type of the tag. The type decides the shape of the value. - `value` (`string`, required, personal data, example seller@example.com) — The value of the tag. - `validFrom` (`string`, optional, date, example 2026-11-01) — The first date that the tag is valid. If it is absent, the tag is valid from the start. - `validTo` (`string`, optional, date, example 2027-10-31) — The last date that the tag is valid. If it is absent, the tag has no end. - One of: `CLOUD_COM_BAS` - `tagId` (`string`, required, example 3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f) — The unique identifier of the tag. - `createdAt` (`string`, required, date-time, example 2026-10-29T08:30:00Z) — The time when the tag was created. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier of the subscription that the tag attaches to. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier of the customer that the tag attaches to. - `licenseId` (`string`, optional, example b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e) — The unique identifier of the license that the tag attaches to. - `type` (`enum`, required, one of REBATE_FIXED, REBATE_PERCENTAGE, REBATE_CREDIT_FIXED, REBATE_CREDIT_PERCENTAGE, CUSTOMER_BOUND_COST_PER_MONTH, INVOICE_DAY_OF_MONTH, INVOICE_DUE_IN_DAYS, INVOICE_VAT, CLOUD_COM_BAS) — The type of the tag. The type decides the shape of the value. - `value` (`number`, required, example 10) — The value of the tag. A percentage type holds a percentage, and an amount type holds an amount in major units of the currency. - `validFrom` (`string`, optional, date, example 2026-11-01) — The first date that the tag is valid. If it is absent, the tag is valid from the start. - `validTo` (`string`, optional, date, example 2027-10-31) — The last date that the tag is valid. If it is absent, the tag has no end. - One of: `REMOVE_FEE` - `tagId` (`string`, required, example 3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f) — The unique identifier of the tag. - `createdAt` (`string`, required, date-time, example 2026-10-29T08:30:00Z) — The time when the tag was created. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier of the subscription that the tag attaches to. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier of the customer that the tag attaches to. - `licenseId` (`string`, optional, example b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e) — The unique identifier of the license that the tag attaches to. - `type` (`enum`, required, one of CALL_SERVICE, CHURN, SUPPORT, PROVISIONING, CHARITY, INVOICE_PERIOD_TYPE, REMOVE_FEE) — The type of the tag. The type decides the shape of the value. - `value` (`string`, required, example MovedAbroad) — The value of the tag. It is one of the options that `GET /tag-types` gives for the type. - `validFrom` (`string`, optional, date, example 2026-11-01) — The first date that the tag is valid. If it is absent, the tag is valid from the start. - `validTo` (`string`, optional, date, example 2027-10-31) — The last date that the tag is valid. If it is absent, the tag has no end. - One of: `INVOICE_PROTECTED_IDENTITY` - `tagId` (`string`, required, example 3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f) — The unique identifier of the tag. - `createdAt` (`string`, required, date-time, example 2026-10-29T08:30:00Z) — The time when the tag was created. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier of the subscription that the tag attaches to. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier of the customer that the tag attaches to. - `licenseId` (`string`, optional, example b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e) — The unique identifier of the license that the tag attaches to. - `type` (`enum`, required, one of BILLING_IGNORE_CUSTOMER, INVOICE_IGNORE_CUSTOMER, INVOICE_PROTECTED_IDENTITY) — The type of the tag. The type decides the shape of the value. - `validFrom` (`string`, optional, date, example 2026-11-01) — The first date that the tag is valid. If it is absent, the tag is valid from the start. - `validTo` (`string`, optional, date, example 2027-10-31) — The last date that the tag is valid. If it is absent, the tag has no end. - One of: `PRODUCT_CATALOG` - `tagId` (`string`, required, example 3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f) — The unique identifier of the tag. - `createdAt` (`string`, required, date-time, example 2026-10-29T08:30:00Z) — The time when the tag was created. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier of the subscription that the tag attaches to. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier of the customer that the tag attaches to. - `licenseId` (`string`, optional, example b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e) — The unique identifier of the license that the tag attaches to. - `type` (`enum`, required, one of PRICE_LIST, PRODUCT_CATALOG) — The type of the tag. The type decides the shape of the value. - `value` (`string`, required, example 5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9) — The unique identifier of the entity that the tag points to, for example a price list. - `validFrom` (`string`, optional, date, example 2026-11-01) — The first date that the tag is valid. If it is absent, the tag is valid from the start. - `validTo` (`string`, optional, date, example 2027-10-31) — The last date that the tag is valid. If it is absent, the tag has no end. - One of: `MANUAL_CHARGE` - `tagId` (`string`, required, example 3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f) — The unique identifier of the tag. - `createdAt` (`string`, required, date-time, example 2026-10-29T08:30:00Z) — The time when the tag was created. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier of the subscription that the tag attaches to. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier of the customer that the tag attaches to. - `licenseId` (`string`, optional, example b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e) — The unique identifier of the license that the tag attaches to. - `type` (`enum`, required, one of MANUAL_CHARGE) — The type of the tag. The type decides the shape of the value. - `manualCharge` (`object`, required) — A charge that the invoice includes. - `description` (`string`, required, personal data, min length 1, example Installation) — The text of the charge on the invoice. It must not contain a colon. - `amountMinor` (`integer`, required, int64, example 2900) — The amount of the charge, in minor units of the currency (for example 2900 = $29.00 when the currency is USD). - `currency` (`string`, required, example USD) — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `validFrom` (`string`, optional, date, example 2026-11-01) — The first date that the tag is valid. If it is absent, the tag is valid from the start. - `validTo` (`string`, optional, date, example 2027-10-31) — The last date that the tag is valid. If it is absent, the tag has no end. - One of: `MANUAL_CHARGE_ONCE` - `tagId` (`string`, required, example 3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f) — The unique identifier of the tag. - `createdAt` (`string`, required, date-time, example 2026-10-29T08:30:00Z) — The time when the tag was created. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The unique identifier of the subscription that the tag attaches to. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier of the customer that the tag attaches to. - `licenseId` (`string`, optional, example b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e) — The unique identifier of the license that the tag attaches to. - `type` (`enum`, required, one of MANUAL_CHARGE_ONCE) — The type of the tag. The type decides the shape of the value. - `manualCharge` (`object`, required) — A charge that the invoice includes. - `description` (`string`, required, personal data, min length 1, example Installation) — The text of the charge on the invoice. It must not contain a colon. - `amountMinor` (`integer`, required, int64, example 2900) — The amount of the charge, in minor units of the currency (for example 2900 = $29.00 when the currency is USD). - `currency` (`string`, required, example USD) — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `chargeDate` (`string`, required, date, example 2026-11-15) — The date of the charge. The invoice that covers this date includes the charge one time. #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/tags \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [POST /tags](/api-reference/tags#tag/tags/POST/tags) Create a tag Create a tag on a subscription, a customer or a license. The roles of the API key must let it manage the type, and the environment must not turn the type off. `GET /tag-types` gives the types that the API key can create on each kind of entity. The currency of a charge must be the currency of the brand. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `one of` - One of: `CUSTOM` - `type` (`enum`, required, one of DIRECT_SALE, PARTNER_SALE, PARTNER_LEAD, MARKETING_SALE, SUPPORT_SALE, ONLINE_SALE, COMPANY_OWNER, INVITE_SALE, REFERRAL_SALE, SALES, ABROAD, DISCOUNT, ENABLE_FEATURE, CUSTOM) — The type of the tag. The type decides the shape of the value. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `licenseId` (`string`, optional, example b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e) — The license to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `value` (`string`, required, personal data, min length 1, example seller@example.com) — The value of the tag. A `CUSTOM` value must not start with the name of another tag type and a colon. - `validFrom` (`string`, optional, date, example 2026-11-01) — The first date that the tag is valid. If it is absent, the tag is valid from the start. - `validTo` (`string`, optional, date, example 2027-10-31) — The last date that the tag is valid. If it is absent, the tag has no end. - One of: `CLOUD_COM_BAS` - `type` (`enum`, required, one of REBATE_FIXED, REBATE_PERCENTAGE, REBATE_CREDIT_FIXED, REBATE_CREDIT_PERCENTAGE, CUSTOMER_BOUND_COST_PER_MONTH, INVOICE_DAY_OF_MONTH, INVOICE_DUE_IN_DAYS, INVOICE_VAT, CLOUD_COM_BAS) — The type of the tag. The type decides the shape of the value. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `licenseId` (`string`, optional, example b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e) — The license to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `value` (`number`, required, example 10) — The value of the tag. A percentage type holds a percentage, and an amount type holds an amount in major units of the currency. - `validFrom` (`string`, optional, date, example 2026-11-01) — The first date that the tag is valid. If it is absent, the tag is valid from the start. - `validTo` (`string`, optional, date, example 2027-10-31) — The last date that the tag is valid. If it is absent, the tag has no end. - One of: `REMOVE_FEE` - `type` (`enum`, required, one of CALL_SERVICE, CHURN, SUPPORT, PROVISIONING, CHARITY, INVOICE_PERIOD_TYPE, REMOVE_FEE) — The type of the tag. The type decides the shape of the value. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `licenseId` (`string`, optional, example b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e) — The license to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `value` (`string`, required, min length 1, example MovedAbroad) — The value of the tag. It is one of the options that `GET /tag-types` gives for the type. - `validFrom` (`string`, optional, date, example 2026-11-01) — The first date that the tag is valid. If it is absent, the tag is valid from the start. - `validTo` (`string`, optional, date, example 2027-10-31) — The last date that the tag is valid. If it is absent, the tag has no end. - One of: `INVOICE_PROTECTED_IDENTITY` - `type` (`enum`, required, one of BILLING_IGNORE_CUSTOMER, INVOICE_IGNORE_CUSTOMER, INVOICE_PROTECTED_IDENTITY) — The type of the tag. The type decides the shape of the value. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `licenseId` (`string`, optional, example b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e) — The license to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `validFrom` (`string`, optional, date, example 2026-11-01) — The first date that the tag is valid. If it is absent, the tag is valid from the start. - `validTo` (`string`, optional, date, example 2027-10-31) — The last date that the tag is valid. If it is absent, the tag has no end. - One of: `PRODUCT_CATALOG` - `type` (`enum`, required, one of PRICE_LIST, PRODUCT_CATALOG) — The type of the tag. The type decides the shape of the value. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `licenseId` (`string`, optional, example b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e) — The license to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `value` (`string`, required, min length 1, example 5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9) — The unique identifier of the entity that the tag points to, for example a price list. - `validFrom` (`string`, optional, date, example 2026-11-01) — The first date that the tag is valid. If it is absent, the tag is valid from the start. - `validTo` (`string`, optional, date, example 2027-10-31) — The last date that the tag is valid. If it is absent, the tag has no end. - One of: `MANUAL_CHARGE` - `type` (`enum`, required, one of MANUAL_CHARGE) — The type of the tag. The type decides the shape of the value. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `licenseId` (`string`, optional, example b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e) — The license to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `manualCharge` (`object`, required) — A charge that the invoice includes. - `description` (`string`, required, personal data, min length 1, example Installation) — The text of the charge on the invoice. It must not contain a colon. - `amountMinor` (`integer`, required, int64, example 2900) — The amount of the charge, in minor units of the currency (for example 2900 = $29.00 when the currency is USD). - `currency` (`string`, required, example USD) — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `validFrom` (`string`, optional, date, example 2026-11-01) — The first date that the tag is valid. If it is absent, the tag is valid from the start. - `validTo` (`string`, optional, date, example 2027-10-31) — The last date that the tag is valid. If it is absent, the tag has no end. - One of: `MANUAL_CHARGE_ONCE` - `type` (`enum`, required, one of MANUAL_CHARGE_ONCE) — The type of the tag. The type decides the shape of the value. - `subscriptionId` (`string`, optional, example d8174435-6378-4be5-a9f5-8b4aaadae5d4) — The subscription to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `customerId` (`string`, optional, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The customer to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `licenseId` (`string`, optional, example b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e) — The license to attach the tag to. Give exactly one of `subscriptionId`, `customerId` and `licenseId`. - `manualCharge` (`object`, required) — A charge that the invoice includes. - `description` (`string`, required, personal data, min length 1, example Installation) — The text of the charge on the invoice. It must not contain a colon. - `amountMinor` (`integer`, required, int64, example 2900) — The amount of the charge, in minor units of the currency (for example 2900 = $29.00 when the currency is USD). - `currency` (`string`, required, example USD) — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `chargeDate` (`string`, required, date, example 2026-11-15) — The date of the charge. The invoice that covers this date includes the charge one time. ### Responses #### 201 The tag was created. Type: [Tag](/api-reference/models.md#models/Tag) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 422 The request is valid, but the current state of the brand or the resource refuses it. The `reason` names the condition. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/tags \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "type": "MANUAL_CHARGE", "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4", "manualCharge": { "description": "Installation", "amountMinor": 2900, "currency": "USD" }, "validFrom": "2026-11-01" }' ``` ## [GET /tags/{tagId}](/api-reference/tags#tag/tags/GET/tags/{tagId}) Get a tag Get a tag by its identifier. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `tagId` (`string`, required) — The unique identifier of the tag. ### Responses #### 200 The tag. Type: [Tag](/api-reference/models.md#models/Tag) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/tags/3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [DELETE /tags/{tagId}](/api-reference/tags#tag/tags/DELETE/tags/{tagId}) Delete a tag Remove a tag. A deleted tag is not in the history of its entity. An invoice that already includes a charge of the tag does not change. To stop a charge, end the tag with `POST /tags/{tagId}/end`. An ended tag stays in the history. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `tagId` (`string`, required) — The unique identifier of the tag. ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Responses #### 204 The tag was deleted. #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/tags/3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f \ --request DELETE \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [POST /tags/{tagId}/end](/api-reference/tags#tag/tags/POST/tags/{tagId}/end) End a tag Set the last date that the tag is valid. The tag stays in the history of its entity. An end can only move the last date earlier. If the tag already ends before the requested date, the API answers `409` with the reason `tag_end_after_valid_to`. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `tagId` (`string`, required) — The unique identifier of the tag. ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `object` - `validTo` (`string`, required, date, example 2026-12-31) — The last date that the tag is valid. It must not be before the `validFrom` of the tag. If the tag already has a `validTo`, the new date must not be later. ### Responses #### 200 The tag was ended. Type: [Tag](/api-reference/models.md#models/Tag) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/tags/3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f/end \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "validTo": "2026-12-31" }' ```