Orders

The orders that the user makes and submits.

List orders

GET/orders

List orders with optional filtering and pagination.

Query parameters

limitinteger>= 1<= 1000default 100

The maximum number of items to return.

cursorstring

Opaque pagination token from a previous response's nextCursor.

stateenum<string>

Filter by order state

The status of an order in its lifecycle.

PENDING: Order is in cart state, can be modified
PENDING_PAYMENT: Order is locked and awaiting payment completion
SUBMITTED: Order has been submitted for processing
PENDING_APPROVAL: Order is pending approval
PROCESSING: Order is being fulfilled
COMPLETED: Order has been successfully fulfilled
CANCELLED: Order was cancelled before completion
EXPIRED: Order expired due to inactivity
FAILED: Order fulfillment failed

values

PENDING
PENDING_PAYMENT
SUBMITTED
PENDING_APPROVAL
PROCESSING
COMPLETED
CANCELLED
EXPIRED
FAILED

userIdstring

Filter by user ID

customerIdstring

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

expiresAfterstringdate-time

Filter orders expiring after this date

expiresBeforestringdate-time

Filter orders expiring before this date

Responses

200

Orders retrieved successfully

application/json

Orders retrieved successfully

object

itemsarray of OrderListItemrequired

Show child attributes

createdAtstringdate-timerequired

When the order was created.

customerobject

Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.

Show child attributes

customerIdstringrequired

The unique identifier for the customer. Use it with the customer endpoints to fetch full details.

namestringrequired

The customer's display name — the company name for business customers or the person's full name for consumers.

expiresAtstringdate-time

When the order will expire if not submitted.

orderIdstringrequired

The unique identifier for the order.

pricingobject

Summary pricing information for the order.

Show child attributes

currencystringrequired

ISO 4217 currency code.

totalMinorintegerint64required

Final order total including all taxes and fees, in minor currency units.

stateenum<string>required

The status of an order in its lifecycle.

PENDING: Order is in cart state, can be modified
PENDING_PAYMENT: Order is locked and awaiting payment completion
SUBMITTED: Order has been submitted for processing
PENDING_APPROVAL: Order is pending approval
PROCESSING: Order is being fulfilled
COMPLETED: Order has been successfully fulfilled
CANCELLED: Order was cancelled before completion
EXPIRED: Order expired due to inactivity
FAILED: Order fulfillment failed

values

PENDING
PENDING_PAYMENT
SUBMITTED
PENDING_APPROVAL
PROCESSING
COMPLETED
CANCELLED
EXPIRED
FAILED

updatedAtstringdate-timerequired

When the order was last updated.

validationStatusenum<string>

Whether the order is complete and ready for submission. Fetch the full order to see which fields are missing or invalid.

values

VALID
INVALID
PENDING_VALIDATION

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

Auth required

Send

X-Api-Key + Bearer JWT

GET /orders

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

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

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

package main

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

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/orders"

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

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

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

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

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

}

{
  "items": [
    {
      "createdAt": "2024-01-15T10:00:00Z",
      "customer": {
        "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "name": "John Doe"
      },
      "expiresAt": "2024-01-22T10:30:00Z",
      "orderId": "ce0539b4-ec57-4709-b72e-47892586d05a",
      "pricing": {
        "currency": "USD",
        "totalMinor": 13739
      },
      "state": "PENDING",
      "updatedAt": "2024-01-15T10:30:00Z",
      "validationStatus": "VALID"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvZmZzZXQiOjEwMH0"
  }
}

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

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

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

{
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header.",
  "message": "Too many requests. Please slow down."
}

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

Auth required

Send

X-Api-Key + Bearer JWT

POST /orders

curl https://apiv2.example.com/api/v2/end-user/orders \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "billing": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "email": "billing@example.com",
    "name": "John Doe"
  },
  "consents": {
    "marketing": "true",
    "termsOfService": "true"
  },
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "customerType": "CONSUMER",
  "lineItems": [
    {
      "activateOnDemand": true,
      "display": "John Doe - Work phone",
      "extensions": {
        "propertyName": "string"
      },
      "leaseToken": "lease_8f3b1c2d4e5f6789",
      "lineItemId": "line-item-1",
      "metadata": {
        "propertyName": "string"
      },
      "msisdn": "+15551234567",
      "porting": {
        "details": {
          "accountNumber": "987654321",
          "address": {
            "attention": "John Doe",
            "city": "Natick",
            "country": "US",
            "region": "Ontario",
            "state": "CA",
            "street": "500 S Main St",
            "street1": "string",
            "street2": "Apt 1",
            "zip": "01701"
          },
          "firstName": "John",
          "lastName": "Doe",
          "passcode": "123456"
        }
      },
      "portingRequested": true,
      "productOfferingId": "mobile-plan-basic",
      "scheduleActivationAt": "2024-02-01",
      "sim": {
        "esim": true,
        "iccid": "8931440400000000000",
        "imei": "356938035643809"
      },
      "subscriber": {
        "address": {
          "attention": "John Doe",
          "city": "Natick",
          "country": "US",
          "region": "Ontario",
          "state": "CA",
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "zip": "01701"
        },
        "email": "john.doe@example.com",
        "msisdn": "+15551234567",
        "name": "John Doe"
      },
      "tempNumber": true,
      "type": "SUBSCRIPTION"
    }
  ],
  "metadata": {
    "propertyName": "string"
  },
  "promoCode": "SUMMER2023",
  "shipping": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "instructions": "Leave at front door",
    "msisdn": "+15551234567",
    "name": "John Doe"
  }
}'

fetch('https://apiv2.example.com/api/v2/end-user/orders', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    billing: {
      address: {
        attention: 'John Doe',
        city: 'Natick',
        country: 'US',
        region: 'Ontario',
        state: 'CA',
        street: '500 S Main St',
        street1: 'string',
        street2: 'Apt 1',
        zip: '01701'
      },
      email: 'billing@example.com',
      name: 'John Doe'
    },
    consents: {
      marketing: 'true',
      termsOfService: 'true'
    },
    customer: {
      customerId: 'a47ac10b-58cc-4372-a567-0e02b2c3d479'
    },
    customerType: 'CONSUMER',
    lineItems: [
      {
        activateOnDemand: true,
        display: 'John Doe - Work phone',
        extensions: {
          propertyName: 'string'
        },
        leaseToken: 'lease_8f3b1c2d4e5f6789',
        lineItemId: 'line-item-1',
        metadata: {
          propertyName: 'string'
        },
        msisdn: '+15551234567',
        porting: {
          details: {
            accountNumber: '987654321',
            address: {
              attention: 'John Doe',
              city: 'Natick',
              country: 'US',
              region: 'Ontario',
              state: 'CA',
              street: '500 S Main St',
              street1: 'string',
              street2: 'Apt 1',
              zip: '01701'
            },
            firstName: 'John',
            lastName: 'Doe',
            passcode: '123456'
          }
        },
        portingRequested: true,
        productOfferingId: 'mobile-plan-basic',
        scheduleActivationAt: '2024-02-01',
        sim: {
          esim: true,
          iccid: '8931440400000000000',
          imei: '356938035643809'
        },
        subscriber: {
          address: {
            attention: 'John Doe',
            city: 'Natick',
            country: 'US',
            region: 'Ontario',
            state: 'CA',
            street: '500 S Main St',
            street1: 'string',
            street2: 'Apt 1',
            zip: '01701'
          },
          email: 'john.doe@example.com',
          msisdn: '+15551234567',
          name: 'John Doe'
        },
        tempNumber: true,
        type: 'SUBSCRIPTION'
      }
    ],
    metadata: {
      propertyName: 'string'
    },
    promoCode: 'SUMMER2023',
    shipping: {
      address: {
        attention: 'John Doe',
        city: 'Natick',
        country: 'US',
        region: 'Ontario',
        state: 'CA',
        street: '500 S Main St',
        street1: 'string',
        street2: 'Apt 1',
        zip: '01701'
      },
      instructions: 'Leave at front door',
      msisdn: '+15551234567',
      name: 'John Doe'
    }
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/end-user/orders",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "billing": {
        "address": {
          "attention": "John Doe",
          "city": "Natick",
          "country": "US",
          "region": "Ontario",
          "state": "CA",
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "zip": "01701"
        },
        "email": "billing@example.com",
        "name": "John Doe"
      },
      "consents": {
        "marketing": "true",
        "termsOfService": "true"
      },
      "customer": {
        "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
      },
      "customerType": "CONSUMER",
      "lineItems": [
        {
          "activateOnDemand": True,
          "display": "John Doe - Work phone",
          "extensions": {
            "propertyName": "string"
          },
          "leaseToken": "lease_8f3b1c2d4e5f6789",
          "lineItemId": "line-item-1",
          "metadata": {
            "propertyName": "string"
          },
          "msisdn": "+15551234567",
          "porting": {
            "details": {
              "accountNumber": "987654321",
              "address": {
                "attention": "John Doe",
                "city": "Natick",
                "country": "US",
                "region": "Ontario",
                "state": "CA",
                "street": "500 S Main St",
                "street1": "string",
                "street2": "Apt 1",
                "zip": "01701"
              },
              "firstName": "John",
              "lastName": "Doe",
              "passcode": "123456"
            }
          },
          "portingRequested": True,
          "productOfferingId": "mobile-plan-basic",
          "scheduleActivationAt": "2024-02-01",
          "sim": {
            "esim": True,
            "iccid": "8931440400000000000",
            "imei": "356938035643809"
          },
          "subscriber": {
            "address": {
              "attention": "John Doe",
              "city": "Natick",
              "country": "US",
              "region": "Ontario",
              "state": "CA",
              "street": "500 S Main St",
              "street1": "string",
              "street2": "Apt 1",
              "zip": "01701"
            },
            "email": "john.doe@example.com",
            "msisdn": "+15551234567",
            "name": "John Doe"
          },
          "tempNumber": True,
          "type": "SUBSCRIPTION"
        }
      ],
      "metadata": {
        "propertyName": "string"
      },
      "promoCode": "SUMMER2023",
      "shipping": {
        "address": {
          "attention": "John Doe",
          "city": "Natick",
          "country": "US",
          "region": "Ontario",
          "state": "CA",
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "zip": "01701"
        },
        "instructions": "Leave at front door",
        "msisdn": "+15551234567",
        "name": "John Doe"
      }
    }
)

package main

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

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/orders"

	payload := strings.NewReader(`{
  "billing": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "email": "billing@example.com",
    "name": "John Doe"
  },
  "consents": {
    "marketing": "true",
    "termsOfService": "true"
  },
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "customerType": "CONSUMER",
  "lineItems": [
    {
      "activateOnDemand": true,
      "display": "John Doe - Work phone",
      "extensions": {
        "propertyName": "string"
      },
      "leaseToken": "lease_8f3b1c2d4e5f6789",
      "lineItemId": "line-item-1",
      "metadata": {
        "propertyName": "string"
      },
      "msisdn": "+15551234567",
      "porting": {
        "details": {
          "accountNumber": "987654321",
          "address": {
            "attention": "John Doe",
            "city": "Natick",
            "country": "US",
            "region": "Ontario",
            "state": "CA",
            "street": "500 S Main St",
            "street1": "string",
            "street2": "Apt 1",
            "zip": "01701"
          },
          "firstName": "John",
          "lastName": "Doe",
          "passcode": "123456"
        }
      },
      "portingRequested": true,
      "productOfferingId": "mobile-plan-basic",
      "scheduleActivationAt": "2024-02-01",
      "sim": {
        "esim": true,
        "iccid": "8931440400000000000",
        "imei": "356938035643809"
      },
      "subscriber": {
        "address": {
          "attention": "John Doe",
          "city": "Natick",
          "country": "US",
          "region": "Ontario",
          "state": "CA",
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "zip": "01701"
        },
        "email": "john.doe@example.com",
        "msisdn": "+15551234567",
        "name": "John Doe"
      },
      "tempNumber": true,
      "type": "SUBSCRIPTION"
    }
  ],
  "metadata": {
    "propertyName": "string"
  },
  "promoCode": "SUMMER2023",
  "shipping": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "instructions": "Leave at front door",
    "msisdn": "+15551234567",
    "name": "John Doe"
  }
}`)

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

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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))

}

{
  "billing": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "email": "billing@example.com",
    "name": "John Doe"
  },
  "completedAt": "2024-01-15T15:00:00Z",
  "consents": {
    "marketing": "true",
    "termsOfService": "true"
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "createdEntities": {
    "addons": [
      {
        "addedAt": "2024-01-15T10:30:00Z",
        "cancelledAt": "2024-06-30T00:00:00Z",
        "licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
        "metadata": {
          "propertyName": "string"
        },
        "productOfferingGroupId": "extra-data-packages",
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "referenceId": "telna-package-12345",
        "status": "PENDING",
        "updatedAt": "2024-01-20T09:00:00Z",
        "createdByLineItem": "h47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ],
    "licenses": [
      {
        "activatedAt": "2024-01-15",
        "cancelledAt": "2024-06-30",
        "licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "status": "PENDING",
        "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "type": "PBX_USER_LEVEL",
        "createdByLineItem": "j47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ],
    "modifications": [
      {
        "appliedAt": "2024-01-15T15:00:00Z",
        "newProductOfferingId": "po_mobile_premium_plus",
        "targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "type": "SUBSCRIPTION_CHANGE",
        "createdByLineItem": "i47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ],
    "subscriptions": [
      {
        "activatedAt": "2024-01-15T10:30:00Z",
        "cancelledAt": "2024-06-30T00:00:00Z",
        "createdAt": "2024-01-10T08:00:00Z",
        "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "display": "(555) 123-4567",
        "msisdn": "+15551234567",
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "status": "PENDING",
        "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
        "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "type": "CELL",
        "updatedAt": "2024-01-15T10:30:00Z",
        "createdByLineItem": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ]
  },
  "customer": {
    "customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
    "customerType": "CONSUMER",
    "name": "John Doe",
    "newCustomer": true
  },
  "expiresAt": "2024-01-22T10:30:00Z",
  "externalPayment": {
    "receiptDescription": "Payment via external billing system",
    "receiptUrl": "https://external.example.com/receipts/123",
    "receivedAt": "2024-01-15T14:30:00Z",
    "reference": "ext-payment-ref-123"
  },
  "lineItems": [
    {
      "activateOnDemand": true,
      "display": "John Doe - Work phone",
      "extensions": {
        "propertyName": "string"
      },
      "leaseToken": "lease_8f3b1c2d4e5f6789",
      "lineItemId": "line-item-1",
      "metadata": {
        "propertyName": "string"
      },
      "msisdn": "+15551234567",
      "porting": {
        "details": {
          "accountNumber": "987654321",
          "address": {
            "attention": "John Doe",
            "city": "Natick",
            "country": "US",
            "region": "Ontario",
            "state": "CA",
            "street": "500 S Main St",
            "street1": "string",
            "street2": "Apt 1",
            "zip": "01701"
          },
          "firstName": "John",
          "lastName": "Doe",
          "passcode": "123456"
        }
      },
      "portingRequested": true,
      "productOfferingId": "mobile-plan-basic",
      "scheduleActivationAt": "2024-02-01",
      "sim": {
        "esim": true,
        "iccid": "8931440400000000000",
        "imei": "356938035643809"
      },
      "status": "PENDING",
      "subscriber": {
        "address": {
          "attention": "John Doe",
          "city": "Natick",
          "country": "US",
          "region": "Ontario",
          "state": "CA",
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "zip": "01701"
        },
        "email": "john.doe@example.com",
        "msisdn": "+15551234567",
        "name": "John Doe"
      },
      "tempNumber": true,
      "type": "SUBSCRIPTION"
    }
  ],
  "metadata": {
    "propertyName": "string"
  },
  "orderId": "order-123",
  "paymentProfileSessionId": "69321a62-f1fe-461f-8761-a19ae6587bb2",
  "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
  "pricing": {
    "amountDueNowMinor": 13739,
    "calculatedAt": "2024-01-15T10:30:00Z",
    "currency": "USD",
    "initialInvoice": {
      "period": {
        "end": "2024-01-31",
        "start": "2024-01-15"
      },
      "subtotalMinor": 1450,
      "taxAmountMinor": 116,
      "taxIncluded": true,
      "totalMinor": 1566
    },
    "recurringCosts": {
      "billingCycle": {
        "interval": 1,
        "period": "MONTHLY"
      },
      "subtotalMinor": 2999,
      "taxAmountMinor": 240,
      "taxIncluded": true,
      "totalMinor": 3239
    },
    "subtotalMinor": 12599,
    "taxAmountMinor": 1008,
    "taxEstimated": false,
    "taxIncluded": true,
    "totalMinor": 13739,
    "lineItems": [
      {
        "chargedMonthAmountMinor": 14458,
        "chargedMonths": 6,
        "description": "Premium Plan",
        "discounts": [
          {
            "amountMinor": 2999,
            "name": "First month free",
            "source": "PROMOTION_CODE",
            "validFrom": "2024-02-01",
            "validTo": "2024-02-01"
          }
        ],
        "initialInvoiceAmountMinor": 1450,
        "lineItemId": "line-item-1",
        "recurringAmountMinor": 2999,
        "recurringDiscounts": [
          {
            "amountMinor": 2999,
            "name": "First month free",
            "source": "PROMOTION_CODE",
            "validFrom": "2024-02-01",
            "validTo": "2024-02-01"
          }
        ],
        "subtotalMinor": 2999,
        "taxAmountMinor": 247,
        "taxBreakdown": [
          {
            "amountMinor": 240,
            "description": "Sales Tax",
            "rate": 8.25
          }
        ],
        "taxIncluded": true,
        "totalDiscountsMinor": 2999,
        "totalMinor": 2747
      }
    ]
  },
  "promoCode": "STUDENT2024",
  "requirements": {
    "requiresPayment": "NOT_REQUIRED",
    "requiresPaymentProfile": "NOT_REQUIRED",
    "requiresSigning": "NOT_REQUIRED"
  },
  "shipping": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "instructions": "Leave at front door",
    "msisdn": "+15551234567",
    "name": "John Doe"
  },
  "signingSessionId": "8f3b1c2d-4e5f-6789-abcd-1234567890ef",
  "state": "PENDING",
  "submittedAt": "2024-01-15T14:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "user": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "newUser": true,
    "userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "validation": {
    "errors": [
      {
        "code": "NOT_AN_INITIAL_OFFERING",
        "message": "Subscriber name is required.",
        "property": "subscriber.name",
        "reason": "not_an_initial_offering"
      }
    ],
    "isValid": false,
    "lineItemValidation": [
      {
        "errors": [
          {
            "code": "NOT_AN_INITIAL_OFFERING",
            "message": "Subscriber name is required.",
            "property": "subscriber.name",
            "reason": "not_an_initial_offering"
          }
        ],
        "isValid": false,
        "lineItemId": "line-item-1",
        "missingFields": [
          "subscriber.name",
          "sim.iccid"
        ]
      }
    ],
    "missingFields": [
      "customer",
      "billing.address"
    ]
  }
}

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

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

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

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

{
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition.",
  "message": "A precondition given in the request headers was not met."
}

{
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header.",
  "message": "Too many requests. Please slow down."
}

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

Claim order handoff

POST/orders/claim-handoff

Get the order of a handoff token. A checkout calls this operation when the user opens a checkout link. Then the checkout uses the order as the cart of the user.

A claim does not consume the token. The operation returns 404 when the token is unknown or expired. It returns 412 when the order is not PENDING or PENDING_PAYMENT.

Bodyrequiredapplication/json

handoffTokenstringrequired

The handoff token from the checkout link.

Responses

200

The order of the token

application/json

The order of the token

objectOrderHandoffClaim

The order of a handoff token.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

CONSUMER
BUSINESS

orderIdstringrequired

The order of the token.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

Auth required

Send

X-Api-Key + Bearer JWT

POST /orders/claim-handoff

curl https://apiv2.example.com/api/v2/end-user/orders/claim-handoff \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "handoffToken": "oht_f47ac10b58cc4372a5670e02b2c3d479"
}'

fetch('https://apiv2.example.com/api/v2/end-user/orders/claim-handoff', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    handoffToken: 'oht_f47ac10b58cc4372a5670e02b2c3d479'
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/end-user/orders/claim-handoff",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "handoffToken": "oht_f47ac10b58cc4372a5670e02b2c3d479"
    }
)

package main

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

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/orders/claim-handoff"

	payload := strings.NewReader(`{
  "handoffToken": "oht_f47ac10b58cc4372a5670e02b2c3d479"
}`)

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

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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))

}

{
  "customerType": "CONSUMER",
  "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

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

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

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

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

{
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition.",
  "message": "A precondition given in the request headers was not met."
}

{
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header.",
  "message": "Too many requests. Please slow down."
}

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

Get order

GET/orders/{orderId}

Retrieve a specific order by ID with all line items and current status.

Path parameters

orderIdstringrequired

The unique identifier of the order

Responses

200

Order retrieved successfully

application/json

Order retrieved successfully

objectOrder

A shopping cart for telecommunications services and products. Add line items to configure services, get pricing, and submit for fulfillment. Orders track progress from creation through completion.

billingobject

Billing information for an order.

For existing customers, we suggest you pre-fill this with the customer's billing information, however it is possible to override this at the order level.

Show child attributes

addressobject

The billing address that this order holds. It is a record of the order, and it does not change the billing address of the customer.

The platform reads it for tax only when the customer holds no billing address.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

attentionstringpersonal data

An optional line for specifying a person, department, or attention to a specific entity within an address.

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

streetstringpersonal data

The first line of the address, typically street and house number.

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2stringpersonal data

The second line of the address, typically apartment, suite, unit, building, floor, etc.

zipstringpersonal datarequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.

emailstringemailpersonal data

Billing contact email.

namestring

Billing contact name.

completedAtstringdate-time

When the order was completed.

consentsobject with string keys

The consents and acknowledgments the customer gave when placing the order, such as accepting terms of service or opting in to marketing. Keys name the consent and values record what was agreed to, so the consent can be audited later.

Show child attributes

*string

createdAtstringdate-timerequired

When the order was created.

createdEntitiesobject

Entities created as part of order fulfillment.

Show child attributes

addonsarray of any

Add-ons created during order fulfillment.

Show child attributes

addedAtstringdate-time

The date and time when the add-on was added to the subscription.

cancelledAtstringdate-time

The date and time when the add-on was canceled (if applicable).

licenseIdstring

The unique identifier of the license associated with this add-on (if applicable).

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

productOfferingGroupIdstring

The unique identifier for the product offering group.

productOfferingIdstringrequired

The unique identifier for the product offering.

referenceIdstringmax length 255

A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider.

statusenum<string>required

The status of an add-on on a subscription.

PENDING: Add-on is scheduled but not yet active
ACTIVE: Add-on is currently active and billable
CANCELLED: Add-on has been cancelled and is no longer active
EXPIRED: Add-on has expired and is no longer active

values

PENDING
ACTIVE
CANCELLED
EXPIRED

updatedAtstringdate-time

The date and time when the add-on was last updated.

createdByLineItemstringrequired

Line item ID that created this add-on.

licensesarray of any

Standalone licenses created during order fulfillment. A license that belongs to an add-on is not listed here.

Show child attributes

activatedAtstringdate

The date when the license was activated.

cancelledAtstringdate

The date when the license was canceled.

licenseIdstringrequired

The unique identifier for the license.

productOfferingIdstringrequired

The unique identifier for the product offering that the license grants.

statusenum<string>required

Current stage of the license lifecycle.

PENDING: Created but not yet activated
ACTIVE: Active and billable; the licensed feature is available
PAUSED: Temporarily stopped; the licensed feature is disabled
CANCELLED: Permanently terminated
BLOCKED: Disabled by the operator, typically for policy or payment reasons

values

PENDING
ACTIVE
PAUSED
CANCELLED
BLOCKED

subscriptionIdstring

The subscription that the license is assigned to. Absent for a license that stands alone.

typestringrequired

The kind of feature the license unlocks. Most types cover business telephony (PBX) features, such as PBX_USER_LEVEL (a PBX seat for one user), PBX_SOFTPHONE (softphone client), PBX_ROUTE_IVR, PBX_ROUTE_GROUP, PBX_ROUTE_QUEUE, and PBX_ROUTE_VOICEMAIL (call routing features), plus EXTERNAL_PRODUCT for licenses tied to products outside the telecom platform.

createdByLineItemstringrequired

Line item ID that created this license.

modificationsarray of any

Modifications applied during order fulfillment.

Show child attributes

appliedAtstringdate-time

When the modification was applied.

newProductOfferingIdstring

The product offering the entity was changed to.

targetIdstringrequired

The subscription or add-on that was modified.

typeenum<string>required

Type of modification applied.

values

SUBSCRIPTION_CHANGE
ADDON_CHANGE

createdByLineItemstringrequired

Line item ID that created this modification.

subscriptionsarray of any

Subscriptions created during order fulfillment.

Show child attributes

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

customerIdstringrequired

The unique identifier for the customer who owns this subscription.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringpersonal datarequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

productOfferingIdstringrequired

The unique identifier for the product offering associated with this subscription.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

subscriberIdstringrequired

The unique identifier for the subscriber associated with this subscription.

subscriptionIdstringrequired

The unique identifier for the subscription.

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

createdByLineItemstringrequired

Line item ID that created this subscription.

customerobject

The customer associated with this order. Includes minimal details about the customer and creation details if the customer was created during order fulfillment.

Show child attributes

customerIdstring

The unique identifier for the customer. For new customers, set once the customer has been created during fulfillment.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

CONSUMER
BUSINESS

namestringrequired

Customer name.

newCustomerbooleanrequired

Indicates if the customer was/will be created as part of order fulfillment.

expiresAtstringdate-timerequired

When the order expires if not submitted (automatically refreshed on each order update to maintain active session).

externalPaymentobject

External payment details if the order was paid outside the system.

Show child attributes

receiptDescriptionstring

Description of the external payment.

receiptUrlstringuri

URL to the external payment receipt.

receivedAtstringdate-time

When the external payment was recorded.

referencestring

Reference from the external payment system.

lineItemsarray of OrderLineItemrequired

Line items in the order.

Show child attributes

Selected by type.

activateOnDemandboolean

Whether the subscription waits for the subscriber to activate it rather than being activated on a date.

The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time.

Cannot be combined with scheduleActivationAt.

displaystring

Custom display name for the subscription. If not provided, will be auto-generated from msisdn.

extensionsobject with string keys

Additional subscription extensions fields for custom subscription types.

Show child attributes

leaseTokenstring

Token received when leasing a number. Required when an msisdn is provided from the number pool.

lineItemIdstringrequired

Unique identifier for this line item within the order.

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

msisdnstringpersonal data

The phone number for this subscription.

Leave empty to have one assigned.
When the number pool is available, you can choose a number from the pool and provide the leaseToken.
When porting a number, provide the number and porting details.

portingobject

Details needed to port in a number for this subscription.

Show child attributes

portingRequestedboolean

If true, the number is a port-in.

productOfferingIdstringrequired

The product offering to create a subscription for.

scheduleActivationAtstringdate

Date when the subscription should be activated. Cannot be combined with activateOnDemand.

simobject

The choice between eSIM and physical SIM plus related device details.

This value is optional while the order is a draft. You must give it before you submit the order.

The choice between eSIM and physical SIM plus related device details.

Show child attributes

statusenum<string>deprecated

Deprecated. Use state on the order.

An order fulfills all its line items or none of them, so every line item of an order reports what the order's own state already gives you.

The fulfillment status of an order line item.

An order fulfills all its line items or none of them. Thus the status follows the order state, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The order.updated event carries the order again when the network provisions an entity of the order.

values

PENDING
RUNNING
COMPLETED
FAILED

subscriberobject

The person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted.

Show child attributes

tempNumberboolean

Whether to use a temporary number until the porting is completed.

If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized.

Can only be used when porting in a number (i.e., when msisdn and porting details are provided).

typeenum<string>required

Identifies this line item as a new subscription purchase. Always SUBSCRIPTION.

values

SUBSCRIPTION

lineItemIdstringrequired

Unique identifier for this line item within the order.

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

parentLineItemIdstring

Reference to parent subscription line item in this same order.

Either this or subscriptionId must be provided.

productOfferingIdstringrequired

The add-on product offering to add.

scheduledAtstringdate

When to activate the add-on.

statusenum<string>deprecated

Deprecated. Use state on the order.

An order fulfills all its line items or none of them, so every line item of an order reports what the order's own state already gives you.

The fulfillment status of an order line item.

An order fulfills all its line items or none of them. Thus the status follows the order state, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The order.updated event carries the order again when the network provisions an entity of the order.

values

PENDING
RUNNING
COMPLETED
FAILED

subscriptionIdstring

An existing subscription to add the add-on to.

Either this or parentLineItemId must be provided.

typeenum<string>required

Identifies this line item as adding an add-on to a subscription. Always ADDON.

values

ADDON

lineItemIdstringrequired

Unique identifier for this line item within the order.

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

parentLineItemIdstring

Reference to parent line item in this order.

productOfferingIdstringrequired

The external product offering from the catalog.

quantityinteger>= 1

Quantity of the external product.

scheduleActivationAtstringdate

Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this date.

statusenum<string>deprecated

Deprecated. Use state on the order.

An order fulfills all its line items or none of them, so every line item of an order reports what the order's own state already gives you.

The fulfillment status of an order line item.

An order fulfills all its line items or none of them. Thus the status follows the order state, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The order.updated event carries the order again when the network provisions an entity of the order.

values

PENDING
RUNNING
COMPLETED
FAILED

typeenum<string>required

Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT.

values

EXTERNAL_PRODUCT

descriptionstring

Description of the external item.

fulfillmentWebhookstringuri

Optional webhook URL for fulfillment notifications.

lineItemIdstringrequired

Unique identifier for this line item within the order.

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

namestringrequired

Name of the external item.

parentLineItemIdstring

Reference to parent line item in this order.

priceobjectrequired

Custom pricing for the external item.

Show child attributes

quantityinteger>= 1

Quantity of the external item.

statusenum<string>deprecated

Deprecated. Use state on the order.

An order fulfills all its line items or none of them, so every line item of an order reports what the order's own state already gives you.

The fulfillment status of an order line item.

An order fulfills all its line items or none of them. Thus the status follows the order state, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The order.updated event carries the order again when the network provisions an entity of the order.

values

PENDING
RUNNING
COMPLETED
FAILED

taxationIdstring

US taxation ID for tax calculation.

typeenum<string>required

Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL.

values

EXTERNAL

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.

The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.

values

PLAN_CHANGE
SIM_CHANGE

lineItemIdstringrequired

Unique identifier for this line item within the order.

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

planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of a subscription.

Show child attributes

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

simChangeobject

The SIM card change. Give this value only for changeType SIM_CHANGE.

A change of the SIM card of a subscription. The change carries a one-time price.

Show child attributes

statusenum<string>deprecated

Deprecated. Use state on the order.

An order fulfills all its line items or none of them, so every line item of an order reports what the order's own state already gives you.

The fulfillment status of an order line item.

An order fulfills all its line items or none of them. Thus the status follows the order state, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The order.updated event carries the order again when the network provisions an entity of the order.

values

PENDING
RUNNING
COMPLETED
FAILED

subscriptionIdstringrequired

The identifier of the existing subscription that this line item changes.

typeenum<string>required

Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE.

values

SUBSCRIPTION_CHANGE

addonIdstringrequired

The identifier of the existing add-on on the subscription that this line item changes.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the add-on.

values

PLAN_CHANGE

lineItemIdstringrequired

Unique identifier for this line item within the order.

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

planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of an add-on.

Show child attributes

reasonstring

Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

statusenum<string>deprecated

Deprecated. Use state on the order.

An order fulfills all its line items or none of them, so every line item of an order reports what the order's own state already gives you.

The fulfillment status of an order line item.

An order fulfills all its line items or none of them. Thus the status follows the order state, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The order.updated event carries the order again when the network provisions an entity of the order.

values

PENDING
RUNNING
COMPLETED
FAILED

subscriptionIdstringrequired

The subscription containing the add-on to modify.

typeenum<string>required

Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE.

values

ADDON_CHANGE

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

orderIdstringrequired

Unique identifier for the order.

paymentProfileSessionIdstring

The payment profile session used to set up a payment method for this order, set when the order was submitted with one.

paymentSessionIdstring

The payment session that collected payment for this order, set when the order was submitted with one.

pricingobject

Detailed pricing information for an order including taxes and discounts.

Show child attributes

amountDueNowMinorintegerint64

What the checkout collects when the order is placed, in minor currency units. Zero for an order that is invoiced instead, such as a postpaid subscription billed each month.

This is not totalMinor, which answers what the order costs however it is paid. Use this one to decide whether to ask for a payment method.

calculatedAtstringdate-timerequired

When the pricing was last calculated.

currencystringrequired

The ISO 4217 currency code for all pricing amounts (e.g., "USD").

initialInvoiceobject

Optional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.

Show child attributes

periodobject

Period covered by the initial invoice.

Show child attributes

subtotalMinorintegerint64

First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.

taxAmountMinorintegerint64

Estimated tax on initial invoice charges, in minor currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxIncludedboolean

Whether every line in this total was priced with its tax as a part of the price.

totalMinorintegerint64

Total first invoice amount, in minor currency units.

recurringCostsobject

Expected recurring costs after the initial period. Represents the typical monthly/billing cycle charges.

A discount that ends with the periods paid for up front is not applied here.

Show child attributes

billingCycleobject

How often a recurring price is charged.

Show child attributes

subtotalMinorintegerint64

Recurring subtotal after discounts and before taxes, in minor currency units.

taxAmountMinorintegerint64

Estimated tax on recurring charges, in minor currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxIncludedboolean

Whether every line in this total was priced with its tax as a part of the price.

totalMinorintegerint64

Total estimated recurring amount, in minor currency units.

subtotalMinorintegerint64

The net of the order after discounts, in minor currency units. When taxIncluded is false, add the totalDiscountsMinor of each line item to it to get the amount before discounts. When taxIncluded is true, the discounts came off the total instead, so the amount before discounts is totalMinor plus the discounts.

taxAmountMinorintegerint64

Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.

taxEstimatedboolean

Whether the amounts leave out a tax that is not calculated yet. In a region where the tax depends on the address, the tax is calculated when the payment starts, and this field is true until then. When taxIncluded is also true, the tax is a part of totalMinor. Otherwise the tax is added to it.

taxIncludedboolean

Whether every line was priced with its tax as a part of the price. When true, the discounts came off totalMinor and taxAmountMinor is the tax inside it. When false, the discounts came off subtotalMinor and the tax was added on top. Absent when the order has no priced line yet.

totalMinorintegerint64required

Total amount due for the order, in minor currency units.

lineItemsarray of OrderLineItemPricing

Pricing breakdown per line item.

Show child attributes

chargedMonthAmountMinorintegerint64

What one month this order charges for costs, in minor currency units. Quote this next to totalMinor on an order that pays for several months at once, because recurringAmountMinor is what a month costs once the order renews, which is more. Do not divide totalMinor by chargedMonths instead: on a brand that bills calendar months, the order also charges a prorated part-month, and that part is in totalMinor but not in these two fields.

chargedMonthsinteger

How many consecutive months cost chargedMonthAmountMinor. A part-month first period is not one of them. The count stops at the first month that costs something else, which is when a discount ends part way through the months the order pays for.

descriptionstring

Description of what this line item covers.

discountsarray of OrderPricingDiscount

The individual discounts making up totalDiscountsMinor, such as a campaign, a promotion code, a price list reduction or a binding period discount. The amounts cover everything this order charges for the line, which is more than one billing period when the order pays for several at once.

Show child attributes

initialInvoiceAmountMinorintegerint64

Amount for this line item on the first invoice when different from recurring, in minor currency units.

lineItemIdstringrequired

The line item in the order that this pricing applies to.

recurringAmountMinorintegerint64

Recurring cost for this line item per billing cycle, in minor currency units.

recurringDiscountsarray of OrderPricingDiscount

The individual discounts inside recurringAmountMinor, for one billing period. Add back the ones that carry a validTo to get what the line costs after they stop.

Show child attributes

subtotalMinorintegerint64required

The net of this line item after discounts, in minor currency units. When taxIncluded is false, add totalDiscountsMinor to it to get the amount before discounts. When taxIncluded is true, the discounts came off totalMinor instead.

taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxBreakdownarray of TaxBreakdownItem

The individual taxes and regulatory fees making up taxAmountMinor, as reported by the tax authority for this line item.

Show child attributes

taxIncludedboolean

Whether the line was priced with its tax as a part of the price. When true, totalMinor is the listed price less the discounts and taxAmountMinor is the tax inside it.

totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

totalMinorintegerint64required

Amount due for this line item after taxes, fees, and discounts, in minor currency units.

promoCodestring

Promotional code applied to this order, if any.

requirementsobjectrequired

What this platform expects a checkout to collect before the order is submitted, so a client can build the right flow up front. These are declared per platform, not derived from the contents of the order.

Submit enforces what the order itself demands rather than what is declared here: an order with an amount left to collect is refused until that amount is paid, and an order that owes nothing submits without any payment reference.

Show child attributes

requiresPaymentenum<string>

Whether a checkout on this platform is expected to collect payment before submitting an order.

Whether a submission step (payment, payment profile setup, or signing) must be completed before the order can be submitted. Determined by platform configuration and the contents of the order.

NOT_REQUIRED: The step does not apply; the order can be submitted without it.
OPTIONAL: The step may be completed, but the order can be submitted without it.
REQUIRED: The step must be completed and its session reference provided when submitting the order.

values

NOT_REQUIRED
OPTIONAL
REQUIRED

requiresPaymentProfileenum<string>

Whether a checkout on this platform is expected to save a payment profile for future billing, passing its paymentProfileSessionId when submitting an order.

Whether a submission step (payment, payment profile setup, or signing) must be completed before the order can be submitted. Determined by platform configuration and the contents of the order.

NOT_REQUIRED: The step does not apply; the order can be submitted without it.
OPTIONAL: The step may be completed, but the order can be submitted without it.
REQUIRED: The step must be completed and its session reference provided when submitting the order.

values

NOT_REQUIRED
OPTIONAL
REQUIRED

requiresSigningenum<string>

Whether a checkout on this platform is expected to capture a digital signature, passing its signingSessionId when submitting an order.

Whether a submission step (payment, payment profile setup, or signing) must be completed before the order can be submitted. Determined by platform configuration and the contents of the order.

NOT_REQUIRED: The step does not apply; the order can be submitted without it.
OPTIONAL: The step may be completed, but the order can be submitted without it.
REQUIRED: The step must be completed and its session reference provided when submitting the order.

values

NOT_REQUIRED
OPTIONAL
REQUIRED

shippingobject

Shipping information for order fulfillment. Only required if the order contains shippable items.

Show child attributes

addressobjectrequired

The address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

attentionstringpersonal data

An optional line for specifying a person, department, or attention to a specific entity within an address.

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

streetstringpersonal data

The first line of the address, typically street and house number.

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2stringpersonal data

The second line of the address, typically apartment, suite, unit, building, floor, etc.

zipstringpersonal datarequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.

instructionsstring

Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.

msisdnstringphonepersonal data

Phone number the carrier can use to reach the recipient about the delivery.

namestringrequired

Full name of the person or department receiving the delivery, printed on the shipping label.

signingSessionIdstring

The signing session that captured the customer's signature for this order, set when the order was submitted with one.

stateenum<string>required

The status of an order in its lifecycle.

PENDING: Order is in cart state, can be modified
PENDING_PAYMENT: Order is locked and awaiting payment completion
SUBMITTED: Order has been submitted for processing
PENDING_APPROVAL: Order is pending approval
PROCESSING: Order is being fulfilled
COMPLETED: Order has been successfully fulfilled
CANCELLED: Order was cancelled before completion
EXPIRED: Order expired due to inactivity
FAILED: Order fulfillment failed

values

PENDING
PENDING_PAYMENT
SUBMITTED
PENDING_APPROVAL
PROCESSING
COMPLETED
CANCELLED
EXPIRED
FAILED

submittedAtstringdate-time

When the order was submitted for fulfillment.

updatedAtstringdate-timerequired

When the order was last updated.

userobject

The person who will log in and manage the services in this order.

For a new user, userId is absent until the user is actually created, which happens when payment is initiated or, for orders that collect no payment, at submission.

Show child attributes

emailstringemailpersonal data

The email the user logs in with.

namestring

The user's full name.

newUserbooleanrequired

Whether this user is created as part of fulfilling the order.

userIdstring

The user's identifier, once the user exists.

validationobjectrequired

The result of the checks that a submit makes on the order and its line items. The checks make sure that each necessary field is set, and that the customer can buy each product offering. Payment is not part of these checks.

Show child attributes

errorsarray of InlineValidationError

Order-level validation errors.

Show child attributes

codeenum<string>deprecated

Deprecated. Use reason.

A code for the problem. An order sets it when the order cannot buy the product offering of a line item:

NOT_AN_INITIAL_OFFERING: The product offering is not an initial product offering of the product catalog of the customer.
ADDON_NOT_APPLICABLE: The plan of the subscription does not take the add-on.
OFFERING_CHANGE_NOT_AVAILABLE: The subscription cannot change to the product offering.

A problem without a code is a field that is missing or not correct.

values

NOT_AN_INITIAL_OFFERING
ADDON_NOT_APPLICABLE
OFFERING_CHANGE_NOT_AVAILABLE

messagestringrequired

Validation error message.

propertystring

Property related to the error, if applicable. May be nested using dot notation (e.g., "customer.email").

reasonstring

Names the problem. 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, for example not_an_initial_offering. Your client must accept a reason that it does not know.

isValidbooleanrequired

Whether the order is valid and ready for submission.

lineItemValidationarray of object

Validation status for each line item.

Show child attributes

errorsarray of InlineValidationError

Validation errors for this line item.

Show child attributes

isValidboolean

Whether this line item is valid.

lineItemIdstring

Reference to the line item.

missingFieldsarray of string

Required fields that are still missing.

missingFieldsarray of string

Required fields that are still missing.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

Auth required

Send

X-Api-Key + Bearer JWT

GET /orders/{orderId}

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

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

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

package main

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

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID"

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

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

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

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

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

}

{
  "billing": {
    "address": {
      "city": "New York",
      "country": "US",
      "state": "NY",
      "street": "123 Main Street",
      "zip": "10001"
    },
    "email": "billing@acme.com",
    "name": "John Doe"
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
    "customerType": "BUSINESS",
    "name": "Acme Corporation",
    "newCustomer": false
  },
  "expiresAt": "2024-01-22T10:30:00Z",
  "lineItems": [
    {
      "lineItemId": "line-item-1",
      "productOfferingId": "mobile-plan-basic",
      "sim": {
        "esim": true
      },
      "status": "PENDING",
      "subscriber": {
        "address": {
          "city": "New York",
          "country": "US",
          "state": "NY",
          "street": "123 Main Street",
          "zip": "10001"
        },
        "email": "john.doe@example.com",
        "name": "John Doe"
      },
      "type": "SUBSCRIPTION"
    }
  ],
  "metadata": {
    "source": "partner-storefront"
  },
  "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "pricing": {
    "calculatedAt": "2024-01-15T10:30:00Z",
    "currency": "USD",
    "subtotalMinor": 2999,
    "taxAmountMinor": 240,
    "taxIncluded": false,
    "totalMinor": 3239
  },
  "promoCode": "SUMMER2023",
  "requirements": {
    "requiresPayment": "REQUIRED",
    "requiresPaymentProfile": "NOT_REQUIRED",
    "requiresSigning": "NOT_REQUIRED"
  },
  "state": "PENDING",
  "updatedAt": "2024-01-15T10:30:00Z",
  "validation": {
    "isValid": true
  }
}

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

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

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

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

{
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header.",
  "message": "Too many requests. Please slow down."
}

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

Auth required

Send

X-Api-Key + Bearer JWT

PUT /orders/{orderId}

curl https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID \
  --request PUT \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "billing": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "email": "billing@example.com",
    "name": "John Doe"
  },
  "consents": {
    "marketing": "true",
    "termsOfService": "true"
  },
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "metadata": {
    "propertyName": "string"
  },
  "promoCode": "STUDENT2024",
  "shipping": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "instructions": "Leave at front door",
    "msisdn": "+15551234567",
    "name": "John Doe"
  },
  "user": {
    "userId": "d47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}'

fetch('https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    billing: {
      address: {
        attention: 'John Doe',
        city: 'Natick',
        country: 'US',
        region: 'Ontario',
        state: 'CA',
        street: '500 S Main St',
        street1: 'string',
        street2: 'Apt 1',
        zip: '01701'
      },
      email: 'billing@example.com',
      name: 'John Doe'
    },
    consents: {
      marketing: 'true',
      termsOfService: 'true'
    },
    customer: {
      customerId: 'a47ac10b-58cc-4372-a567-0e02b2c3d479'
    },
    metadata: {
      propertyName: 'string'
    },
    promoCode: 'STUDENT2024',
    shipping: {
      address: {
        attention: 'John Doe',
        city: 'Natick',
        country: 'US',
        region: 'Ontario',
        state: 'CA',
        street: '500 S Main St',
        street1: 'string',
        street2: 'Apt 1',
        zip: '01701'
      },
      instructions: 'Leave at front door',
      msisdn: '+15551234567',
      name: 'John Doe'
    },
    user: {
      userId: 'd47ac10b-58cc-4372-a567-0e02b2c3d479'
    }
  })
})

requests.put(
    "https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "billing": {
        "address": {
          "attention": "John Doe",
          "city": "Natick",
          "country": "US",
          "region": "Ontario",
          "state": "CA",
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "zip": "01701"
        },
        "email": "billing@example.com",
        "name": "John Doe"
      },
      "consents": {
        "marketing": "true",
        "termsOfService": "true"
      },
      "customer": {
        "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
      },
      "metadata": {
        "propertyName": "string"
      },
      "promoCode": "STUDENT2024",
      "shipping": {
        "address": {
          "attention": "John Doe",
          "city": "Natick",
          "country": "US",
          "region": "Ontario",
          "state": "CA",
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "zip": "01701"
        },
        "instructions": "Leave at front door",
        "msisdn": "+15551234567",
        "name": "John Doe"
      },
      "user": {
        "userId": "d47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    }
)

package main

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

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID"

	payload := strings.NewReader(`{
  "billing": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "email": "billing@example.com",
    "name": "John Doe"
  },
  "consents": {
    "marketing": "true",
    "termsOfService": "true"
  },
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "metadata": {
    "propertyName": "string"
  },
  "promoCode": "STUDENT2024",
  "shipping": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "instructions": "Leave at front door",
    "msisdn": "+15551234567",
    "name": "John Doe"
  },
  "user": {
    "userId": "d47ac10b-58cc-4372-a567-0e02b2c3d479"
  }
}`)

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

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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))

}

{
  "billing": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "email": "billing@example.com",
    "name": "John Doe"
  },
  "completedAt": "2024-01-15T15:00:00Z",
  "consents": {
    "marketing": "true",
    "termsOfService": "true"
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "createdEntities": {
    "addons": [
      {
        "addedAt": "2024-01-15T10:30:00Z",
        "cancelledAt": "2024-06-30T00:00:00Z",
        "licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
        "metadata": {
          "propertyName": "string"
        },
        "productOfferingGroupId": "extra-data-packages",
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "referenceId": "telna-package-12345",
        "status": "PENDING",
        "updatedAt": "2024-01-20T09:00:00Z",
        "createdByLineItem": "h47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ],
    "licenses": [
      {
        "activatedAt": "2024-01-15",
        "cancelledAt": "2024-06-30",
        "licenseId": "c9d0e1f2-a3b4-5678-9012-def012345678",
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "status": "PENDING",
        "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "type": "PBX_USER_LEVEL",
        "createdByLineItem": "j47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ],
    "modifications": [
      {
        "appliedAt": "2024-01-15T15:00:00Z",
        "newProductOfferingId": "po_mobile_premium_plus",
        "targetId": "e8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "type": "SUBSCRIPTION_CHANGE",
        "createdByLineItem": "i47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ],
    "subscriptions": [
      {
        "activatedAt": "2024-01-15T10:30:00Z",
        "cancelledAt": "2024-06-30T00:00:00Z",
        "createdAt": "2024-01-10T08:00:00Z",
        "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d",
        "display": "(555) 123-4567",
        "msisdn": "+15551234567",
        "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "status": "PENDING",
        "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e",
        "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4",
        "type": "CELL",
        "updatedAt": "2024-01-15T10:30:00Z",
        "createdByLineItem": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      }
    ]
  },
  "customer": {
    "customerId": "b47ac10b-58cc-4372-a567-0e02b2c3d479",
    "customerType": "CONSUMER",
    "name": "John Doe",
    "newCustomer": true
  },
  "expiresAt": "2024-01-22T10:30:00Z",
  "externalPayment": {
    "receiptDescription": "Payment via external billing system",
    "receiptUrl": "https://external.example.com/receipts/123",
    "receivedAt": "2024-01-15T14:30:00Z",
    "reference": "ext-payment-ref-123"
  },
  "lineItems": [
    {
      "activateOnDemand": true,
      "display": "John Doe - Work phone",
      "extensions": {
        "propertyName": "string"
      },
      "leaseToken": "lease_8f3b1c2d4e5f6789",
      "lineItemId": "line-item-1",
      "metadata": {
        "propertyName": "string"
      },
      "msisdn": "+15551234567",
      "porting": {
        "details": {
          "accountNumber": "987654321",
          "address": {
            "attention": "John Doe",
            "city": "Natick",
            "country": "US",
            "region": "Ontario",
            "state": "CA",
            "street": "500 S Main St",
            "street1": "string",
            "street2": "Apt 1",
            "zip": "01701"
          },
          "firstName": "John",
          "lastName": "Doe",
          "passcode": "123456"
        }
      },
      "portingRequested": true,
      "productOfferingId": "mobile-plan-basic",
      "scheduleActivationAt": "2024-02-01",
      "sim": {
        "esim": true,
        "iccid": "8931440400000000000",
        "imei": "356938035643809"
      },
      "status": "PENDING",
      "subscriber": {
        "address": {
          "attention": "John Doe",
          "city": "Natick",
          "country": "US",
          "region": "Ontario",
          "state": "CA",
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "zip": "01701"
        },
        "email": "john.doe@example.com",
        "msisdn": "+15551234567",
        "name": "John Doe"
      },
      "tempNumber": true,
      "type": "SUBSCRIPTION"
    }
  ],
  "metadata": {
    "propertyName": "string"
  },
  "orderId": "order-123",
  "paymentProfileSessionId": "69321a62-f1fe-461f-8761-a19ae6587bb2",
  "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
  "pricing": {
    "amountDueNowMinor": 13739,
    "calculatedAt": "2024-01-15T10:30:00Z",
    "currency": "USD",
    "initialInvoice": {
      "period": {
        "end": "2024-01-31",
        "start": "2024-01-15"
      },
      "subtotalMinor": 1450,
      "taxAmountMinor": 116,
      "taxIncluded": true,
      "totalMinor": 1566
    },
    "recurringCosts": {
      "billingCycle": {
        "interval": 1,
        "period": "MONTHLY"
      },
      "subtotalMinor": 2999,
      "taxAmountMinor": 240,
      "taxIncluded": true,
      "totalMinor": 3239
    },
    "subtotalMinor": 12599,
    "taxAmountMinor": 1008,
    "taxEstimated": false,
    "taxIncluded": true,
    "totalMinor": 13739,
    "lineItems": [
      {
        "chargedMonthAmountMinor": 14458,
        "chargedMonths": 6,
        "description": "Premium Plan",
        "discounts": [
          {
            "amountMinor": 2999,
            "name": "First month free",
            "source": "PROMOTION_CODE",
            "validFrom": "2024-02-01",
            "validTo": "2024-02-01"
          }
        ],
        "initialInvoiceAmountMinor": 1450,
        "lineItemId": "line-item-1",
        "recurringAmountMinor": 2999,
        "recurringDiscounts": [
          {
            "amountMinor": 2999,
            "name": "First month free",
            "source": "PROMOTION_CODE",
            "validFrom": "2024-02-01",
            "validTo": "2024-02-01"
          }
        ],
        "subtotalMinor": 2999,
        "taxAmountMinor": 247,
        "taxBreakdown": [
          {
            "amountMinor": 240,
            "description": "Sales Tax",
            "rate": 8.25
          }
        ],
        "taxIncluded": true,
        "totalDiscountsMinor": 2999,
        "totalMinor": 2747
      }
    ]
  },
  "promoCode": "STUDENT2024",
  "requirements": {
    "requiresPayment": "NOT_REQUIRED",
    "requiresPaymentProfile": "NOT_REQUIRED",
    "requiresSigning": "NOT_REQUIRED"
  },
  "shipping": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "instructions": "Leave at front door",
    "msisdn": "+15551234567",
    "name": "John Doe"
  },
  "signingSessionId": "8f3b1c2d-4e5f-6789-abcd-1234567890ef",
  "state": "PENDING",
  "submittedAt": "2024-01-15T14:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "user": {
    "email": "john.doe@example.com",
    "name": "John Doe",
    "newUser": true,
    "userId": "c47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "validation": {
    "errors": [
      {
        "code": "NOT_AN_INITIAL_OFFERING",
        "message": "Subscriber name is required.",
        "property": "subscriber.name",
        "reason": "not_an_initial_offering"
      }
    ],
    "isValid": false,
    "lineItemValidation": [
      {
        "errors": [
          {
            "code": "NOT_AN_INITIAL_OFFERING",
            "message": "Subscriber name is required.",
            "property": "subscriber.name",
            "reason": "not_an_initial_offering"
          }
        ],
        "isValid": false,
        "lineItemId": "line-item-1",
        "missingFields": [
          "subscriber.name",
          "sim.iccid"
        ]
      }
    ],
    "missingFields": [
      "customer",
      "billing.address"
    ]
  }
}

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

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

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

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

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

{
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition.",
  "message": "A precondition given in the request headers was not met."
}

{
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header.",
  "message": "Too many requests. Please slow down."
}

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

Create order handoff token

POST/orders/{orderId}/handoff-token

Create a token that gives this order to a checkout. The checkout prices the order again, collects the payment, and submits the order.

The order must be PENDING or PENDING_PAYMENT. The token is valid for 1 hour. It stops when the order is no longer PENDING or PENDING_PAYMENT. Each request creates a new token, and the earlier tokens stay valid until they expire.

A person with the token can see, change, and pay for the order. Give the token only to the user that the order is for.

Path parameters

orderIdstringrequired

The unique identifier of the order

Headers

X-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

Responses

201

Handoff token created

application/json

Handoff token created

objectOrderHandoffToken

A token that gives an open order to a checkout. A person with the token can see, change, and pay for the order. Give the token only to the user that the order is for.

expiresAtstringdate-timerequired

When the token expires, 1 hour after its creation. The order has its own expiry.

handoffTokenstringrequired

The handoff token. We return it only in this response. If you lose it, create a new token.

orderIdstringrequired

The order of the token.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

Auth required

Send

X-Api-Key + Bearer JWT

POST /orders/{orderId}/handoff-token

curl https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/handoff-token \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/handoff-token', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.post(
    "https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/handoff-token",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

package main

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

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/handoff-token"

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

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

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

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

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

}

{
  "expiresAt": "2024-01-15T11:00:00Z",
  "handoffToken": "oht_f47ac10b58cc4372a5670e02b2c3d479",
  "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

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

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

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

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

{
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition.",
  "message": "A precondition given in the request headers was not met."
}

{
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header.",
  "message": "Too many requests. Please slow down."
}

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

Auth required

Send

X-Api-Key + Bearer JWT

POST /orders/{orderId}/line-items

curl https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/line-items \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "lineItem": {
    "activateOnDemand": true,
    "display": "John Doe - Work phone",
    "extensions": {
      "propertyName": "string"
    },
    "leaseToken": "lease_8f3b1c2d4e5f6789",
    "lineItemId": "line-item-1",
    "metadata": {
      "propertyName": "string"
    },
    "msisdn": "+15551234567",
    "porting": {
      "details": {
        "accountNumber": "987654321",
        "address": {
          "attention": "John Doe",
          "city": "Natick",
          "country": "US",
          "region": "Ontario",
          "state": "CA",
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "zip": "01701"
        },
        "firstName": "John",
        "lastName": "Doe",
        "passcode": "123456"
      }
    },
    "portingRequested": true,
    "productOfferingId": "mobile-plan-basic",
    "scheduleActivationAt": "2024-02-01",
    "sim": {
      "esim": true,
      "iccid": "8931440400000000000",
      "imei": "356938035643809"
    },
    "subscriber": {
      "address": {
        "attention": "John Doe",
        "city": "Natick",
        "country": "US",
        "region": "Ontario",
        "state": "CA",
        "street": "500 S Main St",
        "street1": "string",
        "street2": "Apt 1",
        "zip": "01701"
      },
      "email": "john.doe@example.com",
      "msisdn": "+15551234567",
      "name": "John Doe"
    },
    "tempNumber": true,
    "type": "SUBSCRIPTION"
  }
}'

fetch('https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/line-items', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    lineItem: {
      activateOnDemand: true,
      display: 'John Doe - Work phone',
      extensions: {
        propertyName: 'string'
      },
      leaseToken: 'lease_8f3b1c2d4e5f6789',
      lineItemId: 'line-item-1',
      metadata: {
        propertyName: 'string'
      },
      msisdn: '+15551234567',
      porting: {
        details: {
          accountNumber: '987654321',
          address: {
            attention: 'John Doe',
            city: 'Natick',
            country: 'US',
            region: 'Ontario',
            state: 'CA',
            street: '500 S Main St',
            street1: 'string',
            street2: 'Apt 1',
            zip: '01701'
          },
          firstName: 'John',
          lastName: 'Doe',
          passcode: '123456'
        }
      },
      portingRequested: true,
      productOfferingId: 'mobile-plan-basic',
      scheduleActivationAt: '2024-02-01',
      sim: {
        esim: true,
        iccid: '8931440400000000000',
        imei: '356938035643809'
      },
      subscriber: {
        address: {
          attention: 'John Doe',
          city: 'Natick',
          country: 'US',
          region: 'Ontario',
          state: 'CA',
          street: '500 S Main St',
          street1: 'string',
          street2: 'Apt 1',
          zip: '01701'
        },
        email: 'john.doe@example.com',
        msisdn: '+15551234567',
        name: 'John Doe'
      },
      tempNumber: true,
      type: 'SUBSCRIPTION'
    }
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/line-items",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "lineItem": {
        "activateOnDemand": True,
        "display": "John Doe - Work phone",
        "extensions": {
          "propertyName": "string"
        },
        "leaseToken": "lease_8f3b1c2d4e5f6789",
        "lineItemId": "line-item-1",
        "metadata": {
          "propertyName": "string"
        },
        "msisdn": "+15551234567",
        "porting": {
          "details": {
            "accountNumber": "987654321",
            "address": {
              "attention": "John Doe",
              "city": "Natick",
              "country": "US",
              "region": "Ontario",
              "state": "CA",
              "street": "500 S Main St",
              "street1": "string",
              "street2": "Apt 1",
              "zip": "01701"
            },
            "firstName": "John",
            "lastName": "Doe",
            "passcode": "123456"
          }
        },
        "portingRequested": True,
        "productOfferingId": "mobile-plan-basic",
        "scheduleActivationAt": "2024-02-01",
        "sim": {
          "esim": True,
          "iccid": "8931440400000000000",
          "imei": "356938035643809"
        },
        "subscriber": {
          "address": {
            "attention": "John Doe",
            "city": "Natick",
            "country": "US",
            "region": "Ontario",
            "state": "CA",
            "street": "500 S Main St",
            "street1": "string",
            "street2": "Apt 1",
            "zip": "01701"
          },
          "email": "john.doe@example.com",
          "msisdn": "+15551234567",
          "name": "John Doe"
        },
        "tempNumber": True,
        "type": "SUBSCRIPTION"
      }
    }
)

package main

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

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/line-items"

	payload := strings.NewReader(`{
  "lineItem": {
    "activateOnDemand": true,
    "display": "John Doe - Work phone",
    "extensions": {
      "propertyName": "string"
    },
    "leaseToken": "lease_8f3b1c2d4e5f6789",
    "lineItemId": "line-item-1",
    "metadata": {
      "propertyName": "string"
    },
    "msisdn": "+15551234567",
    "porting": {
      "details": {
        "accountNumber": "987654321",
        "address": {
          "attention": "John Doe",
          "city": "Natick",
          "country": "US",
          "region": "Ontario",
          "state": "CA",
          "street": "500 S Main St",
          "street1": "string",
          "street2": "Apt 1",
          "zip": "01701"
        },
        "firstName": "John",
        "lastName": "Doe",
        "passcode": "123456"
      }
    },
    "portingRequested": true,
    "productOfferingId": "mobile-plan-basic",
    "scheduleActivationAt": "2024-02-01",
    "sim": {
      "esim": true,
      "iccid": "8931440400000000000",
      "imei": "356938035643809"
    },
    "subscriber": {
      "address": {
        "attention": "John Doe",
        "city": "Natick",
        "country": "US",
        "region": "Ontario",
        "state": "CA",
        "street": "500 S Main St",
        "street1": "string",
        "street2": "Apt 1",
        "zip": "01701"
      },
      "email": "john.doe@example.com",
      "msisdn": "+15551234567",
      "name": "John Doe"
    },
    "tempNumber": true,
    "type": "SUBSCRIPTION"
  }
}`)

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

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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))

}

{
  "activateOnDemand": true,
  "display": "John Doe - Work phone",
  "extensions": {
    "propertyName": "string"
  },
  "leaseToken": "lease_8f3b1c2d4e5f6789",
  "lineItemId": "line-item-1",
  "metadata": {
    "propertyName": "string"
  },
  "msisdn": "+15551234567",
  "porting": {
    "details": {
      "accountNumber": "987654321",
      "address": {
        "attention": "John Doe",
        "city": "Natick",
        "country": "US",
        "region": "Ontario",
        "state": "CA",
        "street": "500 S Main St",
        "street1": "string",
        "street2": "Apt 1",
        "zip": "01701"
      },
      "firstName": "John",
      "lastName": "Doe",
      "passcode": "123456"
    }
  },
  "portingRequested": true,
  "productOfferingId": "mobile-plan-basic",
  "scheduleActivationAt": "2024-02-01",
  "sim": {
    "esim": true,
    "iccid": "8931440400000000000",
    "imei": "356938035643809"
  },
  "status": "PENDING",
  "subscriber": {
    "address": {
      "attention": "John Doe",
      "city": "Natick",
      "country": "US",
      "region": "Ontario",
      "state": "CA",
      "street": "500 S Main St",
      "street1": "string",
      "street2": "Apt 1",
      "zip": "01701"
    },
    "email": "john.doe@example.com",
    "msisdn": "+15551234567",
    "name": "John Doe"
  },
  "tempNumber": true,
  "type": "SUBSCRIPTION"
}

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

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

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

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

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

{
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition.",
  "message": "A precondition given in the request headers was not met."
}

{
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header.",
  "message": "Too many requests. Please slow down."
}

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

Remove line item

DELETE/orders/{orderId}/line-items/{lineItemId}

Remove a line item from an order. Order must be in PENDING status.

Path parameters

orderIdstringrequired

The unique identifier of the order

lineItemIdstringrequired

The unique identifier of the line item

Headers

X-Idempotency-Keystringmax length 256

A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.

Modified requests with the same idempotency keys are rejected with a 409 Conflict status code.

Responses

204

Line item removed successfully

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

Auth required

Send

X-Api-Key + Bearer JWT

DELETE /orders/{orderId}/line-items/{lineItemId}

curl https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/line-items/LINE_ITEM_ID \
  --request DELETE \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/line-items/LINE_ITEM_ID', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.delete(
    "https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/line-items/LINE_ITEM_ID",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

package main

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

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/line-items/LINE_ITEM_ID"

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

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

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

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

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

}

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

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

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

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

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

{
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition.",
  "message": "A precondition given in the request headers was not met."
}

{
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header.",
  "message": "Too many requests. Please slow down."
}

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

Submit order

POST/orders/{orderId}/submit

Submit an order for fulfillment. Requires payment, signing, or card capture, depending on the setup. Only orders in the PENDING state can be submitted. An order paying through a payment session or payment link is in PENDING_PAYMENT and is submitted automatically once the payment succeeds — poll the order or subscribe to the order.statusChanged webhook instead of calling this endpoint.

Path parameters

orderIdstringrequired

The unique identifier of the order

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.

BodySubmitOrderRequestrequiredapplication/json

Request to submit an order for fulfillment.

Depending on the order's requirements, payment intent, saved payment profile, or signing reference may be required.

In a fully managed flow, the order may be auto-submitted on successfully fulfilling all requirements (e.g. successful payment or signing).

externalPaymentobject

Details of an external payment made outside the system. When provided, the order is considered paid and will bypass internal payment requirements.

Cannot be used together with paymentSessionId.

Show child attributes

receiptDescriptionstring

Optional human-readable description of the payment.

receiptUrlstringuri

Optional URL to a receipt or confirmation page for the payment.

referencestringmin length 1required

Reference or identifier from the external payment system.

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

paymentProfileSessionIdstring

Reference to completed payment profile session for zero-total orders requiring payment method setup.

paymentSessionIdstring

Reference to completed payment session for orders requiring payment collection.

signingSessionIdstring

Reference to completed signing session.

Responses

200

Order submitted successfully

application/json

Order submitted successfully

objectOrder

A shopping cart for telecommunications services and products. Add line items to configure services, get pricing, and submit for fulfillment. Orders track progress from creation through completion.

billingobject

Billing information for an order.

For existing customers, we suggest you pre-fill this with the customer's billing information, however it is possible to override this at the order level.

Show child attributes

addressobject

The billing address that this order holds. It is a record of the order, and it does not change the billing address of the customer.

The platform reads it for tax only when the customer holds no billing address.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

attentionstringpersonal data

An optional line for specifying a person, department, or attention to a specific entity within an address.

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

streetstringpersonal data

The first line of the address, typically street and house number.

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2stringpersonal data

The second line of the address, typically apartment, suite, unit, building, floor, etc.

zipstringpersonal datarequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.

emailstringemailpersonal data

Billing contact email.

namestring

Billing contact name.

completedAtstringdate-time

When the order was completed.

consentsobject with string keys

The consents and acknowledgments the customer gave when placing the order, such as accepting terms of service or opting in to marketing. Keys name the consent and values record what was agreed to, so the consent can be audited later.

Show child attributes

*string

createdAtstringdate-timerequired

When the order was created.

createdEntitiesobject

Entities created as part of order fulfillment.

Show child attributes

addonsarray of any

Add-ons created during order fulfillment.

Show child attributes

addedAtstringdate-time

The date and time when the add-on was added to the subscription.

cancelledAtstringdate-time

The date and time when the add-on was canceled (if applicable).

licenseIdstring

The unique identifier of the license associated with this add-on (if applicable).

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

productOfferingGroupIdstring

The unique identifier for the product offering group.

productOfferingIdstringrequired

The unique identifier for the product offering.

referenceIdstringmax length 255

A reference identifier provided by API clients or upstream provider integrations to identify this subscription add-on in their own systems. Unique per tenant when set. Use this field to look up add-ons by your external identifier (for example a provider-side package ID). Typically populated by a workflow once the add-on has been provisioned with the underlying network provider.

statusenum<string>required

The status of an add-on on a subscription.

PENDING: Add-on is scheduled but not yet active
ACTIVE: Add-on is currently active and billable
CANCELLED: Add-on has been cancelled and is no longer active
EXPIRED: Add-on has expired and is no longer active

values

PENDING
ACTIVE
CANCELLED
EXPIRED

updatedAtstringdate-time

The date and time when the add-on was last updated.

createdByLineItemstringrequired

Line item ID that created this add-on.

licensesarray of any

Standalone licenses created during order fulfillment. A license that belongs to an add-on is not listed here.

Show child attributes

activatedAtstringdate

The date when the license was activated.

cancelledAtstringdate

The date when the license was canceled.

licenseIdstringrequired

The unique identifier for the license.

productOfferingIdstringrequired

The unique identifier for the product offering that the license grants.

statusenum<string>required

Current stage of the license lifecycle.

PENDING: Created but not yet activated
ACTIVE: Active and billable; the licensed feature is available
PAUSED: Temporarily stopped; the licensed feature is disabled
CANCELLED: Permanently terminated
BLOCKED: Disabled by the operator, typically for policy or payment reasons

values

PENDING
ACTIVE
PAUSED
CANCELLED
BLOCKED

subscriptionIdstring

The subscription that the license is assigned to. Absent for a license that stands alone.

typestringrequired

The kind of feature the license unlocks. Most types cover business telephony (PBX) features, such as PBX_USER_LEVEL (a PBX seat for one user), PBX_SOFTPHONE (softphone client), PBX_ROUTE_IVR, PBX_ROUTE_GROUP, PBX_ROUTE_QUEUE, and PBX_ROUTE_VOICEMAIL (call routing features), plus EXTERNAL_PRODUCT for licenses tied to products outside the telecom platform.

createdByLineItemstringrequired

Line item ID that created this license.

modificationsarray of any

Modifications applied during order fulfillment.

Show child attributes

appliedAtstringdate-time

When the modification was applied.

newProductOfferingIdstring

The product offering the entity was changed to.

targetIdstringrequired

The subscription or add-on that was modified.

typeenum<string>required

Type of modification applied.

values

SUBSCRIPTION_CHANGE
ADDON_CHANGE

createdByLineItemstringrequired

Line item ID that created this modification.

subscriptionsarray of any

Subscriptions created during order fulfillment.

Show child attributes

activatedAtstringdate-time

The date and time when the subscription was activated. Absent until the subscription has been activated.

cancelledAtstringdate-time

The date and time when the subscription was cancelled (if applicable).

createdAtstringdate-timerequired

The date and time when the subscription was created.

customerIdstringrequired

The unique identifier for the customer who owns this subscription.

displaystringrequired

Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.

msisdnstringpersonal datarequired

The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.

productOfferingIdstringrequired

The unique identifier for the product offering associated with this subscription.

statusenum<string>required

Current stage of the subscription lifecycle.

PENDING: Created but not yet activated in the network
ACTIVATED: Active and billable; service is available
BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations
CANCELLED: Permanently terminated
PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled
SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled

values

PENDING
ACTIVATED
BLOCKED
CANCELLED
PAUSED
SUSPENDED

subscriberIdstringrequired

The unique identifier for the subscriber associated with this subscription.

subscriptionIdstringrequired

The unique identifier for the subscription.

typestringrequired

The kind of telecommunications service the subscription provides.

Common values include CELL (mobile voice/SMS/data), DATA (data-only SIM), MBB (mobile broadband), M2M (machine-to-machine/IoT), and TRAVEL_ESIM (travel eSIM for international roaming). Determined by the product offering the subscription was created with.

updatedAtstringdate-timerequired

The date and time when the subscription was last updated.

createdByLineItemstringrequired

Line item ID that created this subscription.

customerobject

The customer associated with this order. Includes minimal details about the customer and creation details if the customer was created during order fulfillment.

Show child attributes

customerIdstring

The unique identifier for the customer. For new customers, set once the customer has been created during fulfillment.

customerTypeenum<string>required

Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply.

values

CONSUMER
BUSINESS

namestringrequired

Customer name.

newCustomerbooleanrequired

Indicates if the customer was/will be created as part of order fulfillment.

expiresAtstringdate-timerequired

When the order expires if not submitted (automatically refreshed on each order update to maintain active session).

externalPaymentobject

External payment details if the order was paid outside the system.

Show child attributes

receiptDescriptionstring

Description of the external payment.

receiptUrlstringuri

URL to the external payment receipt.

receivedAtstringdate-time

When the external payment was recorded.

referencestring

Reference from the external payment system.

lineItemsarray of OrderLineItemrequired

Line items in the order.

Show child attributes

Selected by type.

activateOnDemandboolean

Whether the subscription waits for the subscriber to activate it rather than being activated on a date.

The subscription is created when the order is fulfilled and stays pending until the subscriber requests activation; only then is it activated in the network. Use this when the subscriber decides when their service starts, for example a SIM shipped ahead of time.

Cannot be combined with scheduleActivationAt.

displaystring

Custom display name for the subscription. If not provided, will be auto-generated from msisdn.

extensionsobject with string keys

Additional subscription extensions fields for custom subscription types.

Show child attributes

leaseTokenstring

Token received when leasing a number. Required when an msisdn is provided from the number pool.

lineItemIdstringrequired

Unique identifier for this line item within the order.

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

msisdnstringpersonal data

The phone number for this subscription.

Leave empty to have one assigned.
When the number pool is available, you can choose a number from the pool and provide the leaseToken.
When porting a number, provide the number and porting details.

portingobject

Details needed to port in a number for this subscription.

Show child attributes

portingRequestedboolean

If true, the number is a port-in.

productOfferingIdstringrequired

The product offering to create a subscription for.

scheduleActivationAtstringdate

Date when the subscription should be activated. Cannot be combined with activateOnDemand.

simobject

The choice between eSIM and physical SIM plus related device details.

This value is optional while the order is a draft. You must give it before you submit the order.

The choice between eSIM and physical SIM plus related device details.

Show child attributes

statusenum<string>deprecated

Deprecated. Use state on the order.

An order fulfills all its line items or none of them, so every line item of an order reports what the order's own state already gives you.

The fulfillment status of an order line item.

An order fulfills all its line items or none of them. Thus the status follows the order state, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The order.updated event carries the order again when the network provisions an entity of the order.

values

PENDING
RUNNING
COMPLETED
FAILED

subscriberobject

The person who will use this subscription, including their name, contact details, and service address. Optional while the order is a draft, but must be provided before the order can be submitted.

Show child attributes

tempNumberboolean

Whether to use a temporary number until the porting is completed.

If true, a temporary number will be assigned and activated as soon as possible until the porting is finalized.

Can only be used when porting in a number (i.e., when msisdn and porting details are provided).

typeenum<string>required

Identifies this line item as a new subscription purchase. Always SUBSCRIPTION.

values

SUBSCRIPTION

lineItemIdstringrequired

Unique identifier for this line item within the order.

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

parentLineItemIdstring

Reference to parent subscription line item in this same order.

Either this or subscriptionId must be provided.

productOfferingIdstringrequired

The add-on product offering to add.

scheduledAtstringdate

When to activate the add-on.

statusenum<string>deprecated

Deprecated. Use state on the order.

An order fulfills all its line items or none of them, so every line item of an order reports what the order's own state already gives you.

The fulfillment status of an order line item.

An order fulfills all its line items or none of them. Thus the status follows the order state, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The order.updated event carries the order again when the network provisions an entity of the order.

values

PENDING
RUNNING
COMPLETED
FAILED

subscriptionIdstring

An existing subscription to add the add-on to.

Either this or parentLineItemId must be provided.

typeenum<string>required

Identifies this line item as adding an add-on to a subscription. Always ADDON.

values

ADDON

lineItemIdstringrequired

Unique identifier for this line item within the order.

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

parentLineItemIdstring

Reference to parent line item in this order.

productOfferingIdstringrequired

The external product offering from the catalog.

quantityinteger>= 1

Quantity of the external product.

scheduleActivationAtstringdate

Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this date.

statusenum<string>deprecated

Deprecated. Use state on the order.

An order fulfills all its line items or none of them, so every line item of an order reports what the order's own state already gives you.

The fulfillment status of an order line item.

An order fulfills all its line items or none of them. Thus the status follows the order state, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The order.updated event carries the order again when the network provisions an entity of the order.

values

PENDING
RUNNING
COMPLETED
FAILED

typeenum<string>required

Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT.

values

EXTERNAL_PRODUCT

descriptionstring

Description of the external item.

fulfillmentWebhookstringuri

Optional webhook URL for fulfillment notifications.

lineItemIdstringrequired

Unique identifier for this line item within the order.

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

namestringrequired

Name of the external item.

parentLineItemIdstring

Reference to parent line item in this order.

priceobjectrequired

Custom pricing for the external item.

Show child attributes

quantityinteger>= 1

Quantity of the external item.

statusenum<string>deprecated

Deprecated. Use state on the order.

An order fulfills all its line items or none of them, so every line item of an order reports what the order's own state already gives you.

The fulfillment status of an order line item.

An order fulfills all its line items or none of them. Thus the status follows the order state, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The order.updated event carries the order again when the network provisions an entity of the order.

values

PENDING
RUNNING
COMPLETED
FAILED

taxationIdstring

US taxation ID for tax calculation.

typeenum<string>required

Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL.

values

EXTERNAL

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.

The category of the product offering must agree with this value. The platform refuses a SIM card offering under PLAN_CHANGE, and a plan offering under SIM_CHANGE.

values

PLAN_CHANGE
SIM_CHANGE

lineItemIdstringrequired

Unique identifier for this line item within the order.

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

planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of a subscription.

Show child attributes

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

simChangeobject

The SIM card change. Give this value only for changeType SIM_CHANGE.

A change of the SIM card of a subscription. The change carries a one-time price.

Show child attributes

statusenum<string>deprecated

Deprecated. Use state on the order.

An order fulfills all its line items or none of them, so every line item of an order reports what the order's own state already gives you.

The fulfillment status of an order line item.

An order fulfills all its line items or none of them. Thus the status follows the order state, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The order.updated event carries the order again when the network provisions an entity of the order.

values

PENDING
RUNNING
COMPLETED
FAILED

subscriptionIdstringrequired

The identifier of the existing subscription that this line item changes.

typeenum<string>required

Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE.

values

SUBSCRIPTION_CHANGE

addonIdstringrequired

The identifier of the existing add-on on the subscription that this line item changes.

changeTypeenum<string>required

What this line item changes.

PLAN_CHANGE changes the product of the add-on.

values

PLAN_CHANGE

lineItemIdstringrequired

Unique identifier for this line item within the order.

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

planChangeobject

The plan change. Give this value only for changeType PLAN_CHANGE.

A change of the product of an add-on.

Show child attributes

reasonstring

Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up.

scheduleDatestringdate

Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.

statusenum<string>deprecated

Deprecated. Use state on the order.

An order fulfills all its line items or none of them, so every line item of an order reports what the order's own state already gives you.

The fulfillment status of an order line item.

An order fulfills all its line items or none of them. Thus the status follows the order state, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The order.updated event carries the order again when the network provisions an entity of the order.

values

PENDING
RUNNING
COMPLETED
FAILED

subscriptionIdstringrequired

The subscription containing the add-on to modify.

typeenum<string>required

Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE.

values

ADDON_CHANGE

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

orderIdstringrequired

Unique identifier for the order.

paymentProfileSessionIdstring

The payment profile session used to set up a payment method for this order, set when the order was submitted with one.

paymentSessionIdstring

The payment session that collected payment for this order, set when the order was submitted with one.

pricingobject

Detailed pricing information for an order including taxes and discounts.

Show child attributes

amountDueNowMinorintegerint64

What the checkout collects when the order is placed, in minor currency units. Zero for an order that is invoiced instead, such as a postpaid subscription billed each month.

This is not totalMinor, which answers what the order costs however it is paid. Use this one to decide whether to ask for a payment method.

calculatedAtstringdate-timerequired

When the pricing was last calculated.

currencystringrequired

The ISO 4217 currency code for all pricing amounts (e.g., "USD").

initialInvoiceobject

Optional breakdown for the first invoice when different from recurring. Used for prorated charges, first-month adjustments, etc.

Show child attributes

periodobject

Period covered by the initial invoice.

Show child attributes

subtotalMinorintegerint64

First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.

taxAmountMinorintegerint64

Estimated tax on initial invoice charges, in minor currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxIncludedboolean

Whether every line in this total was priced with its tax as a part of the price.

totalMinorintegerint64

Total first invoice amount, in minor currency units.

recurringCostsobject

Expected recurring costs after the initial period. Represents the typical monthly/billing cycle charges.

A discount that ends with the periods paid for up front is not applied here.

Show child attributes

billingCycleobject

How often a recurring price is charged.

Show child attributes

subtotalMinorintegerint64

Recurring subtotal after discounts and before taxes, in minor currency units.

taxAmountMinorintegerint64

Estimated tax on recurring charges, in minor currency units.

Only calculated in certain regions. In the US, taxes are calculated at the time of invoicing and are not estimated here.

taxIncludedboolean

Whether every line in this total was priced with its tax as a part of the price.

totalMinorintegerint64

Total estimated recurring amount, in minor currency units.

subtotalMinorintegerint64

The net of the order after discounts, in minor currency units. When taxIncluded is false, add the totalDiscountsMinor of each line item to it to get the amount before discounts. When taxIncluded is true, the discounts came off the total instead, so the amount before discounts is totalMinor plus the discounts.

taxAmountMinorintegerint64

Tax amount for the order, in minor currency units. Set to 0 for orders that will be invoiced separately.

taxEstimatedboolean

Whether the amounts leave out a tax that is not calculated yet. In a region where the tax depends on the address, the tax is calculated when the payment starts, and this field is true until then. When taxIncluded is also true, the tax is a part of totalMinor. Otherwise the tax is added to it.

taxIncludedboolean

Whether every line was priced with its tax as a part of the price. When true, the discounts came off totalMinor and taxAmountMinor is the tax inside it. When false, the discounts came off subtotalMinor and the tax was added on top. Absent when the order has no priced line yet.

totalMinorintegerint64required

Total amount due for the order, in minor currency units.

lineItemsarray of OrderLineItemPricing

Pricing breakdown per line item.

Show child attributes

chargedMonthAmountMinorintegerint64

What one month this order charges for costs, in minor currency units. Quote this next to totalMinor on an order that pays for several months at once, because recurringAmountMinor is what a month costs once the order renews, which is more. Do not divide totalMinor by chargedMonths instead: on a brand that bills calendar months, the order also charges a prorated part-month, and that part is in totalMinor but not in these two fields.

chargedMonthsinteger

How many consecutive months cost chargedMonthAmountMinor. A part-month first period is not one of them. The count stops at the first month that costs something else, which is when a discount ends part way through the months the order pays for.

descriptionstring

Description of what this line item covers.

discountsarray of OrderPricingDiscount

The individual discounts making up totalDiscountsMinor, such as a campaign, a promotion code, a price list reduction or a binding period discount. The amounts cover everything this order charges for the line, which is more than one billing period when the order pays for several at once.

Show child attributes

initialInvoiceAmountMinorintegerint64

Amount for this line item on the first invoice when different from recurring, in minor currency units.

lineItemIdstringrequired

The line item in the order that this pricing applies to.

recurringAmountMinorintegerint64

Recurring cost for this line item per billing cycle, in minor currency units.

recurringDiscountsarray of OrderPricingDiscount

The individual discounts inside recurringAmountMinor, for one billing period. Add back the ones that carry a validTo to get what the line costs after they stop.

Show child attributes

subtotalMinorintegerint64required

The net of this line item after discounts, in minor currency units. When taxIncluded is false, add totalDiscountsMinor to it to get the amount before discounts. When taxIncluded is true, the discounts came off totalMinor instead.

taxAmountMinorintegerint64

Total taxes for this line item, in minor currency units.

taxBreakdownarray of TaxBreakdownItem

The individual taxes and regulatory fees making up taxAmountMinor, as reported by the tax authority for this line item.

Show child attributes

taxIncludedboolean

Whether the line was priced with its tax as a part of the price. When true, totalMinor is the listed price less the discounts and taxAmountMinor is the tax inside it.

totalDiscountsMinorintegerint64

Total discounts for this line item, in minor currency units.

totalMinorintegerint64required

Amount due for this line item after taxes, fees, and discounts, in minor currency units.

promoCodestring

Promotional code applied to this order, if any.

requirementsobjectrequired

What this platform expects a checkout to collect before the order is submitted, so a client can build the right flow up front. These are declared per platform, not derived from the contents of the order.

Submit enforces what the order itself demands rather than what is declared here: an order with an amount left to collect is refused until that amount is paid, and an order that owes nothing submits without any payment reference.

Show child attributes

requiresPaymentenum<string>

Whether a checkout on this platform is expected to collect payment before submitting an order.

Whether a submission step (payment, payment profile setup, or signing) must be completed before the order can be submitted. Determined by platform configuration and the contents of the order.

NOT_REQUIRED: The step does not apply; the order can be submitted without it.
OPTIONAL: The step may be completed, but the order can be submitted without it.
REQUIRED: The step must be completed and its session reference provided when submitting the order.

values

NOT_REQUIRED
OPTIONAL
REQUIRED

requiresPaymentProfileenum<string>

Whether a checkout on this platform is expected to save a payment profile for future billing, passing its paymentProfileSessionId when submitting an order.

Whether a submission step (payment, payment profile setup, or signing) must be completed before the order can be submitted. Determined by platform configuration and the contents of the order.

NOT_REQUIRED: The step does not apply; the order can be submitted without it.
OPTIONAL: The step may be completed, but the order can be submitted without it.
REQUIRED: The step must be completed and its session reference provided when submitting the order.

values

NOT_REQUIRED
OPTIONAL
REQUIRED

requiresSigningenum<string>

Whether a checkout on this platform is expected to capture a digital signature, passing its signingSessionId when submitting an order.

Whether a submission step (payment, payment profile setup, or signing) must be completed before the order can be submitted. Determined by platform configuration and the contents of the order.

NOT_REQUIRED: The step does not apply; the order can be submitted without it.
OPTIONAL: The step may be completed, but the order can be submitted without it.
REQUIRED: The step must be completed and its session reference provided when submitting the order.

values

NOT_REQUIRED
OPTIONAL
REQUIRED

shippingobject

Shipping information for order fulfillment. Only required if the order contains shippable items.

Show child attributes

addressobjectrequired

The address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer.

A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.

Show child attributes

attentionstringpersonal data

An optional line for specifying a person, department, or attention to a specific entity within an address.

citystringrequired

The city or municipality of the address.

countrystringpattern ^[A-Z]{2}$required

The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).

regionstring

A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).

statestring

For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).

streetstringpersonal data

The first line of the address, typically street and house number.

street1stringpersonal datadeprecatedrequired

Deprecated. Use street instead.

The first line of the address, typically street and house number.

street2stringpersonal data

The second line of the address, typically apartment, suite, unit, building, floor, etc.

zipstringpersonal datarequired

The zip code of the address.

Depending on the country, this may be referred to as a postal code or postcode.

A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused.

instructionsstring

Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.

msisdnstringphonepersonal data

Phone number the carrier can use to reach the recipient about the delivery.

namestringrequired

Full name of the person or department receiving the delivery, printed on the shipping label.

signingSessionIdstring

The signing session that captured the customer's signature for this order, set when the order was submitted with one.

stateenum<string>required

The status of an order in its lifecycle.

PENDING: Order is in cart state, can be modified
PENDING_PAYMENT: Order is locked and awaiting payment completion
SUBMITTED: Order has been submitted for processing
PENDING_APPROVAL: Order is pending approval
PROCESSING: Order is being fulfilled
COMPLETED: Order has been successfully fulfilled
CANCELLED: Order was cancelled before completion
EXPIRED: Order expired due to inactivity
FAILED: Order fulfillment failed

values

PENDING
PENDING_PAYMENT
SUBMITTED
PENDING_APPROVAL
PROCESSING
COMPLETED
CANCELLED
EXPIRED
FAILED

submittedAtstringdate-time

When the order was submitted for fulfillment.

updatedAtstringdate-timerequired

When the order was last updated.

userobject

The person who will log in and manage the services in this order.

For a new user, userId is absent until the user is actually created, which happens when payment is initiated or, for orders that collect no payment, at submission.

Show child attributes

emailstringemailpersonal data

The email the user logs in with.

namestring

The user's full name.

newUserbooleanrequired

Whether this user is created as part of fulfilling the order.

userIdstring

The user's identifier, once the user exists.

validationobjectrequired

The result of the checks that a submit makes on the order and its line items. The checks make sure that each necessary field is set, and that the customer can buy each product offering. Payment is not part of these checks.

Show child attributes

errorsarray of InlineValidationError

Order-level validation errors.

Show child attributes

codeenum<string>deprecated

Deprecated. Use reason.

A code for the problem. An order sets it when the order cannot buy the product offering of a line item:

NOT_AN_INITIAL_OFFERING: The product offering is not an initial product offering of the product catalog of the customer.
ADDON_NOT_APPLICABLE: The plan of the subscription does not take the add-on.
OFFERING_CHANGE_NOT_AVAILABLE: The subscription cannot change to the product offering.

A problem without a code is a field that is missing or not correct.

values

NOT_AN_INITIAL_OFFERING
ADDON_NOT_APPLICABLE
OFFERING_CHANGE_NOT_AVAILABLE

messagestringrequired

Validation error message.

propertystring

Property related to the error, if applicable. May be nested using dot notation (e.g., "customer.email").

reasonstring

Names the problem. 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, for example not_an_initial_offering. Your client must accept a reason that it does not know.

isValidbooleanrequired

Whether the order is valid and ready for submission.

lineItemValidationarray of object

Validation status for each line item.

Show child attributes

errorsarray of InlineValidationError

Validation errors for this line item.

Show child attributes

isValidboolean

Whether this line item is valid.

lineItemIdstring

Reference to the line item.

missingFieldsarray of string

Required fields that are still missing.

missingFieldsarray of string

Required fields that are still missing.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

429

Too many requests have been sent in a given amount of time.

application/json

Too many requests have been sent in a given amount of time.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

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.

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.

detailsarray of object

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

Show child attributes

codestringdeprecatedrequired

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

messagestringrequired

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

propertystring

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

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.

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

domainstring

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

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.

hintstring

A hint to help resolve the error.

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.

messagestringrequired

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

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.

retryableboolean

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

spanIdstring

The span within the trace that failed.

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.

Auth required

Send

X-Api-Key + Bearer JWT

POST /orders/{orderId}/submit

curl https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/submit \
  --request POST \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901"
}'

fetch('https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/submit', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    Authorization: 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    paymentSessionId: 'd2e3f4a5-b6c7-8901-2345-012345678901'
  })
})

requests.post(
    "https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/submit",
    headers={
      "X-Api-Key": "YOUR_API_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN",
      "Content-Type": "application/json"
    },
    json={
      "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901"
    }
)

package main

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

func main() {
	requestUrl := "https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/submit"

	payload := strings.NewReader(`{
  "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901"
}`)

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

	req.Header.Add("X-Api-Key", "YOUR_API_KEY")
	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	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))

}

{
  "billing": {
    "address": {
      "city": "New York",
      "country": "US",
      "state": "NY",
      "street": "123 Main Street",
      "zip": "10001"
    },
    "email": "billing@acme.com",
    "name": "John Doe"
  },
  "createdAt": "2024-01-15T10:00:00Z",
  "customer": {
    "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479",
    "customerType": "BUSINESS",
    "name": "Acme Corporation",
    "newCustomer": false
  },
  "expiresAt": "2024-01-22T10:30:00Z",
  "lineItems": [
    {
      "lineItemId": "line-item-1",
      "productOfferingId": "mobile-plan-basic",
      "sim": {
        "esim": true
      },
      "status": "RUNNING",
      "subscriber": {
        "address": {
          "city": "New York",
          "country": "US",
          "state": "NY",
          "street": "123 Main Street",
          "zip": "10001"
        },
        "email": "john.doe@example.com",
        "name": "John Doe"
      },
      "type": "SUBSCRIPTION"
    }
  ],
  "metadata": {
    "source": "partner-storefront"
  },
  "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901",
  "pricing": {
    "calculatedAt": "2024-01-15T10:30:00Z",
    "currency": "USD",
    "subtotalMinor": 2999,
    "taxAmountMinor": 240,
    "taxIncluded": false,
    "totalMinor": 3239
  },
  "promoCode": "SUMMER2023",
  "requirements": {
    "requiresPayment": "REQUIRED",
    "requiresPaymentProfile": "NOT_REQUIRED",
    "requiresSigning": "NOT_REQUIRED"
  },
  "state": "PROCESSING",
  "submittedAt": "2024-01-15T14:30:00Z",
  "updatedAt": "2024-01-15T14:30:00Z",
  "validation": {
    "isValid": true
  }
}

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

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

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

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

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

{
  "code": "precondition_failed",
  "hint": "Fetch the current resource and retry with an up-to-date precondition.",
  "message": "A precondition given in the request headers was not met."
}

{
  "code": "too_many_requests",
  "hint": "Retry after the number of seconds indicated in the Retry-After header.",
  "message": "Too many requests. Please slow down."
}

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

Orders

List orders

Query parameters

Responses

Create order

Headers

BodyCreateOrderRequestrequiredapplication/json

Responses

Claim order handoff

Bodyrequiredapplication/json

Responses

Get order

Path parameters

Responses

Update order

Path parameters

BodyUpdateOrderRequestrequiredapplication/json

Responses

Create order handoff token

Path parameters

Headers

Responses

Add line item

Path parameters

Headers

BodyAddLineItemRequestrequiredapplication/json

Responses

Remove line item

Path parameters

Headers

Responses

Submit order

Path parameters

Headers

BodySubmitOrderRequestrequiredapplication/json

Responses

Query parameters

Responses

Headers

Body·CreateOrderRequestrequiredapplication/json

Responses

Bodyrequiredapplication/json

Responses

Path parameters

Responses

Path parameters

Body·UpdateOrderRequestrequiredapplication/json

Responses

Path parameters

Headers

Responses

Path parameters

Headers

Body·AddLineItemRequestrequiredapplication/json

Responses

Path parameters

Headers

Responses

Path parameters

Headers

Body·SubmitOrderRequestrequiredapplication/json

Responses

BodyCreateOrderRequestrequiredapplication/json

BodyUpdateOrderRequestrequiredapplication/json

BodyAddLineItemRequestrequiredapplication/json

BodySubmitOrderRequestrequiredapplication/json