Valdyr

Subscription Actions

Start actions on subscriptions, and follow the progress of each action.

List subscription actions

GET/subscription-actions

List the actions of the subscriptions that you can access, newest scheduled first. The list does not include a removed plan that never started.

Query parameters

limitinteger>= 1<= 1000default 100

The maximum number of items to return.

cursorstring

Opaque pagination token from a previous response's nextCursor.

customerIdarray of string

Filter by customer IDs. When omitted, include all customers visible to the caller.

subscriptionIdstring

Optionally restrict results to one subscription of the selected customers.

Responses

200

Subscription actions retrieved successfully

application/json

Subscription actions retrieved successfully

object

itemsarray of SubscriptionActionrequired
Show child attributes
actionIdstringrequired

Unique identifier for this action.

subscriptionIdstringrequired

Subscription affected by this action.

customerIdstringrequired

Customer that owns the subscription.

typeenum<string>required

The kind of recorded subscription action. The list includes legacy values that can occur in historical records. A caller must tolerate new values.

values

  • UNKNOWN
  • CREATE
  • CREATE_WITH_PORT_IN
  • CHANGE_PRODUCT
  • CHANGE_SIM_CARD
  • CHANGE_VANITY_NUMBER_FORWARD
  • CHANGE_MSISDN
  • CHANGE_MSISDN_WITH_PORT_IN
  • GET_NEW_MSISDN
  • CHANGE_RATE_PLAN
  • PAUSE
  • SUSPEND
  • BAR
  • RESTORE
  • CANCEL
  • RESET_NETWORK
  • ENABLE_ADDON
  • CANCEL_ADDON
  • CHANGE_ADDON_PRODUCT
  • EXPIRE_ADDON
  • MOVED_FROM_ANOTHER_CUSTOMER
  • CANCEL_DEVICE_LOCATION
  • RESET_VOICEMAIL_PASSWORD
  • UPDATE_ROAMING_LIMIT
  • ENABLE_VOWIFI
  • RESEND_ESIM_QR_CODE
  • RECONNECT
  • PORT_BACK
  • PORT_OUT
  • CHANGE_E911_ADDRESS
  • TOPUP
  • MOVE_TO_ANOTHER_CUSTOMER
  • OPEN_FOR_OUTPORTING
  • ADD_CONTRACT_PERIOD
  • LEGACY_UPDATE
statusenum<string>required

The recorded execution state of an action. UNKNOWN means that the state is not known. PENDING waits for execution. RUNNING is in progress. SUCCESS and FAILURE describe the result of execution. A caller must tolerate new values.

values

  • UNKNOWN
  • PENDING
  • RUNNING
  • SUCCESS
  • FAILURE
scheduleModeenum<string>required

How the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values.

values

  • UNKNOWN
  • IMMEDIATE
  • AT_SPECIFIED_DATE
  • AT_SPECIFIED_DATE_TIME
  • ON_DEMAND
applyAtstringdate-timerequired

When the operation is scheduled to take effect.

executionStartedAtstringdate-time

When execution began, if it has started.

executionFinishedAtstringdate-time

When execution ended, if it has finished.

failureReasonstring

Names the condition that failed the action, in lower snake_case. The values are the same as the reason of an error response. For example, invalid_e911_address means that the network operator refused the service address as an E911 address. Only an action with the status FAILURE has this field, and such an action can also fail without a reason. Your client must accept a reason that it does not know.

createdAtstringdate-timerequired

When the action was created.

updatedAtstringdate-timerequired

When the action was most recently updated.

paginationobjectrequired

Cursor-based pagination information returned by list endpoints. Pass nextCursor as the cursor query parameter of the next request to fetch the following page.

Show child attributes
nextCursorstring | nullrequired

Opaque token for fetching the next page. Null when no more results.

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 /subscription-actions
curl https://apiv2.example.com/api/v2/subscription-actions \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/subscription-actions', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/subscription-actions",
    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/subscription-actions"

	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": [
    {
      "actionId": "string",
      "subscriptionId": "string",
      "customerId": "string",
      "type": "ENABLE_VOWIFI",
      "status": "PENDING",
      "scheduleMode": "ON_DEMAND",
      "applyAt": "2024-01-15T10:30:00Z",
      "executionStartedAt": "2024-01-15T10:30:00Z",
      "executionFinishedAt": "2024-01-15T10:30:00Z",
      "failureReason": "invalid_e911_address",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvZmZzZXQiOjEwMH0"
  }
}
{
  "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."
}

Get subscription action

GET/subscription-actions/{actionId}

Get the execution state of an action. An action of a subscription that you cannot access and a missing action both return not found.

Path parameters

actionIdstringrequired

Unique identifier of the action.

Responses

200

Subscription action retrieved successfully

application/json

Subscription action retrieved successfully

objectSubscriptionAction

A subscription operation and its execution state. Action payloads and internal task details are not exposed.

actionIdstringrequired

Unique identifier for this action.

subscriptionIdstringrequired

Subscription affected by this action.

customerIdstringrequired

Customer that owns the subscription.

typeenum<string>required

The kind of recorded subscription action. The list includes legacy values that can occur in historical records. A caller must tolerate new values.

values

  • UNKNOWN
  • CREATE
  • CREATE_WITH_PORT_IN
  • CHANGE_PRODUCT
  • CHANGE_SIM_CARD
  • CHANGE_VANITY_NUMBER_FORWARD
  • CHANGE_MSISDN
  • CHANGE_MSISDN_WITH_PORT_IN
  • GET_NEW_MSISDN
  • CHANGE_RATE_PLAN
  • PAUSE
  • SUSPEND
  • BAR
  • RESTORE
  • CANCEL
  • RESET_NETWORK
  • ENABLE_ADDON
  • CANCEL_ADDON
  • CHANGE_ADDON_PRODUCT
  • EXPIRE_ADDON
  • MOVED_FROM_ANOTHER_CUSTOMER
  • CANCEL_DEVICE_LOCATION
  • RESET_VOICEMAIL_PASSWORD
  • UPDATE_ROAMING_LIMIT
  • ENABLE_VOWIFI
  • RESEND_ESIM_QR_CODE
  • RECONNECT
  • PORT_BACK
  • PORT_OUT
  • CHANGE_E911_ADDRESS
  • TOPUP
  • MOVE_TO_ANOTHER_CUSTOMER
  • OPEN_FOR_OUTPORTING
  • ADD_CONTRACT_PERIOD
  • LEGACY_UPDATE
statusenum<string>required

The recorded execution state of an action. UNKNOWN means that the state is not known. PENDING waits for execution. RUNNING is in progress. SUCCESS and FAILURE describe the result of execution. A caller must tolerate new values.

values

  • UNKNOWN
  • PENDING
  • RUNNING
  • SUCCESS
  • FAILURE
scheduleModeenum<string>required

How the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values.

values

  • UNKNOWN
  • IMMEDIATE
  • AT_SPECIFIED_DATE
  • AT_SPECIFIED_DATE_TIME
  • ON_DEMAND
applyAtstringdate-timerequired

When the operation is scheduled to take effect.

executionStartedAtstringdate-time

When execution began, if it has started.

executionFinishedAtstringdate-time

When execution ended, if it has finished.

failureReasonstring

Names the condition that failed the action, in lower snake_case. The values are the same as the reason of an error response. For example, invalid_e911_address means that the network operator refused the service address as an E911 address. Only an action with the status FAILURE has this field, and such an action can also fail without a reason. Your client must accept a reason that it does not know.

createdAtstringdate-timerequired

When the action was created.

updatedAtstringdate-timerequired

When the action was most recently updated.

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 /subscription-actions/{actionId}
curl https://apiv2.example.com/api/v2/subscription-actions/ACTION_ID \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/subscription-actions/ACTION_ID', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/subscription-actions/ACTION_ID",
    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/subscription-actions/ACTION_ID"

	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))

}
{
  "actionId": "string",
  "subscriptionId": "string",
  "customerId": "string",
  "type": "ENABLE_VOWIFI",
  "status": "PENDING",
  "scheduleMode": "ON_DEMAND",
  "applyAt": "2024-01-15T10:30:00Z",
  "executionStartedAt": "2024-01-15T10:30:00Z",
  "executionFinishedAt": "2024-01-15T10:30:00Z",
  "failureReason": "invalid_e911_address",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
{
  "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."
}

List the action options of a subscription

GET/subscriptions/{subscriptionId}/action-options

List the actions that the caller can start on one subscription with startSubscriptionAction. Read it before you show the buttons for these actions.

  • An action is absent when the brand or the network operator does not offer it. Do not show it.
  • An action has available false when the state of the subscription refuses it now. Then refusalReason is the reason that startSubscriptionAction gives.
  • An available action gives the date that it gets when the request names no date.

The End-User API applies the rules of the manager portal. The Platform API applies the rules of the admin portal.

Path parameters

subscriptionIdstringrequired

The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

Responses

200

The action options of the subscription.

application/json

The action options of the subscription.

object

itemsarray of SubscriptionActionOptionrequired
Show child attributes
typeenum<string>required

The type to send to startSubscriptionAction. A caller must tolerate new values.

values

  • PAUSE
  • RESTORE
  • CANCEL
  • BLOCK_SIM
  • RESET_NETWORK
  • ACTIVATE
availablebooleanrequired

True when startSubscriptionAction accepts the action now. False when the state of the subscription refuses it now. Then refusalReason gives the cause.

refusalReasonstring

The reason of the error that startSubscriptionAction gives for the action now. It is present only when available is false.

scheduleModeenum<string>

How the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values.

values

  • UNKNOWN
  • IMMEDIATE
  • AT_SPECIFIED_DATE
  • AT_SPECIFIED_DATE_TIME
  • ON_DEMAND
effectiveDatestringdate

The date that the action gets when the request names no date. It is absent when the action is refused, or when the request must name the date.

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 /subscriptions/{subscriptionId}/action-options
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/action-options \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/action-options', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/action-options",
    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/subscriptions/SUBSCRIPTION_ID/action-options"

	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": "CANCEL",
      "available": false,
      "refusalReason": "subscription_in_binding_period"
    },
    {
      "type": "PAUSE",
      "available": true,
      "scheduleMode": "AT_SPECIFIED_DATE",
      "effectiveDate": "2026-12-01"
    },
    {
      "type": "BLOCK_SIM",
      "available": true,
      "scheduleMode": "IMMEDIATE",
      "effectiveDate": "2026-11-30"
    }
  ]
}
{
  "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."
}

List the actions of a subscription

GET/subscriptions/{subscriptionId}/actions

List the actions of one subscription, with the newest scheduled action first. An action records a change to the subscription and the progress of that change. The list leaves out a removed action that never started.

Path parameters

subscriptionIdstringrequired

The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

Query parameters

limitinteger>= 1<= 1000default 100

The maximum number of items to return.

cursorstring

Opaque pagination token from a previous response's nextCursor.

Responses

200

The actions of the subscription.

application/json

The actions of the subscription.

object

itemsarray of SubscriptionActionrequired
Show child attributes
actionIdstringrequired

Unique identifier for this action.

subscriptionIdstringrequired

Subscription affected by this action.

customerIdstringrequired

Customer that owns the subscription.

typeenum<string>required

The kind of recorded subscription action. The list includes legacy values that can occur in historical records. A caller must tolerate new values.

values

  • UNKNOWN
  • CREATE
  • CREATE_WITH_PORT_IN
  • CHANGE_PRODUCT
  • CHANGE_SIM_CARD
  • CHANGE_VANITY_NUMBER_FORWARD
  • CHANGE_MSISDN
  • CHANGE_MSISDN_WITH_PORT_IN
  • GET_NEW_MSISDN
  • CHANGE_RATE_PLAN
  • PAUSE
  • SUSPEND
  • BAR
  • RESTORE
  • CANCEL
  • RESET_NETWORK
  • ENABLE_ADDON
  • CANCEL_ADDON
  • CHANGE_ADDON_PRODUCT
  • EXPIRE_ADDON
  • MOVED_FROM_ANOTHER_CUSTOMER
  • CANCEL_DEVICE_LOCATION
  • RESET_VOICEMAIL_PASSWORD
  • UPDATE_ROAMING_LIMIT
  • ENABLE_VOWIFI
  • RESEND_ESIM_QR_CODE
  • RECONNECT
  • PORT_BACK
  • PORT_OUT
  • CHANGE_E911_ADDRESS
  • TOPUP
  • MOVE_TO_ANOTHER_CUSTOMER
  • OPEN_FOR_OUTPORTING
  • ADD_CONTRACT_PERIOD
  • LEGACY_UPDATE
statusenum<string>required

The recorded execution state of an action. UNKNOWN means that the state is not known. PENDING waits for execution. RUNNING is in progress. SUCCESS and FAILURE describe the result of execution. A caller must tolerate new values.

values

  • UNKNOWN
  • PENDING
  • RUNNING
  • SUCCESS
  • FAILURE
scheduleModeenum<string>required

How the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values.

values

  • UNKNOWN
  • IMMEDIATE
  • AT_SPECIFIED_DATE
  • AT_SPECIFIED_DATE_TIME
  • ON_DEMAND
applyAtstringdate-timerequired

When the operation is scheduled to take effect.

executionStartedAtstringdate-time

When execution began, if it has started.

executionFinishedAtstringdate-time

When execution ended, if it has finished.

failureReasonstring

Names the condition that failed the action, in lower snake_case. The values are the same as the reason of an error response. For example, invalid_e911_address means that the network operator refused the service address as an E911 address. Only an action with the status FAILURE has this field, and such an action can also fail without a reason. Your client must accept a reason that it does not know.

createdAtstringdate-timerequired

When the action was created.

updatedAtstringdate-timerequired

When the action was most recently updated.

paginationobjectrequired

Cursor-based pagination information returned by list endpoints. Pass nextCursor as the cursor query parameter of the next request to fetch the following page.

Show child attributes
nextCursorstring | nullrequired

Opaque token for fetching the next page. Null when no more results.

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 /subscriptions/{subscriptionId}/actions
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions",
    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/subscriptions/SUBSCRIPTION_ID/actions"

	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": [
    {
      "actionId": "string",
      "subscriptionId": "string",
      "customerId": "string",
      "type": "ENABLE_VOWIFI",
      "status": "PENDING",
      "scheduleMode": "ON_DEMAND",
      "applyAt": "2024-01-15T10:30:00Z",
      "executionStartedAt": "2024-01-15T10:30:00Z",
      "executionFinishedAt": "2024-01-15T10:30:00Z",
      "failureReason": "invalid_e911_address",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvZmZzZXQiOjEwMH0"
  }
}
{
  "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."
}

Start an action on a subscription

POST/subscriptions/{subscriptionId}/actions

Start an action on one subscription. The type of the body selects the action, and each type has its own fields.

typeWhat it does
PAUSEPauses the subscription.
RESTORERestores a paused, suspended or blocked subscription.
CANCELCancels the subscription.
BLOCK_SIMBlocks the SIM card at once. The action has the type BAR.
RESET_NETWORKResets the network services at the network operator.

The response is the action. Read it again with getActionOfSubscription to follow its status.

A RESET_NETWORK that started or ended in the last 15 minutes is given again, and no second reset starts. If the brand or the network operator does not offer a network reset, the 409 response gives the reason subscription_action_not_offered.

Path parameters

subscriptionIdstringrequired

The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

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.

BodyStartSubscriptionActionRequestrequiredapplication/json

The action to start on the subscription. The type decides the other fields.

Selected by type.

typeenum<string>required

The action to start.

values

  • PAUSE
scheduledAtstringdate

The first date of the pause. If it is absent, the pause starts at once.

metadataobject with string keys

A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.

Show child attributes
*string
typeenum<string>required

The action to start.

values

  • RESTORE
scheduledAtstringdate

The date of the restore. If it is absent, the restore occurs today.

allowedCurrentStatusesarray of SubscriptionStatus

The statuses that the restore can start from. If it is absent, the restore can start from each status that a restore supports.

barReasonsarray of BarReasonmin items 1

The reasons of the bars to remove from a BLOCKED subscription. If it is absent, the restore removes each bar. The subscription is activated only when no bar stays.

typeenum<string>required

The action to start.

values

  • CANCEL
cancelAtone ofrequired

The date of the cancel.

Show child attributes
churnenum<string>

The reason for the cancel. We use it for reports and analysis.

If you give OTHER, you must also give a comment.

values

  • BETTER_DEAL_PRICE
  • NOT_HAPPY_MISSING_FUNCTIONS
  • NOT_HAPPY_COVERAGE_SLA
  • NOT_HAPPY_COMPLEX_ADMIN
  • NOT_HAPPY_SUPPORT_ENGAGEMENT
  • FRAUD
  • FRAUD_ATTEMPT
  • TEST_OR_MARKETING
  • NO_NEED
  • WRONG_ORDER
  • OTHER
commentstring

A comment about the cancel. It is necessary when churn is OTHER.

typeenum<string>required

The action to start.

values

  • BLOCK_SIM
typeenum<string>required

The action to start.

values

  • RESET_NETWORK
confirmedbooleanrequired

Must be true. It records that the user accepts a short stop of the service.

Responses

201

The action started.

application/json

The action started.

objectSubscriptionAction

A subscription operation and its execution state. Action payloads and internal task details are not exposed.

actionIdstringrequired

Unique identifier for this action.

subscriptionIdstringrequired

Subscription affected by this action.

customerIdstringrequired

Customer that owns the subscription.

typeenum<string>required

The kind of recorded subscription action. The list includes legacy values that can occur in historical records. A caller must tolerate new values.

values

  • UNKNOWN
  • CREATE
  • CREATE_WITH_PORT_IN
  • CHANGE_PRODUCT
  • CHANGE_SIM_CARD
  • CHANGE_VANITY_NUMBER_FORWARD
  • CHANGE_MSISDN
  • CHANGE_MSISDN_WITH_PORT_IN
  • GET_NEW_MSISDN
  • CHANGE_RATE_PLAN
  • PAUSE
  • SUSPEND
  • BAR
  • RESTORE
  • CANCEL
  • RESET_NETWORK
  • ENABLE_ADDON
  • CANCEL_ADDON
  • CHANGE_ADDON_PRODUCT
  • EXPIRE_ADDON
  • MOVED_FROM_ANOTHER_CUSTOMER
  • CANCEL_DEVICE_LOCATION
  • RESET_VOICEMAIL_PASSWORD
  • UPDATE_ROAMING_LIMIT
  • ENABLE_VOWIFI
  • RESEND_ESIM_QR_CODE
  • RECONNECT
  • PORT_BACK
  • PORT_OUT
  • CHANGE_E911_ADDRESS
  • TOPUP
  • MOVE_TO_ANOTHER_CUSTOMER
  • OPEN_FOR_OUTPORTING
  • ADD_CONTRACT_PERIOD
  • LEGACY_UPDATE
statusenum<string>required

The recorded execution state of an action. UNKNOWN means that the state is not known. PENDING waits for execution. RUNNING is in progress. SUCCESS and FAILURE describe the result of execution. A caller must tolerate new values.

values

  • UNKNOWN
  • PENDING
  • RUNNING
  • SUCCESS
  • FAILURE
scheduleModeenum<string>required

How the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values.

values

  • UNKNOWN
  • IMMEDIATE
  • AT_SPECIFIED_DATE
  • AT_SPECIFIED_DATE_TIME
  • ON_DEMAND
applyAtstringdate-timerequired

When the operation is scheduled to take effect.

executionStartedAtstringdate-time

When execution began, if it has started.

executionFinishedAtstringdate-time

When execution ended, if it has finished.

failureReasonstring

Names the condition that failed the action, in lower snake_case. The values are the same as the reason of an error response. For example, invalid_e911_address means that the network operator refused the service address as an E911 address. Only an action with the status FAILURE has this field, and such an action can also fail without a reason. Your client must accept a reason that it does not know.

createdAtstringdate-timerequired

When the action was created.

updatedAtstringdate-timerequired

When the action was most recently updated.

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.

412

A precondition for this request was not met.

application/json

A precondition for this request was not met.

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 /subscriptions/{subscriptionId}/actions
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "PAUSE",
  "scheduledAt": "2026-12-01"
}'
fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'PAUSE',
    scheduledAt: '2026-12-01'
  })
})
requests.post(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "type": "PAUSE",
      "scheduledAt": "2026-12-01"
    }
)
package main

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

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

	payload := strings.NewReader(`{
  "type": "PAUSE",
  "scheduledAt": "2026-12-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))

}
{
  "actionId": "string",
  "subscriptionId": "string",
  "customerId": "string",
  "type": "ENABLE_VOWIFI",
  "status": "PENDING",
  "scheduleMode": "ON_DEMAND",
  "applyAt": "2024-01-15T10:30:00Z",
  "executionStartedAt": "2024-01-15T10:30:00Z",
  "executionFinishedAt": "2024-01-15T10:30:00Z",
  "failureReason": "invalid_e911_address",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
{
  "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": "A precondition given in the request headers was not met.",
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition."
}
{
  "message": "An unexpected error occurred on the server.",
  "code": "internal_server_error",
  "hint": "Retry the request later. If the problem persists, contact support."
}

Get an action of a subscription

GET/subscriptions/{subscriptionId}/actions/{actionId}

Get one action of a subscription and its progress. An action of another subscription gets the same 404 response as a missing action.

Path parameters

subscriptionIdstringrequired

The identifier of the subscription. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with rid_ (e.g., rid_crm-subscription-12345) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup.

actionIdstringrequired

The identifier of the action.

Responses

200

The action.

application/json

The action.

objectSubscriptionAction

A subscription operation and its execution state. Action payloads and internal task details are not exposed.

actionIdstringrequired

Unique identifier for this action.

subscriptionIdstringrequired

Subscription affected by this action.

customerIdstringrequired

Customer that owns the subscription.

typeenum<string>required

The kind of recorded subscription action. The list includes legacy values that can occur in historical records. A caller must tolerate new values.

values

  • UNKNOWN
  • CREATE
  • CREATE_WITH_PORT_IN
  • CHANGE_PRODUCT
  • CHANGE_SIM_CARD
  • CHANGE_VANITY_NUMBER_FORWARD
  • CHANGE_MSISDN
  • CHANGE_MSISDN_WITH_PORT_IN
  • GET_NEW_MSISDN
  • CHANGE_RATE_PLAN
  • PAUSE
  • SUSPEND
  • BAR
  • RESTORE
  • CANCEL
  • RESET_NETWORK
  • ENABLE_ADDON
  • CANCEL_ADDON
  • CHANGE_ADDON_PRODUCT
  • EXPIRE_ADDON
  • MOVED_FROM_ANOTHER_CUSTOMER
  • CANCEL_DEVICE_LOCATION
  • RESET_VOICEMAIL_PASSWORD
  • UPDATE_ROAMING_LIMIT
  • ENABLE_VOWIFI
  • RESEND_ESIM_QR_CODE
  • RECONNECT
  • PORT_BACK
  • PORT_OUT
  • CHANGE_E911_ADDRESS
  • TOPUP
  • MOVE_TO_ANOTHER_CUSTOMER
  • OPEN_FOR_OUTPORTING
  • ADD_CONTRACT_PERIOD
  • LEGACY_UPDATE
statusenum<string>required

The recorded execution state of an action. UNKNOWN means that the state is not known. PENDING waits for execution. RUNNING is in progress. SUCCESS and FAILURE describe the result of execution. A caller must tolerate new values.

values

  • UNKNOWN
  • PENDING
  • RUNNING
  • SUCCESS
  • FAILURE
scheduleModeenum<string>required

How the action is scheduled. UNKNOWN means that the schedule mode is not known. IMMEDIATE starts execution at once. AT_SPECIFIED_DATE and AT_SPECIFIED_DATE_TIME target a specified date or time. ON_DEMAND starts execution on demand. A caller must tolerate new values.

values

  • UNKNOWN
  • IMMEDIATE
  • AT_SPECIFIED_DATE
  • AT_SPECIFIED_DATE_TIME
  • ON_DEMAND
applyAtstringdate-timerequired

When the operation is scheduled to take effect.

executionStartedAtstringdate-time

When execution began, if it has started.

executionFinishedAtstringdate-time

When execution ended, if it has finished.

failureReasonstring

Names the condition that failed the action, in lower snake_case. The values are the same as the reason of an error response. For example, invalid_e911_address means that the network operator refused the service address as an E911 address. Only an action with the status FAILURE has this field, and such an action can also fail without a reason. Your client must accept a reason that it does not know.

createdAtstringdate-timerequired

When the action was created.

updatedAtstringdate-timerequired

When the action was most recently updated.

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 /subscriptions/{subscriptionId}/actions/{actionId}
curl https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions/ACTION_ID \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
fetch('https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions/ACTION_ID', {
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'X-Api-Key': 'YOUR_API_KEY'
  }
})
requests.get(
    "https://apiv2.example.com/api/v2/subscriptions/SUBSCRIPTION_ID/actions/ACTION_ID",
    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/subscriptions/SUBSCRIPTION_ID/actions/ACTION_ID"

	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))

}
{
  "actionId": "string",
  "subscriptionId": "string",
  "customerId": "string",
  "type": "ENABLE_VOWIFI",
  "status": "PENDING",
  "scheduleMode": "ON_DEMAND",
  "applyAt": "2024-01-15T10:30:00Z",
  "executionStartedAt": "2024-01-15T10:30:00Z",
  "executionFinishedAt": "2024-01-15T10:30:00Z",
  "failureReason": "invalid_e911_address",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
{
  "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."
}