--- title: Orders description: Manage orders and line items. --- # Orders Manage orders and line items. ## [POST /orders](/api-reference/orders#tag/orders/POST/orders) Create order Create a new order with initial configuration. Orders can be created with minimal information and progressively configured. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `object` - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — The type of customer this order is for. This scopes the order to the customer type's context, which affects which product offerings can be ordered, who is authorized to place the order, and what is required to submit it. For logged in orders, this must match the customer's type. - `user` (`one of`, optional) — The person who will log in and manage the services in this order. Provide a userId for a returning user, let the authenticated user be resolved from their token, or provide details to create a new user together with the order. - One of: `ExistingUserById` - `userId` (`string`, required, example d47ac10b-58cc-4372-a567-0e02b2c3d479) — The user's internal ID. - One of: `AuthenticatedUser` - `authenticatedUser` (`boolean`, required, example true) — Always true. - One of: `OrderUserReference_NewUser` - `name` (`string`, required, example John Doe) — The user's full name. - `email` (`string`, required, email, example john.doe@example.com) — The email the user logs in with and receives order confirmations on. - `identity` (`string`, optional, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `msisdn` (`string`, optional, phone, example +15551234567) — The user's phone number. - `address` (`object`, optional, deprecated) — Deprecated. The platform does not store this address. A user is a sign-in identity, and the address of the person belongs to the customer that pays. Give the address in `customer` instead. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `customer` (`one of`, optional) — Reference to a customer of the order. Provide a customerId (which accepts both internal UUIDs and external reference IDs), let the authenticated user's own customer be resolved, or provide details to create a new customer. - One of: `ExistingCustomerById` - `customerId` (`string`, required, example a47ac10b-58cc-4372-a567-0e02b2c3d479) — The customer's internal ID (UUID) or external reference ID. Both formats are accepted and will be resolved automatically. - One of: `AuthenticatedCustomer` - `authenticatedCustomer` (`boolean`, required, example true) — Always true. - One of: `OrderCustomerReference_NewCustomer` - `referenceId` (`string`, optional, max length 255, example crm-customer-12345) — Optional reference ID to assign to the new customer. If a customer with this referenceId already exists, that customer will be used instead of creating a new one. - `name` (`string`, required, example Acme Corporation) — Name for the new customer. - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `identity` (`string`, optional, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `preferredLocale` (`string`, optional, example en-US) — Preferred locale for the customer. - `contact` (`object`, optional) — Contact information for the new customer. - `email` (`string`, optional, email, example billing@acme.com) — Primary contact email for the new customer. - `msisdn` (`string`, optional, phone, example +15551234567) — Primary contact phone number for the new customer. - `billing` (`object`, optional) — Billing configuration and payment preferences for the new customer. - `method` (`enum`, required, one of E_INVOICE, EMAIL_INVOICE, PAPER_INVOICE) — How invoices should be delivered to the customer. — How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address. - `email` (`string`, optional, email, example billing@acme.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `address` (`object`, optional) — The billing address for the customer. Used for invoicing and tax calculation. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `currency` (`string`, required, example USD) — The currency for customer billing and payments. — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `autoPay` (`boolean`, optional, default false, example true) — Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set to have any effect. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `billing` (`object`, optional) — 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. - `name` (`string`, optional, example John Doe) — Billing contact name. - `email` (`string`, optional, email, example billing@example.com) — Billing contact email. - `address` (`object`, optional) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `shipping` (`object`, optional) — Shipping information for order fulfillment. Only required if the order contains shippable items. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `msisdn` (`string`, optional, phone, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `instructions` (`string`, optional, example Leave at front door) — Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference. - `lineItems` (`array of OrderLineItem`, optional) — Initial line items for the order (can be empty). - One of: `SUBSCRIPTION` - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `msisdn` (`string`, optional, example +15551234567) — 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. - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `tempNumber` (`boolean`, optional, example true) — 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). - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `porting` (`object`, optional) — Details needed to port in a number for this subscription. - `details` (`one of`, required) — Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers. - One of: `PortingDetailsUS` - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `subscriber` (`object`, optional) — 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. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `email` (`string`, optional, email, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `address` (`object`, optional) — The address of the subscriber. Depending on local regulations, this may be required for certain subscriptions. In the US, this is the E911 address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `sim` (`object`, optional) — 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. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `activateOnDemand` (`boolean`, optional, example true) — 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. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON` - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL_PRODUCT` - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example external-device-iphone15) — The external product offering from the catalog. - `quantity` (`integer`, optional, >= 1, example 2) — Quantity of the external product. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this date. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL` - `type` (`enum`, required, one of EXTERNAL) — Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the order. - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `price` (`object`, required) — Custom pricing for the external item. - `amountMinor` (`integer`, required, int64, example 9999) — The price per unit, in minor units of the currency (e.g., 9999 = $99.99 when the currency is USD). - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in. Must match the order currency. - `quantity` (`integer`, optional, >= 1, example 1) — Quantity of the external item. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `SUBSCRIPTION_CHANGE` - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `changeType` (`enum`, required, one of PLAN_CHANGE, SIM_CHANGE, example PLAN_CHANGE) — 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. - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of a subscription. - `productOfferingId` (`string`, required, example mobile-plan-premium) — The plan offering to change to. The platform refuses an offering in the SIM card category. - `simChange` (`object`, optional) — 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. - `productOfferingId` (`string`, required, example sim-card-replacement) — The SIM card offering to change to. The offering must be in the SIM card category. - `sim` (`object`, optional) — The SIM card of the change. The product offering decides the SIM type. The platform refuses an esim value that disagrees with the offering. Give the value only to state what you expect. The iccid is optional. Give it to name a card you already hold. Without it the SIM pool supplies the card, the same way it does for a new subscription. — The choice between eSIM and physical SIM plus related device details. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON_CHANGE` - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `addonId` (`string`, required, example addon-123) — The identifier of the existing add-on on the subscription that this line item changes. - `changeType` (`enum`, required, one of PLAN_CHANGE, example PLAN_CHANGE) — What this line item changes. PLAN_CHANGE changes the product of the add-on. - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of an add-on. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on offering to change to. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `reason` (`string`, optional, example Customer upgrade request) — Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - `consents` (`object with string keys`, optional, example {"termsOfService":"true","marketing":"true"}) — 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. - `*` (`string`, optional) - `promoCode` (`string`, optional, example SUMMER2023) — Promo code to apply to the order. Rejected with `internalCode` 4119 when no promotion has that code, or when it is outside its validity period. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) ### Responses #### 201 Order created successfully Type: [Order](/api-reference/models.md#models/Order) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/orders \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "customerType": "BUSINESS", "customer": { "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479" }, "billing": { "name": "John Doe", "email": "billing@acme.com", "address": { "street": "123 Main Street", "city": "New York", "zip": "10001", "state": "NY", "country": "US" } }, "lineItems": [ { "type": "SUBSCRIPTION", "lineItemId": "line-item-1", "productOfferingId": "mobile-plan-basic", "sim": { "esim": true }, "subscriber": { "name": "John Doe", "email": "john.doe@example.com" } } ], "promoCode": "SUMMER2023", "metadata": { "source": "partner-storefront" } }' ``` ## [GET /orders](/api-reference/orders#tag/orders/GET/orders) List orders List orders with optional filtering and pagination. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Query parameters - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. - `state` (`enum`, optional, one of PENDING, PENDING_PAYMENT, SUBMITTED, PENDING_APPROVAL, PROCESSING, COMPLETED, CANCELLED, EXPIRED, FAILED) — 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 - `userId` (`string`, optional) — Filter by user ID - `customerId` (`string`, optional) — 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. - `expiresAfter` (`string`, optional, date-time) — Filter orders expiring after this date - `expiresBefore` (`string`, optional, date-time) — Filter orders expiring before this date ### Responses #### 200 Orders retrieved successfully Type: `object` - `items` (`array of OrderListItem`, required) - `orderId` (`string`, required, example ce0539b4-ec57-4709-b72e-47892586d05a) — The unique identifier for the order. - `state` (`enum`, required, one of PENDING, PENDING_PAYMENT, SUBMITTED, PENDING_APPROVAL, PROCESSING, COMPLETED, CANCELLED, EXPIRED, FAILED) — 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 - `customer` (`object`, optional) — Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization. - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — The unique identifier for the customer. Use it with the customer endpoints to fetch full details. - `name` (`string`, required, example John Doe) — The customer's display name — the company name for business customers or the person's full name for consumers. - `pricing` (`object`, optional) — Summary pricing information for the order. - `totalMinor` (`integer`, required, int64, example 13739) — Final order total including all taxes and fees, in minor currency units. - `currency` (`string`, required, example USD) — ISO 4217 currency code. - `validationStatus` (`enum`, optional, one of VALID, INVALID, PENDING_VALIDATION) — Whether the order is complete and ready for submission. Fetch the full order to see which fields are missing or invalid. - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the order was created. - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the order was last updated. - `expiresAt` (`string`, optional, date-time, example 2024-01-22T10:30:00Z) — When the order will expire if not submitted. - `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/orders \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [GET /orders/{orderId}](/api-reference/orders#tag/orders/GET/orders/{orderId}) Get order Retrieve a specific order by ID with all line items and current status. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ### Responses #### 200 Order retrieved successfully Type: [Order](/api-reference/models.md#models/Order) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [PUT /orders/{orderId}](/api-reference/orders#tag/orders/PUT/orders/{orderId}) Update order Update order details (excluding line items). Order must be in PENDING status. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ### Request body (required) Type: `object` - `user` (`one of`, optional) — The person who will log in and manage the services in this order. Provide a userId for a returning user, let the authenticated user be resolved from their token, or provide details to create a new user together with the order. - One of: `ExistingUserById` - `userId` (`string`, required, example d47ac10b-58cc-4372-a567-0e02b2c3d479) — The user's internal ID. - One of: `AuthenticatedUser` - `authenticatedUser` (`boolean`, required, example true) — Always true. - One of: `OrderUserReference_NewUser` - `name` (`string`, required, example John Doe) — The user's full name. - `email` (`string`, required, email, example john.doe@example.com) — The email the user logs in with and receives order confirmations on. - `identity` (`string`, optional, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `msisdn` (`string`, optional, phone, example +15551234567) — The user's phone number. - `address` (`object`, optional, deprecated) — Deprecated. The platform does not store this address. A user is a sign-in identity, and the address of the person belongs to the customer that pays. Give the address in `customer` instead. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `customer` (`one of`, optional) — Reference to a customer of the order. Provide a customerId (which accepts both internal UUIDs and external reference IDs), let the authenticated user's own customer be resolved, or provide details to create a new customer. - One of: `ExistingCustomerById` - `customerId` (`string`, required, example a47ac10b-58cc-4372-a567-0e02b2c3d479) — The customer's internal ID (UUID) or external reference ID. Both formats are accepted and will be resolved automatically. - One of: `AuthenticatedCustomer` - `authenticatedCustomer` (`boolean`, required, example true) — Always true. - One of: `OrderCustomerReference_NewCustomer` - `referenceId` (`string`, optional, max length 255, example crm-customer-12345) — Optional reference ID to assign to the new customer. If a customer with this referenceId already exists, that customer will be used instead of creating a new one. - `name` (`string`, required, example Acme Corporation) — Name for the new customer. - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `identity` (`string`, optional, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `preferredLocale` (`string`, optional, example en-US) — Preferred locale for the customer. - `contact` (`object`, optional) — Contact information for the new customer. - `email` (`string`, optional, email, example billing@acme.com) — Primary contact email for the new customer. - `msisdn` (`string`, optional, phone, example +15551234567) — Primary contact phone number for the new customer. - `billing` (`object`, optional) — Billing configuration and payment preferences for the new customer. - `method` (`enum`, required, one of E_INVOICE, EMAIL_INVOICE, PAPER_INVOICE) — How invoices should be delivered to the customer. — How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address. - `email` (`string`, optional, email, example billing@acme.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `address` (`object`, optional) — The billing address for the customer. Used for invoicing and tax calculation. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `currency` (`string`, required, example USD) — The currency for customer billing and payments. — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `autoPay` (`boolean`, optional, default false, example true) — Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set to have any effect. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `billing` (`object`, optional) — 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. - `name` (`string`, optional, example John Doe) — Billing contact name. - `email` (`string`, optional, email, example billing@example.com) — Billing contact email. - `address` (`object`, optional) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `shipping` (`object`, optional) — Shipping information for order fulfillment. Only required if the order contains shippable items. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `msisdn` (`string`, optional, phone, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `instructions` (`string`, optional, example Leave at front door) — Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference. - `consents` (`object with string keys`, optional, example {"termsOfService":"true","marketing":"true"}) — 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. - `*` (`string`, optional) - `promoCode` (`string`, optional, example STUDENT2024) — Promo code to apply to the order, or an empty string to remove the one it holds. Rejected with `internalCode` 4119 when no promotion has that code, or when it is outside its validity period. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) ### Responses #### 200 Order updated successfully Type: [Order](/api-reference/models.md#models/Order) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID \ --request PUT \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "user": { "userId": "d47ac10b-58cc-4372-a567-0e02b2c3d479" }, "customer": { "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479" }, "billing": { "name": "John Doe", "email": "billing@example.com", "address": { "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } }, "shipping": { "name": "John Doe", "msisdn": "+15551234567", "address": { "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" }, "instructions": "Leave at front door" }, "consents": { "termsOfService": "true", "marketing": "true" }, "promoCode": "STUDENT2024", "metadata": { "propertyName": "string" } }' ``` ## [POST /orders/{orderId}/line-items](/api-reference/orders#tag/orders/POST/orders/{orderId}/line-items) Add line item Add a new line item to an order. Order must be in PENDING status. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `object` - `lineItem` (`one of`, required) — A line item in an order representing a billable action or service. - One of: `SUBSCRIPTION` - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `msisdn` (`string`, optional, example +15551234567) — 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. - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `tempNumber` (`boolean`, optional, example true) — 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). - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `porting` (`object`, optional) — Details needed to port in a number for this subscription. - `details` (`one of`, required) — Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers. - One of: `PortingDetailsUS` - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `subscriber` (`object`, optional) — 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. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `email` (`string`, optional, email, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `address` (`object`, optional) — The address of the subscriber. Depending on local regulations, this may be required for certain subscriptions. In the US, this is the E911 address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `sim` (`object`, optional) — 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. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `activateOnDemand` (`boolean`, optional, example true) — 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. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON` - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL_PRODUCT` - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example external-device-iphone15) — The external product offering from the catalog. - `quantity` (`integer`, optional, >= 1, example 2) — Quantity of the external product. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this date. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL` - `type` (`enum`, required, one of EXTERNAL) — Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the order. - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `price` (`object`, required) — Custom pricing for the external item. - `amountMinor` (`integer`, required, int64, example 9999) — The price per unit, in minor units of the currency (e.g., 9999 = $99.99 when the currency is USD). - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in. Must match the order currency. - `quantity` (`integer`, optional, >= 1, example 1) — Quantity of the external item. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `SUBSCRIPTION_CHANGE` - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `changeType` (`enum`, required, one of PLAN_CHANGE, SIM_CHANGE, example PLAN_CHANGE) — 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. - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of a subscription. - `productOfferingId` (`string`, required, example mobile-plan-premium) — The plan offering to change to. The platform refuses an offering in the SIM card category. - `simChange` (`object`, optional) — 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. - `productOfferingId` (`string`, required, example sim-card-replacement) — The SIM card offering to change to. The offering must be in the SIM card category. - `sim` (`object`, optional) — The SIM card of the change. The product offering decides the SIM type. The platform refuses an esim value that disagrees with the offering. Give the value only to state what you expect. The iccid is optional. Give it to name a card you already hold. Without it the SIM pool supplies the card, the same way it does for a new subscription. — The choice between eSIM and physical SIM plus related device details. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON_CHANGE` - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `addonId` (`string`, required, example addon-123) — The identifier of the existing add-on on the subscription that this line item changes. - `changeType` (`enum`, required, one of PLAN_CHANGE, example PLAN_CHANGE) — What this line item changes. PLAN_CHANGE changes the product of the add-on. - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of an add-on. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on offering to change to. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `reason` (`string`, optional, example Customer upgrade request) — Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. ### Responses #### 201 Line item added successfully Type: [OrderLineItem](/api-reference/models.md#models/OrderLineItem) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "lineItem": { "type": "SUBSCRIPTION", "lineItemId": "line-item-1", "productOfferingId": "mobile-plan-basic", "msisdn": "+15551234567", "leaseToken": "lease_8f3b1c2d4e5f6789", "tempNumber": true, "portingRequested": true, "porting": { "details": { "accountNumber": "987654321", "passcode": "123456", "firstName": "John", "lastName": "Doe", "address": { "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } } }, "extensions": { "propertyName": "string" }, "display": "John Doe - Work phone", "subscriber": { "name": "John Doe", "email": "john.doe@example.com", "msisdn": "+15551234567", "address": { "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } }, "sim": { "esim": true, "imei": "356938035643809", "iccid": "8931440400000000000" }, "scheduleActivationAt": "2024-02-01", "activateOnDemand": true, "metadata": { "propertyName": "string" } } }' ``` ## [PUT /orders/{orderId}/line-items/{lineItemId}](/api-reference/orders#tag/orders/PUT/orders/{orderId}/line-items/{lineItemId}) Update line item Update a line item configuration. Order must be in PENDING status. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `orderId` (`string`, required) — The unique identifier of the order - `lineItemId` (`string`, required) — The unique identifier of the line item ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `object` - `lineItem` (`one of`, required) — A line item in an order representing a billable action or service. - One of: `SUBSCRIPTION` - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `msisdn` (`string`, optional, example +15551234567) — 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. - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `tempNumber` (`boolean`, optional, example true) — 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). - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `porting` (`object`, optional) — Details needed to port in a number for this subscription. - `details` (`one of`, required) — Ownership and account information the carriers need to approve a number transfer. The required information varies by country: provide US details for US numbers and Swedish details for Swedish numbers. - One of: `PortingDetailsUS` - `accountNumber` (`string`, optional, example 987654321) — The account number with the current provider. If not provided here, must be provided in the future for activation on-demand. - `passcode` (`string`, optional, example 123456) — The passcode or PIN associated with the account at the current provider, often called a Number Transfer PIN or port-out PIN. Most US carriers require the account holder to generate this in their account settings before the number can be released. If not provided here, must be provided in the future for activation on-demand. - `firstName` (`string`, required, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, example Doe) — The last name of the account holder at the current provider. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - One of: `PortingDetailsSweden` - `identity` (`string`, required, example 199001011234) — The identity of the number's current owner as registered with the losing carrier: a Swedish personal identity number (personnummer) for individuals, or a company registration number (organisationsnummer) for businesses. The transfer is rejected if this does not match the losing carrier's records. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `subscriber` (`object`, optional) — 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. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `email` (`string`, optional, email, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `address` (`object`, optional) — The address of the subscriber. Depending on local regulations, this may be required for certain subscriptions. In the US, this is the E911 address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `sim` (`object`, optional) — 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. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `activateOnDemand` (`boolean`, optional, example true) — 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. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON` - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL_PRODUCT` - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the order. - `productOfferingId` (`string`, required, example external-device-iphone15) — The external product offering from the catalog. - `quantity` (`integer`, optional, >= 1, example 2) — Quantity of the external product. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this date. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `EXTERNAL` - `type` (`enum`, required, one of EXTERNAL) — Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the order. - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `price` (`object`, required) — Custom pricing for the external item. - `amountMinor` (`integer`, required, int64, example 9999) — The price per unit, in minor units of the currency (e.g., 9999 = $99.99 when the currency is USD). - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in. Must match the order currency. - `quantity` (`integer`, optional, >= 1, example 1) — Quantity of the external item. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `SUBSCRIPTION_CHANGE` - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `changeType` (`enum`, required, one of PLAN_CHANGE, SIM_CHANGE, example PLAN_CHANGE) — 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. - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of a subscription. - `productOfferingId` (`string`, required, example mobile-plan-premium) — The plan offering to change to. The platform refuses an offering in the SIM card category. - `simChange` (`object`, optional) — 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. - `productOfferingId` (`string`, required, example sim-card-replacement) — The SIM card offering to change to. The offering must be in the SIM card category. - `sim` (`object`, optional) — The SIM card of the change. The product offering decides the SIM type. The platform refuses an esim value that disagrees with the offering. Give the value only to state what you expect. The iccid is optional. Give it to name a card you already hold. Without it the SIM pool supplies the card, the same way it does for a new subscription. — The choice between eSIM and physical SIM plus related device details. - `esim` (`boolean`, required, example true) — Whether this line item uses eSIM technology. - `imei` (`string`, optional, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `iccid` (`string`, optional, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. - One of: `ADDON_CHANGE` - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `addonId` (`string`, required, example addon-123) — The identifier of the existing add-on on the subscription that this line item changes. - `changeType` (`enum`, required, one of PLAN_CHANGE, example PLAN_CHANGE) — What this line item changes. PLAN_CHANGE changes the product of the add-on. - `planChange` (`object`, optional) — The plan change. Give this value only for changeType PLAN_CHANGE. — A change of the product of an add-on. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on offering to change to. - `scheduleDate` (`string`, optional, date, example 2024-02-01) — Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it. - `reason` (`string`, optional, example Customer upgrade request) — Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) - `status` (`enum`, optional, deprecated, one of PENDING, RUNNING, COMPLETED, FAILED) — 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 current fulfillment status of an order line item. Resolved dynamically from the underlying entity (subscription action, activation). An order can complete while individual line items remain RUNNING or FAILED; failures on one line item do not block completion of the rest of the order. ### Responses #### 200 Line item updated successfully Type: [OrderLineItem](/api-reference/models.md#models/OrderLineItem) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items/LINE_ITEM_ID \ --request PUT \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "lineItem": { "type": "SUBSCRIPTION", "lineItemId": "line-item-1", "productOfferingId": "mobile-plan-basic", "msisdn": "+15551234567", "leaseToken": "lease_8f3b1c2d4e5f6789", "tempNumber": true, "portingRequested": true, "porting": { "details": { "accountNumber": "987654321", "passcode": "123456", "firstName": "John", "lastName": "Doe", "address": { "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } } }, "extensions": { "propertyName": "string" }, "display": "John Doe - Work phone", "subscriber": { "name": "John Doe", "email": "john.doe@example.com", "msisdn": "+15551234567", "address": { "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "city": "Natick", "zip": "01701", "country": "US", "state": "CA", "region": "Ontario", "attention": "John Doe" } }, "sim": { "esim": true, "imei": "356938035643809", "iccid": "8931440400000000000" }, "scheduleActivationAt": "2024-02-01", "activateOnDemand": true, "metadata": { "propertyName": "string" } } }' ``` ## [DELETE /orders/{orderId}/line-items/{lineItemId}](/api-reference/orders#tag/orders/DELETE/orders/{orderId}/line-items/{lineItemId}) Remove line item Remove a line item from an order. Order must be in PENDING status. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `orderId` (`string`, required) — The unique identifier of the order - `lineItemId` (`string`, required) — The unique identifier of the line item ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Responses #### 204 Line item removed successfully #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID/line-items/LINE_ITEM_ID \ --request DELETE \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [POST /orders/{orderId}/submit](/api-reference/orders#tag/orders/POST/orders/{orderId}/submit) Submit order 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. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `object` - `paymentSessionId` (`string`, optional, example a1b2c3d4-e5f6-7890-1234-56789abcdef0) — Reference to completed payment session for orders requiring payment collection. - `paymentProfileSessionId` (`string`, optional, example b2c3d4e5-f6a7-8901-2345-6789abcdef01) — Reference to completed payment profile session for zero-total orders requiring payment method setup. - `signingSessionId` (`string`, optional, example c3d4e5f6-a7b8-9012-3456-789abcdef012) — Reference to completed signing session. - `externalPayment` (`object`, optional) — 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. - `reference` (`string`, required, min length 1, example ext-payment-ref-123) — Reference or identifier from the external payment system. - `receiptDescription` (`string`, optional, example Payment via external billing system) — Optional human-readable description of the payment. - `receiptUrl` (`string`, optional, uri, example https://external.example.com/receipts/123) — Optional URL to a receipt or confirmation page for the payment. - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) ### Responses #### 200 Order submitted successfully Type: [Order](/api-reference/models.md#models/Order) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID/submit \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901" }' ``` ## [POST /orders/{orderId}/cancel](/api-reference/orders#tag/orders/POST/orders/{orderId}/cancel) Cancel order Cancel an order before it has been submitted. Only orders in PENDING status can be canceled. This prevents the order from being submitted and cleans up any reserved resources. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ### Request body (optional) Type: `object` - `metadata` (`object with string keys`, optional) — 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. - `*` (`string`, optional) ### Responses #### 200 Order canceled successfully Type: [Order](/api-reference/models.md#models/Order) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID/cancel \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "metadata": { "propertyName": "string" } }' ``` ## [POST /orders/{orderId}/approve](/api-reference/orders#tag/orders/POST/orders/{orderId}/approve) Approve order Approve an order that requires admin or manager approval. Only orders in PENDING_APPROVAL status can be approved. The approving user must have the appropriate role for the approval type required by the order. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ### Request body (optional) Type: `object` - `comment` (`string`, optional, max length 1000, example Approved after reviewing customer credit check) — Optional comment explaining the approval decision. ### Responses #### 200 Order approved successfully Type: [Order](/api-reference/models.md#models/Order) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID/approve \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "comment": "Approved after reviewing customer credit check" }' ``` ## [POST /orders/{orderId}/handoff-token](/api-reference/orders#tag/orders/POST/orders/{orderId}/handoff-token) Create order handoff token Mint a short-lived token that lets a checkout pick up this draft order, so an order built over the API can be configured further and paid by the customer in a storefront checkout. The order must still be open (PENDING or PENDING_PAYMENT). The token expires on its own, and it stops working as soon as the order is no longer open. Anyone holding the token can view and complete the order, so pass it only to the person the order is for. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Responses #### 201 Handoff token created Type: [OrderHandoffToken](/api-reference/models.md#models/OrderHandoffToken) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/orders/ORDER_ID/handoff-token \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [POST /orders/claim-handoff](/api-reference/orders#tag/orders/POST/orders/claim-handoff) Claim order handoff Resolve a handoff token to the order it hands off. A checkout calls this with the token it received and then continues the order under its own session. Fails when the token is unknown or expired, or when the order is no longer open. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Request body (required) Type: `object` - `handoffToken` (`string`, required, example oht_f47ac10b58cc4372a5670e02b2c3d479) — The handoff token to resolve. ### Responses #### 200 The order the token hands off Type: [OrderHandoffClaim](/api-reference/models.md#models/OrderHandoffClaim) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/orders/claim-handoff \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "handoffToken": "oht_f47ac10b58cc4372a5670e02b2c3d479" }' ```