Tags

Manage the tags of subscriptions, customers and licenses.

List the tag types

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

Query parameters

targetenum<string>required

The kind of entity that the tags attach to.

The kind of entity that a tag attaches to.

values

SUBSCRIPTION
CUSTOMER
LICENSE

Responses

200

The tag types that the API key can create on the kind of entity.

application/json

The tag types that the API key can create on the kind of entity.

object

itemsarray of CreatableTagTyperequired

Show child attributes

typeenum<string>required

The type of a tag. We add new types without notice. Your client must accept a type that it does not know.

values

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

valueShapeenum<string>required

The shape of the value of a tag type.

values

TEXT
NUMBER
OPTION
FLAG
REFERENCE
MANUAL_CHARGE
ONE_TIME_MANUAL_CHARGE

optionsarray of stringrequired

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.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /tag-types

curl 'https://apiv2.example.com/api/v2/tag-types?target=SUBSCRIPTION' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'

fetch('https://apiv2.example.com/api/v2/tag-types?target=SUBSCRIPTION', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.get(
    "https://apiv2.example.com/api/v2/tag-types",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    },
    params={
      "target": "SUBSCRIPTION"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/tag-types?target=SUBSCRIPTION"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "items": [
    {
      "type": "DIRECT_SALE",
      "valueShape": "TEXT",
      "options": [
        "MovedAbroad"
      ]
    }
  ]
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

List tags

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

Query parameters

subscriptionIdstring

Get the tags of this subscription. Give exactly one of subscriptionId, customerId and licenseId.

customerIdstring

Get the tags of this customer. Give exactly one of subscriptionId, customerId and licenseId.

licenseIdstring

Get the tags of this license. Give exactly one of subscriptionId, customerId and licenseId.

typearray of TagTypeName

Get only the tags of these types.

Responses

200

The tags of the entity.

application/json

The tags of the entity.

object

itemsarray of Tagrequired

Show child attributes

Selected by type.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

DIRECT_SALE
PARTNER_SALE
PARTNER_LEAD
MARKETING_SALE
SUPPORT_SALE
ONLINE_SALE
COMPANY_OWNER
INVITE_SALE
REFERRAL_SALE
SALES
ABROAD
DISCOUNT
ENABLE_FEATURE
CUSTOM

valuestringpersonal datarequired

The value of the tag.

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

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

valuenumberrequired

The value of the tag. A percentage type holds a percentage, and an amount type holds an amount in major units of the currency.

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

CALL_SERVICE
CHURN
SUPPORT
PROVISIONING
CHARITY
INVOICE_PERIOD_TYPE
REMOVE_FEE

valuestringrequired

The value of the tag. It is one of the options that GET /tag-types gives for the type.

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

BILLING_IGNORE_CUSTOMER
INVOICE_IGNORE_CUSTOMER
INVOICE_PROTECTED_IDENTITY

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

PRICE_LIST
PRODUCT_CATALOG

valuestringrequired

The unique identifier of the entity that the tag points to, for example a price list.

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

MANUAL_CHARGE

manualChargeobjectrequired

A charge that the invoice includes.

Show child attributes

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

MANUAL_CHARGE_ONCE

manualChargeobjectrequired

A charge that the invoice includes.

Show child attributes

chargeDatestringdaterequired

The date of the charge. The invoice that covers this date includes the charge one time.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /tags

curl https://apiv2.example.com/api/v2/tags \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'

fetch('https://apiv2.example.com/api/v2/tags', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.get("https://apiv2.example.com/api/v2/tags",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/tags"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "items": [
    {
      "tagId": "3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f",
      "createdAt": "2026-10-29T08:30:00Z",
      "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
      "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
      "licenseId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
      "type": "DIRECT_SALE",
      "value": "seller@example.com",
      "validFrom": "2026-11-01",
      "validTo": "2027-10-31"
    }
  ]
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /tags

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"
}'

fetch('https://apiv2.example.com/api/v2/tags', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'MANUAL_CHARGE',
    subscriptionId: 'd8174435-6378-4be5-a9f5-8b4aaadae5d4',
    manualCharge: {
      description: 'Installation',
      amountMinor: 2900,
      currency: 'USD'
    },
    validFrom: '2026-11-01'
  })
})

requests.post("https://apiv2.example.com/api/v2/tags",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "type": "MANUAL_CHARGE",
      "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
      "manualCharge": {
        "description": "Installation",
        "amountMinor": 2900,
        "currency": "USD"
      },
      "validFrom": "2026-11-01"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/tags"

	payload := strings.NewReader(`{
  "type": "MANUAL_CHARGE",
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "manualCharge": {
    "description": "Installation",
    "amountMinor": 2900,
    "currency": "USD"
  },
  "validFrom": "2026-11-01"
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "tagId": "3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f",
  "createdAt": "2026-10-29T08:30:00Z",
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "licenseId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
  "type": "DIRECT_SALE",
  "value": "seller@example.com",
  "validFrom": "2026-11-01",
  "validTo": "2027-10-31"
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "ManualChargeOnce tags are turned off on this environment.",
  "code": "failed_precondition",
  "reason": "tag_type_disabled"
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Get a tag

GET/tags/{tagId}

Get a tag by its identifier.

Path parameters

tagIdstringrequired

The unique identifier of the tag.

Responses

200

The tag.

application/json

The tag.

one ofTag

A tag on a subscription, a customer or a license. The type decides the shape of the value.

We add new tag types without notice. Your client must accept a type that it does not know.

Selected by type.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

DIRECT_SALE
PARTNER_SALE
PARTNER_LEAD
MARKETING_SALE
SUPPORT_SALE
ONLINE_SALE
COMPANY_OWNER
INVITE_SALE
REFERRAL_SALE
SALES
ABROAD
DISCOUNT
ENABLE_FEATURE
CUSTOM

valuestringpersonal datarequired

The value of the tag.

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

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

valuenumberrequired

The value of the tag. A percentage type holds a percentage, and an amount type holds an amount in major units of the currency.

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

CALL_SERVICE
CHURN
SUPPORT
PROVISIONING
CHARITY
INVOICE_PERIOD_TYPE
REMOVE_FEE

valuestringrequired

The value of the tag. It is one of the options that GET /tag-types gives for the type.

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

BILLING_IGNORE_CUSTOMER
INVOICE_IGNORE_CUSTOMER
INVOICE_PROTECTED_IDENTITY

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

PRICE_LIST
PRODUCT_CATALOG

valuestringrequired

The unique identifier of the entity that the tag points to, for example a price list.

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

MANUAL_CHARGE

manualChargeobjectrequired

A charge that the invoice includes.

Show child attributes

descriptionstringpersonal datamin length 1required

The text of the charge on the invoice. It must not contain a colon.

amountMinorintegerint64required

The amount of the charge, in minor units of the currency (for example 2900 = $29.00 when the currency is USD).

currencystringrequired

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

MANUAL_CHARGE_ONCE

manualChargeobjectrequired

A charge that the invoice includes.

Show child attributes

descriptionstringpersonal datamin length 1required

The text of the charge on the invoice. It must not contain a colon.

amountMinorintegerint64required

The amount of the charge, in minor units of the currency (for example 2900 = $29.00 when the currency is USD).

currencystringrequired

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

chargeDatestringdaterequired

The date of the charge. The invoice that covers this date includes the charge one time.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

GET /tags/{tagId}

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'

fetch('https://apiv2.example.com/api/v2/tags/3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.get(
    "https://apiv2.example.com/api/v2/tags/3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/tags/3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f"

	req, _ := http.NewRequest("GET", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "tagId": "3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f",
  "createdAt": "2026-10-29T08:30:00Z",
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "licenseId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
  "type": "DIRECT_SALE",
  "value": "seller@example.com",
  "validFrom": "2026-11-01",
  "validTo": "2027-10-31"
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Delete a tag

DELETE/tags/{tagId}

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.

Path parameters

tagIdstringrequired

The unique identifier of the tag.

Headers

X-Idempotency-Keystringmax 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.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

DELETE /tags/{tagId}

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'

fetch('https://apiv2.example.com/api/v2/tags/3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})

requests.delete(
    "https://apiv2.example.com/api/v2/tags/3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/tags/3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f"

	req, _ := http.NewRequest("DELETE", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

End a tag

POST/tags/{tagId}/end

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.

Path parameters

tagIdstringrequired

The unique identifier of the tag.

Headers

X-Idempotency-Keystringmax 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.

BodyEndTagRequestrequiredapplication/json

A request to end a tag.

validTostringdaterequired

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.

application/json

The tag was ended.

one ofTag

A tag on a subscription, a customer or a license. The type decides the shape of the value.

We add new tag types without notice. Your client must accept a type that it does not know.

Selected by type.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

DIRECT_SALE
PARTNER_SALE
PARTNER_LEAD
MARKETING_SALE
SUPPORT_SALE
ONLINE_SALE
COMPANY_OWNER
INVITE_SALE
REFERRAL_SALE
SALES
ABROAD
DISCOUNT
ENABLE_FEATURE
CUSTOM

valuestringpersonal datarequired

The value of the tag.

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

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

valuenumberrequired

The value of the tag. A percentage type holds a percentage, and an amount type holds an amount in major units of the currency.

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

CALL_SERVICE
CHURN
SUPPORT
PROVISIONING
CHARITY
INVOICE_PERIOD_TYPE
REMOVE_FEE

valuestringrequired

The value of the tag. It is one of the options that GET /tag-types gives for the type.

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

BILLING_IGNORE_CUSTOMER
INVOICE_IGNORE_CUSTOMER
INVOICE_PROTECTED_IDENTITY

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

PRICE_LIST
PRODUCT_CATALOG

valuestringrequired

The unique identifier of the entity that the tag points to, for example a price list.

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

MANUAL_CHARGE

manualChargeobjectrequired

A charge that the invoice includes.

Show child attributes

descriptionstringpersonal datamin length 1required

The text of the charge on the invoice. It must not contain a colon.

amountMinorintegerint64required

The amount of the charge, in minor units of the currency (for example 2900 = $29.00 when the currency is USD).

currencystringrequired

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

validFromstringdate

The first date that the tag is valid. If it is absent, the tag is valid from the start.

validTostringdate

The last date that the tag is valid. If it is absent, the tag has no end.

tagIdstringrequired

The unique identifier of the tag.

createdAtstringdate-timerequired

The time when the tag was created.

subscriptionIdstring

The unique identifier of the subscription that the tag attaches to.

customerIdstring

The unique identifier of the customer that the tag attaches to.

licenseIdstring

The unique identifier of the license that the tag attaches to.

typeenum<string>required

The type of the tag. The type decides the shape of the value.

values

MANUAL_CHARGE_ONCE

manualChargeobjectrequired

A charge that the invoice includes.

Show child attributes

descriptionstringpersonal datamin length 1required

The text of the charge on the invoice. It must not contain a colon.

amountMinorintegerint64required

The amount of the charge, in minor units of the currency (for example 2900 = $29.00 when the currency is USD).

currencystringrequired

The three-letter ISO 4217 code of the currency used for prices, billing, and payments.

chargeDatestringdaterequired

The date of the charge. The invoice that covers this date includes the charge one time.

400

The request was malformed or invalid.

application/json

The request was malformed or invalid.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

401

Authentication is required to access this resource.

application/json

Authentication is required to access this resource.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

403

Access to this resource is forbidden.

application/json

Access to this resource is forbidden.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

404

The requested resource was not found.

application/json

The requested resource was not found.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

409

The request conflicts with the current state of the resource.

application/json

The request conflicts with the current state of the resource.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

500

An unexpected error occurred on the server.

application/json

An unexpected error occurred on the server.

objectError

The error body returned by every endpoint when a request fails. Branch on reason, show message to a human, and check details for field-level problems when the request was invalid.

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason.

This field mixes three unrelated codes and does not say which one you have: a code that we publish, an operator's own code when the failure came from an operator, or the request status when there is neither. Do not branch on it.

reasonstring

Names the condition that failed, in lower snake_case. It is independent of which system reported the failure, and it is stable across releases. Branch on this field. We add new reasons without notice, so your client must accept a reason that it does not know.

If the request has problems with different reasons, the reason is validation_failed. Then each item of details names its own problem.

domainstring

The business area of the reason, for example customer or porting. It is for information only. Do not branch on it.

retryableboolean

True when the same request can pass later with no change. A 429 and a 503 are always retryable.

externalCodestring

The code that a third party, for example a network operator, sent for the failure. It is exactly as the third party sent it.

externalSourcestring

The third party that reported the failure.

internalCodestring

The number of the condition that failed. It is stable across releases. A condition that we added after reason has no number, so branch on reason instead.

detailsarray of object

Additional details about the error, typically one entry per invalid field on validation failures.

Show child attributes

messagestringrequired

A human-readable message providing more details about the error.

codestringdeprecatedrequired

Deprecated. Use reason. It is the status of the whole error, the same for each item.

reasonstring

Names the problem with the property. property_required is a missing value, property_invalid is a value with the wrong format, and property_conflict is two values that cannot occur together. Other reasons name a business condition. Your client must accept a reason that it does not know.

propertystring

The property or field related to the error. May be nested using dot notation (e.g., "billing.email").

suggestionone of

A suggested value for the particular property.

For example, this may be set when validating an address with an alias, suggesting the expected value by the operator.

A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.

Show child attributes

hintstring

A hint to help resolve the error.

traceIdstring

Identifies the trace this request produced. Quote it when reporting a failure — it is what lets us find the request among everything else the platform served.

spanIdstring

The span within the trace that failed.

Auth required

Send one of

X-Api-Key
Bearer JWT + X-Api-Key

The API key is always required; the bearer token is optional.

POST /tags/{tagId}/end

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"
}'

fetch('https://apiv2.example.com/api/v2/tags/3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f/end', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    validTo: '2026-12-31'
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/tags/3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f/end",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "validTo": "2026-12-31"
    }
)

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/tags/3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f/end"

	payload := strings.NewReader(`{
  "validTo": "2026-12-31"
}`)

	req, _ := http.NewRequest("POST", requestUrl, payload)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

{
  "tagId": "3f6c2a1e-8b4d-4c7a-9e2f-1a5b6c7d8e9f",
  "createdAt": "2026-10-29T08:30:00Z",
  "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
  "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
  "licenseId": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",
  "type": "DIRECT_SALE",
  "value": "seller@example.com",
  "validFrom": "2026-11-01",
  "validTo": "2027-10-31"
}

{
  "message": "The request body is invalid.",
  "code": "bad_request",
  "details": [
    {
      "message": "Email format is invalid.",
      "code": "invalid_email",
      "property": "contact.email"
    }
  ],
  "hint": "Check the request payload and correct the highlighted fields."
}

{
  "message": "Authentication is required to access this resource.",
  "code": "unauthorized",
  "hint": "Provide a valid API key in the X-Api-Key header."
}

{
  "message": "You do not have permission to perform this action.",
  "code": "forbidden",
  "hint": "Ensure your API key or user has the required permissions."
}

{
  "message": "The requested customer could not be found.",
  "code": "not_found",
  "hint": "Verify the customerId and try again."
}

{
  "message": "The request conflicts with the current state of the resource.",
  "code": "conflict",
  "hint": "Reload the resource to get its latest state before retrying."
}

{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Tags

List the tag types

Query parameters

Responses

List tags

Query parameters

Responses

Create a tag

Headers

BodyCreateTagRequestrequiredapplication/json

Responses

Get a tag

Path parameters

Responses

Delete a tag

Path parameters

Headers

Responses

End a tag

Path parameters

Headers

BodyEndTagRequestrequiredapplication/json

Responses

Tags

List the tag types

Query parameters

Responses

List tags

Query parameters

Responses

Create a tag

Headers

Body·CreateTagRequestrequiredapplication/json

Responses

Get a tag

Path parameters

Responses

Delete a tag

Path parameters

Headers

Responses

End a tag

Path parameters

Headers

Body·EndTagRequestrequiredapplication/json

Responses

BodyCreateTagRequestrequiredapplication/json

BodyEndTagRequestrequiredapplication/json