--- title: Orders description: The orders that the user makes and submits. --- # Orders The orders that the user makes and submits. ## [GET /orders](/end-user-api/orders#tag/orders/GET/orders) List orders List orders with optional filtering and pagination. Authentication: X-Api-Key + Bearer JWT ### 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) - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the order was created. - `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. - `expiresAt` (`string`, optional, date-time, example 2024-01-22T10:30:00Z) — When the order will expire if not submitted. - `orderId` (`string`, required, example ce0539b4-ec57-4709-b72e-47892586d05a) — The unique identifier for the order. - `pricing` (`object`, optional) — Summary pricing information for the order. - `currency` (`string`, required, example USD) — ISO 4217 currency code. - `totalMinor` (`integer`, required, int64, example 13739) — Final order total including all taxes and fees, in minor currency units. - `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 - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:30:00Z) — When the order was last updated. - `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. - `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](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/orders \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` ## [POST /orders](/end-user-api/orders#tag/orders/POST/orders) Create order Create a new order for a customer of the user that makes the request. The order takes its user from the bearer token, so the request gives no user. A user can manage more than one customer, so the request names the customer that the order is for. This is the only difference from the same operation on the Platform API. Authentication: X-Api-Key + Bearer JWT ### 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` - `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. - `address` (`object`, optional) — The billing address that this order holds. It is a record of the order, and it does not change the billing address of the customer. The platform reads it for tax only when the customer holds no billing address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `attention` (`string`, optional, personal data, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `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). - `street` (`string`, optional, personal data, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, personal data, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, personal data, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `zip` (`string`, required, personal data, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused. - `email` (`string`, optional, email, personal data, example billing@example.com) — Billing contact email. - `name` (`string`, optional, example John Doe) — Billing contact name. - `consents` (`object with string keys`, optional, example {"marketing":"true","termsOfService":"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) - `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` - `billing` (`object`, optional) — Billing configuration and payment preferences for the new customer. - `address` (`object`, optional) — The billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge. A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `attention` (`string`, optional, personal data, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `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). - `street` (`string`, optional, personal data, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, personal data, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, personal data, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `zip` (`string`, required, personal data, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused. - `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. - `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. - `email` (`string`, optional, email, personal data, example billing@acme.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `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. - `contact` (`object`, optional) — Contact information for the new customer. - `email` (`string`, optional, email, personal data, example billing@acme.com) — Primary contact email for the new customer. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Primary contact phone number 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, personal data, 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. - `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) - `name` (`string`, required, example Acme Corporation) — Name for the new customer. - `preferredLocale` (`string`, optional, example en-US) — Preferred locale for the customer. - `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. - `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. - `lineItems` (`array of OrderLineItem`, optional) — Initial line items for the order (can be empty). - One of: `SUBSCRIPTION` - `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. - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the 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) - `msisdn` (`string`, optional, personal data, 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. - `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. - `address` (`object`, required) — The address that the current provider holds for the account holder. The provider compares it with its own record before it releases the number. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `attention` (`string`, optional, personal data, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `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). - `street` (`string`, optional, personal data, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, personal data, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, personal data, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `zip` (`string`, required, personal data, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused. - `firstName` (`string`, required, personal data, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, personal data, example Doe) — The last name of the account holder at the current provider. - `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. - One of: `PortingDetailsSweden` - `identity` (`string`, required, personal data, 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. - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `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. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `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 fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `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. - `address` (`object`, optional) — The address where the subscriber uses this subscription. In the US, this is the E911 address. Give it only when it is different from the billing address of the customer. The subscription then holds it as its service address. A subscription with no address of its own is served at the billing address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `attention` (`string`, optional, personal data, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `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). - `street` (`string`, optional, personal data, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, personal data, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, personal data, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `zip` (`string`, required, personal data, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused. - `email` (`string`, optional, email, personal data, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `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). - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - One of: `ADDON` - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the 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) - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `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 fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - One of: `EXTERNAL_PRODUCT` - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the 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) - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this 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. - `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. - `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 fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - One of: `EXTERNAL` - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the 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) - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `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. - `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 fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `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. - One of: `SUBSCRIPTION_CHANGE` - `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. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the 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) - `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. - `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. - `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. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `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 fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - One of: `ADDON_CHANGE` - `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. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the 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) - `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. - `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. - `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. - `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 fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. - `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) - `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. - `shipping` (`object`, optional) — Shipping information for order fulfillment. Only required if the order contains shippable items. - `address` (`object`, required) — The address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `attention` (`string`, optional, personal data, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `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). - `street` (`string`, optional, personal data, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, personal data, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, personal data, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `zip` (`string`, required, personal data, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused. - `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. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. ### Responses #### 201 Order created successfully Type: [Order](/end-user-api/models.md#models/Order) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/end-user-api/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/end-user-api/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/orders \ --request POST \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "billing": { "address": { "attention": "John Doe", "city": "Natick", "country": "US", "region": "Ontario", "state": "CA", "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "zip": "01701" }, "email": "billing@example.com", "name": "John Doe" }, "consents": { "marketing": "true", "termsOfService": "true" }, "customer": { "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479" }, "customerType": "CONSUMER", "lineItems": [ { "activateOnDemand": true, "display": "John Doe - Work phone", "extensions": { "propertyName": "string" }, "leaseToken": "lease_8f3b1c2d4e5f6789", "lineItemId": "line-item-1", "metadata": { "propertyName": "string" }, "msisdn": "+15551234567", "porting": { "details": { "accountNumber": "987654321", "address": { "attention": "John Doe", "city": "Natick", "country": "US", "region": "Ontario", "state": "CA", "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "zip": "01701" }, "firstName": "John", "lastName": "Doe", "passcode": "123456" } }, "portingRequested": true, "productOfferingId": "mobile-plan-basic", "scheduleActivationAt": "2024-02-01", "sim": { "esim": true, "iccid": "8931440400000000000", "imei": "356938035643809" }, "subscriber": { "address": { "attention": "John Doe", "city": "Natick", "country": "US", "region": "Ontario", "state": "CA", "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "zip": "01701" }, "email": "john.doe@example.com", "msisdn": "+15551234567", "name": "John Doe" }, "tempNumber": true, "type": "SUBSCRIPTION" } ], "metadata": { "propertyName": "string" }, "promoCode": "SUMMER2023", "shipping": { "address": { "attention": "John Doe", "city": "Natick", "country": "US", "region": "Ontario", "state": "CA", "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "zip": "01701" }, "instructions": "Leave at front door", "msisdn": "+15551234567", "name": "John Doe" } }' ``` ## [POST /orders/claim-handoff](/end-user-api/orders#tag/orders/POST/orders/claim-handoff) Claim order handoff Get the order of a handoff token. A checkout calls this operation when the user opens a checkout link. Then the checkout uses the order as the cart of the user. A claim does not consume the token. The operation returns 404 when the token is unknown or expired. It returns 412 when the order is not PENDING or PENDING_PAYMENT. Authentication: X-Api-Key + Bearer JWT ### Request body (required) Type: `object` - `handoffToken` (`string`, required, example oht_f47ac10b58cc4372a5670e02b2c3d479) — The handoff token from the checkout link. ### Responses #### 200 The order of the token Type: [OrderHandoffClaim](/end-user-api/models.md#models/OrderHandoffClaim) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/end-user-api/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/orders/claim-handoff \ --request POST \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "handoffToken": "oht_f47ac10b58cc4372a5670e02b2c3d479" }' ``` ## [GET /orders/{orderId}](/end-user-api/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 + Bearer JWT ### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ### Responses #### 200 Order retrieved successfully Type: [Order](/end-user-api/models.md#models/Order) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` ## [PUT /orders/{orderId}](/end-user-api/orders#tag/orders/PUT/orders/{orderId}) Update order Update order details (excluding line items). Order must be in PENDING status. Authentication: X-Api-Key + Bearer JWT ### Path parameters - `orderId` (`string`, required) — The unique identifier of the order ### Request body (required) Type: `object` - `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. - `address` (`object`, optional) — The billing address that this order holds. It is a record of the order, and it does not change the billing address of the customer. The platform reads it for tax only when the customer holds no billing address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `attention` (`string`, optional, personal data, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `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). - `street` (`string`, optional, personal data, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, personal data, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, personal data, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `zip` (`string`, required, personal data, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused. - `email` (`string`, optional, email, personal data, example billing@example.com) — Billing contact email. - `name` (`string`, optional, example John Doe) — Billing contact name. - `consents` (`object with string keys`, optional, example {"marketing":"true","termsOfService":"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) - `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` - `billing` (`object`, optional) — Billing configuration and payment preferences for the new customer. - `address` (`object`, optional) — The billing address of the customer. A paper invoice goes to this address, and it decides the tax of each charge. A subscription with no service address of its own is served at this address. A delivery goes to this address when the customer holds no shipping address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `attention` (`string`, optional, personal data, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `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). - `street` (`string`, optional, personal data, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, personal data, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, personal data, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `zip` (`string`, required, personal data, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused. - `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. - `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. - `email` (`string`, optional, email, personal data, example billing@acme.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `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. - `contact` (`object`, optional) — Contact information for the new customer. - `email` (`string`, optional, email, personal data, example billing@acme.com) — Primary contact email for the new customer. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Primary contact phone number 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, personal data, 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. - `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) - `name` (`string`, required, example Acme Corporation) — Name for the new customer. - `preferredLocale` (`string`, optional, example en-US) — Preferred locale for the customer. - `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. - `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) - `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. - `shipping` (`object`, optional) — Shipping information for order fulfillment. Only required if the order contains shippable items. - `address` (`object`, required) — The address that the physical items of this order go to. It is a record of the order, and it does not change the shipping address of the customer. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `attention` (`string`, optional, personal data, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `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). - `street` (`string`, optional, personal data, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, personal data, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, personal data, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `zip` (`string`, required, personal data, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused. - `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. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `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` - `email` (`string`, required, email, personal data, example john.doe@example.com) — The email the user logs in with and receives order confirmations on. - `identity` (`string`, optional, personal data, 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. - `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. - `attention` (`string`, optional, personal data, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `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). - `street` (`string`, optional, personal data, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, personal data, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, personal data, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `zip` (`string`, required, personal data, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused. - `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) - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — The user's phone number. - `name` (`string`, required, example John Doe) — The user's full name. ### Responses #### 200 Order updated successfully Type: [Order](/end-user-api/models.md#models/Order) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/end-user-api/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/end-user-api/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID \ --request PUT \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "billing": { "address": { "attention": "John Doe", "city": "Natick", "country": "US", "region": "Ontario", "state": "CA", "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "zip": "01701" }, "email": "billing@example.com", "name": "John Doe" }, "consents": { "marketing": "true", "termsOfService": "true" }, "customer": { "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479" }, "metadata": { "propertyName": "string" }, "promoCode": "STUDENT2024", "shipping": { "address": { "attention": "John Doe", "city": "Natick", "country": "US", "region": "Ontario", "state": "CA", "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "zip": "01701" }, "instructions": "Leave at front door", "msisdn": "+15551234567", "name": "John Doe" }, "user": { "userId": "d47ac10b-58cc-4372-a567-0e02b2c3d479" } }' ``` ## [POST /orders/{orderId}/handoff-token](/end-user-api/orders#tag/orders/POST/orders/{orderId}/handoff-token) Create order handoff token Create a token that gives this order to a checkout. The checkout prices the order again, collects the payment, and submits the order. The order must be PENDING or PENDING_PAYMENT. The token is valid for 1 hour. It stops when the order is no longer PENDING or PENDING_PAYMENT. Each request creates a new token, and the earlier tokens stay valid until they expire. A person with the token can see, change, and pay for the order. Give the token only to the user that the order is for. Authentication: X-Api-Key + Bearer JWT ### 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](/end-user-api/models.md#models/OrderHandoffToken) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/end-user-api/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/handoff-token \ --request POST \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` ## [POST /orders/{orderId}/line-items](/end-user-api/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. A `SUBSCRIPTION` line item or an `EXTERNAL_PRODUCT` line item must name an initial product offering of the product catalog of the customer. `initialProductOfferingIds` of the customer product catalog names these product offerings. An order with no customer buys from the default product catalog. If the product offering is not one of them, the request gets status 400 with the `internalCode` `4334`. An add-on that the plan does not take gets the `internalCode` `4335`. Authentication: X-Api-Key + Bearer JWT ### 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` - `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. - `display` (`string`, optional, example John Doe - Work phone) — Custom display name for the subscription. If not provided, will be auto-generated from msisdn. - `extensions` (`object with string keys`, optional) — Additional subscription extensions fields for custom subscription types. - `*` (`string`, optional) - `leaseToken` (`string`, optional, example lease_8f3b1c2d4e5f6789) — Token received when leasing a number. Required when an msisdn is provided from the number pool. - `lineItemId` (`string`, required, example line-item-1) — Unique identifier for this line item within the 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) - `msisdn` (`string`, optional, personal data, 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. - `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. - `address` (`object`, required) — The address that the current provider holds for the account holder. The provider compares it with its own record before it releases the number. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `attention` (`string`, optional, personal data, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `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). - `street` (`string`, optional, personal data, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, personal data, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, personal data, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `zip` (`string`, required, personal data, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused. - `firstName` (`string`, required, personal data, example John) — The first name of the account holder at the current provider. - `lastName` (`string`, required, personal data, example Doe) — The last name of the account holder at the current provider. - `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. - One of: `PortingDetailsSweden` - `identity` (`string`, required, personal data, 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. - `portingRequested` (`boolean`, optional, example true) — If true, the number is a port-in. - `productOfferingId` (`string`, required, example mobile-plan-basic) — The product offering to create a subscription for. - `scheduleActivationAt` (`string`, optional, date, example 2024-02-01) — Date when the subscription should be activated. Cannot be combined with activateOnDemand. - `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. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `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 fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `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. - `address` (`object`, optional) — The address where the subscriber uses this subscription. In the US, this is the E911 address. Give it only when it is different from the billing address of the customer. The subscription then holds it as its service address. A subscription with no address of its own is served at the billing address. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `attention` (`string`, optional, personal data, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `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). - `street` (`string`, optional, personal data, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, personal data, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, personal data, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `zip` (`string`, required, personal data, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. A US ZIP code must hold five digits. The four-digit extension (ZIP+4) is refused. - `email` (`string`, optional, email, personal data, example john.doe@example.com) — Contact email of the subscriber. - `msisdn` (`string`, optional, phone, personal data, example +15551234567) — Contact phone number of the subscriber. May be the same as the subscription's msisdn. - `name` (`string`, optional, example John Doe) — Name of the subscriber. - `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). - `type` (`enum`, required, one of SUBSCRIPTION) — Identifies this line item as a new subscription purchase. Always SUBSCRIPTION. - One of: `ADDON` - `lineItemId` (`string`, required, example line-item-3) — Unique identifier for this line item within the 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) - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent subscription line item in this same order. Either this or `subscriptionId` must be provided. - `productOfferingId` (`string`, required, example addon-data-5gb) — The add-on product offering to add. - `scheduledAt` (`string`, optional, date, example 2024-02-01) — When to activate the add-on. - `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 fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, optional, example subscription-456) — An existing subscription to add the add-on to. Either this or `parentLineItemId` must be provided. - `type` (`enum`, required, one of ADDON) — Identifies this line item as adding an add-on to a subscription. Always ADDON. - One of: `EXTERNAL_PRODUCT` - `lineItemId` (`string`, required, example line-item-5) — Unique identifier for this line item within the 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) - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this 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. - `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. - `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 fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `type` (`enum`, required, one of EXTERNAL_PRODUCT) — Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT. - One of: `EXTERNAL` - `description` (`string`, optional, example Professional on-site installation and setup) — Description of the external item. - `fulfillmentWebhook` (`string`, optional, uri, example https://partner.com/webhooks/fulfillment) — Optional webhook URL for fulfillment notifications. - `lineItemId` (`string`, required, example line-item-6) — Unique identifier for this line item within the 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) - `name` (`string`, required, example Custom Installation Service) — Name of the external item. - `parentLineItemId` (`string`, optional, example line-item-1) — Reference to parent line item in this order. - `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. - `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 fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `taxationId` (`string`, optional, example TAX123456) — US taxation ID for tax calculation. - `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. - One of: `SUBSCRIPTION_CHANGE` - `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. - `lineItemId` (`string`, required, example line-item-7) — Unique identifier for this line item within the 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) - `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. - `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. - `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. - `iccid` (`string`, optional, personal data, example 8931440400000000000) — Integrated Circuit Card identifier for existing SIM. Provide if using a pre-existing SIM card. This feature only applies to certain networks. - `imei` (`string`, optional, personal data, example 356938035643809) — International Mobile Equipment Identity for eSIM activation. Some networks require this to activate the eSIM. - `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 fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, required, example subscription-456) — The identifier of the existing subscription that this line item changes. - `type` (`enum`, required, one of SUBSCRIPTION_CHANGE) — Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE. - One of: `ADDON_CHANGE` - `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. - `lineItemId` (`string`, required, example line-item-9) — Unique identifier for this line item within the 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) - `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. - `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. - `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. - `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 fulfillment status of an order line item. An order fulfills all its line items or none of them. Thus the status follows the order `state`, and each line item of one order has the same status. The status does not show when the network provisions a subscription or an add-on. The `order.updated` event carries the order again when the network provisions an entity of the order. - `subscriptionId` (`string`, required, example subscription-456) — The subscription containing the add-on to modify. - `type` (`enum`, required, one of ADDON_CHANGE) — Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE. ### Responses #### 201 Line item added successfully Type: [OrderLineItem](/end-user-api/models.md#models/OrderLineItem) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/end-user-api/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/end-user-api/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/line-items \ --request POST \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "lineItem": { "activateOnDemand": true, "display": "John Doe - Work phone", "extensions": { "propertyName": "string" }, "leaseToken": "lease_8f3b1c2d4e5f6789", "lineItemId": "line-item-1", "metadata": { "propertyName": "string" }, "msisdn": "+15551234567", "porting": { "details": { "accountNumber": "987654321", "address": { "attention": "John Doe", "city": "Natick", "country": "US", "region": "Ontario", "state": "CA", "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "zip": "01701" }, "firstName": "John", "lastName": "Doe", "passcode": "123456" } }, "portingRequested": true, "productOfferingId": "mobile-plan-basic", "scheduleActivationAt": "2024-02-01", "sim": { "esim": true, "iccid": "8931440400000000000", "imei": "356938035643809" }, "subscriber": { "address": { "attention": "John Doe", "city": "Natick", "country": "US", "region": "Ontario", "state": "CA", "street": "500 S Main St", "street1": "string", "street2": "Apt 1", "zip": "01701" }, "email": "john.doe@example.com", "msisdn": "+15551234567", "name": "John Doe" }, "tempNumber": true, "type": "SUBSCRIPTION" } }' ``` ## [DELETE /orders/{orderId}/line-items/{lineItemId}](/end-user-api/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 + Bearer JWT ### 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](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/end-user-api/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/end-user-api/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/line-items/LINE_ITEM_ID \ --request DELETE \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` ## [POST /orders/{orderId}/submit](/end-user-api/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 + Bearer JWT ### 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` - `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. - `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. - `reference` (`string`, required, min length 1, example ext-payment-ref-123) — Reference or identifier from the external payment system. - `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) - `paymentProfileSessionId` (`string`, optional, example b2c3d4e5-f6a7-8901-2345-6789abcdef01) — Reference to completed payment profile session for zero-total orders requiring payment method setup. - `paymentSessionId` (`string`, optional, example a1b2c3d4-e5f6-7890-1234-56789abcdef0) — Reference to completed payment session for orders requiring payment collection. - `signingSessionId` (`string`, optional, example c3d4e5f6-a7b8-9012-3456-789abcdef012) — Reference to completed signing session. ### Responses #### 200 Order submitted successfully Type: [Order](/end-user-api/models.md#models/Order) #### 400 The request was malformed or invalid. Type: [Error](/end-user-api/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/end-user-api/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/end-user-api/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/end-user-api/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/end-user-api/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/end-user-api/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/end-user-api/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/end-user-api/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/end-user/orders/ORDER_ID/submit \ --request POST \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901" }' ```