{ "openapi": "3.1.0", "info": { "title": "Telness Tech API", "version": "2026-08-21.auk", "description": "The Telness Tech API provides all you need to own your user's connectivity experience.\n\nGo back to [Telnesstech.com](https://telnesstech.com)\n", "license": { "name": "Proprietary", "identifier": "LicenseRef-Telness-Tech-Proprietary" } }, "servers": [ { "url": "{BASE_URL}", "description": "The base URL for the API, provided for your domain.", "variables": { "BASE_URL": { "default": "https://apiv2.example.com/api/v2", "description": "The base URL for your domain." } } } ], "security": [ { "apiKey": [] }, { "bearerAuth": [], "apiKey": [] } ], "tags": [ { "name": "Auth", "description": "Authenticate users and obtain access tokens." }, { "name": "Users", "description": "Manage users." }, { "name": "Customers", "description": "Manage customers." }, { "name": "Subscriptions", "description": "Manage subscriptions and subscription." }, { "name": "Subscription Addons", "description": "Manage subscription addons." }, { "name": "Subscription Usage", "description": "Get subscription usage." }, { "name": "Subscribers", "description": "Manage subscribers." }, { "name": "Licenses", "description": "Manage licenses." }, { "name": "Product Offerings", "description": "Browse product offerings." }, { "name": "Product Catalogs", "description": "Browse product catalogs." }, { "name": "Product Discounts", "description": "Discounts and promotions." }, { "name": "Orders", "description": "Manage orders and line items." }, { "name": "Payment Intents", "description": "Inspect payment intents, the money collected over card rails for orders and renewals." }, { "name": "Payment Links", "description": "Create and manage payment links for orders and invoices." }, { "name": "Payment Sessions", "description": "Create and manage payment sessions for orders." }, { "name": "Payment Profiles", "description": "Manage customer payment profiles and methods." }, { "name": "Payment Profile Sessions", "description": "Create sessions for setting up payment profiles." }, { "name": "Signing sessions", "description": "Handle contract signing sessions for postpaid orders." }, { "name": "Porting", "description": "Manage number porting for subscriptions." }, { "name": "Invoices", "description": "Manage invoices and invoice items." }, { "name": "Tools", "description": "Tools for address validation, number porting, device info, and network coverage." }, { "name": "Inventory", "description": "Manage phone number inventory, SIM cards, and reservations." }, { "name": "Workflows", "description": "Dynamic processing of customer journeys and events." }, { "name": "Reports", "description": "Retrieve generated reports and download their files." } ], "paths": { "/auth/email/start": { "post": { "summary": "Start email login", "description": "Initiates an email-based login flow by sending a verification code to the provided email address.\n\nThe response includes a nonce that must be used when verifying the login, along with timing information for the verification code.\n\nThis endpoint always returns 202 Accepted to prevent email enumeration attacks.\n", "operationId": "startEmailLogin", "tags": [ "Auth" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartEmailLoginRequest" }, "example": { "email": "john.doe@example.com" } } } }, "responses": { "202": { "description": "Login flow initiated. A verification code has been sent to the email address if it exists in the system.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartEmailLoginResponse" }, "example": { "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "expiresIn": 300, "createdAt": "2024-01-15T10:30:00Z", "expiresAt": "2024-01-15T10:35:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/auth/email/verify": { "post": { "summary": "Verify email login", "description": "Verifies an email login by validating the verification code sent to the email address.\n\nOn success, returns an OAuth2-style bearer token response with:\n- `accessToken`: JWT token for authenticating subsequent API requests\n- `tokenType`: Always \"Bearer\"\n- `expiresIn`: Token lifetime in seconds\n- `userId`: The authenticated user's identifier\n\nUse the access token in the Authorization header: `Authorization: Bearer {accessToken}`\n", "operationId": "verifyEmailLogin", "tags": [ "Auth" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyEmailLoginRequest" }, "example": { "email": "john.doe@example.com", "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "code": "123456" } } } }, "responses": { "200": { "description": "Login verified successfully. Returns access token for API authentication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" }, "example": { "accessToken": "\u003caccess-token\u003e", "tokenType": "Bearer", "expiresIn": 604800, "userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/users": { "get": { "summary": "List users", "description": "List all users.\n\nWill return all users the requester has access to.\n", "operationId": "listUsers", "tags": [ "Users" ], "parameters": [ { "in": "query", "name": "filter", "schema": { "type": "string" }, "description": "A free text search string to filter users by name or email." }, { "in": "query", "name": "customerId", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by customer. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A list of users.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/User" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "summary": "Create user", "description": "Create a new user.", "operationId": "createUser", "tags": [ "Users" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserRequest" }, "example": { "name": "John Doe", "email": "john.doe@example.com", "msisdn": "+15551234567", "role": "ADMIN", "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "referenceId": "hr-employee-98765" } } } }, "responses": { "201": { "description": "User created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" }, "example": { "userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e", "name": "John Doe", "email": "john.doe@example.com", "msisdn": "+15551234567", "referenceId": "hr-employee-98765", "customers": [ { "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "name": "Acme Corp" } ], "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/users/{userId}": { "get": { "summary": "Get user", "description": "Get a user by ID or referenceId.", "operationId": "getUser", "tags": [ "Users" ], "parameters": [ { "in": "path", "name": "userId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the user. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_hr-employee-98765`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" } ], "responses": { "200": { "description": "User details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "summary": "Update user", "description": "Update an existing user.", "operationId": "updateUser", "tags": [ "Users" ], "parameters": [ { "in": "path", "name": "userId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the user. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_hr-employee-98765`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateUserRequest" } } } }, "responses": { "200": { "description": "User updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers": { "get": { "summary": "List customers", "description": "List all customers.\n\nWill return all customers the requester has access to.\n", "operationId": "listCustomers", "tags": [ "Customers" ], "parameters": [ { "in": "query", "name": "filter", "schema": { "type": "string" }, "description": "A free text search string to filter customers." }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A list of customers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "example": { "items": [ { "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "customerType": "BUSINESS", "name": "Acme Corp", "humanReadableId": "29A-BY3Z-X78", "referenceId": "crm-customer-12345", "preferredLocale": "en-US", "contact": { "email": "john.doe@example.com", "msisdn": "+15551234567" }, "billing": { "method": "EMAIL_INVOICE", "email": "billing@example.com", "currency": "USD", "autoPay": false }, "users": [ { "userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e", "name": "John Doe", "role": "ADMIN" } ], "contactPerson": { "userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e", "name": "John Doe", "role": "ADMIN" }, "shipping": { "name": "John Doe", "msisdn": "+15551234567", "address": { "street": "123 Main Street", "city": "New York", "zip": "10001", "state": "NY", "country": "US" } } } ], "pagination": { "nextCursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "summary": "Create customer", "description": "Create a new customer.", "operationId": "createCustomer", "tags": [ "Customers" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" }, "example": { "customerType": "BUSINESS", "name": "Acme Corp", "referenceId": "crm-customer-12345", "preferredLocale": "en-US", "contact": { "email": "john.doe@example.com", "msisdn": "+15551234567" }, "billing": { "method": "EMAIL_INVOICE", "email": "billing@example.com", "currency": "USD" }, "userIds": [ "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e" ], "contactPersonUserId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e", "shipping": { "name": "John Doe", "msisdn": "+15551234567", "address": { "street": "123 Main Street", "city": "New York", "zip": "10001", "state": "NY", "country": "US" } } } } } }, "responses": { "201": { "description": "Customer created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "customerType": "BUSINESS", "name": "Acme Corp", "humanReadableId": "29A-BY3Z-X78", "referenceId": "crm-customer-12345", "preferredLocale": "en-US", "contact": { "email": "john.doe@example.com", "msisdn": "+15551234567" }, "billing": { "method": "EMAIL_INVOICE", "email": "billing@example.com", "currency": "USD", "autoPay": false }, "users": [ { "userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e", "name": "John Doe", "role": "ADMIN" } ], "contactPerson": { "userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e", "name": "John Doe", "role": "ADMIN" }, "shipping": { "name": "John Doe", "msisdn": "+15551234567", "address": { "street": "123 Main Street", "city": "New York", "zip": "10001", "state": "NY", "country": "US" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{customerId}": { "get": { "summary": "Get customer", "description": "Get a customer by ID or referenceId.", "operationId": "getCustomer", "tags": [ "Customers" ], "parameters": [ { "in": "path", "name": "customerId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the customer. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" } ], "responses": { "200": { "description": "Customer details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "customerType": "BUSINESS", "name": "Acme Corp", "humanReadableId": "29A-BY3Z-X78", "referenceId": "crm-customer-12345", "preferredLocale": "en-US", "contact": { "email": "john.doe@example.com", "msisdn": "+15551234567" }, "billing": { "method": "EMAIL_INVOICE", "email": "billing@example.com", "currency": "USD", "autoPay": false }, "users": [ { "userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e", "name": "John Doe", "role": "ADMIN" } ], "contactPerson": { "userId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e", "name": "John Doe", "role": "ADMIN" }, "shipping": { "name": "John Doe", "msisdn": "+15551234567", "address": { "street": "123 Main Street", "city": "New York", "zip": "10001", "state": "NY", "country": "US" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "summary": "Update customer", "description": "Update an existing customer.", "operationId": "updateCustomer", "tags": [ "Customers" ], "parameters": [ { "in": "path", "name": "customerId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the customer. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerRequest" }, "examples": { "updateContact": { "summary": "Update customer contact information", "value": { "contact": { "email": "newemail@example.com", "msisdn": "+15559876543" } } }, "updateBilling": { "summary": "Update billing method and address", "value": { "billing": { "method": "PAPER_INVOICE", "address": { "street": "789 Business Blvd", "city": "Chicago", "state": "IL", "zip": "60601", "country": "US" }, "currency": "USD" } } }, "fullUpdate": { "summary": "Complete customer update", "value": { "name": "Updated Customer Name", "preferredLocale": "sv-SE", "contact": { "email": "updated@example.com", "msisdn": "+46701234567" }, "billing": { "method": "EMAIL_INVOICE", "email": "billing@updated.com", "currency": "SEK", "autoPay": true }, "shippingAddress": { "street": "Updated Street 123", "city": "Stockholm", "zip": "11122", "country": "SE" } } } } } } }, "responses": { "200": { "description": "Customer updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{customerId}/users": { "delete": { "summary": "Remove user from customer", "description": "Remove a user from a customer. The user keeps their account, so they can still be added to\nanother customer later, but loses the roles and permissions this customer granted them.\n\nA customer's contact person cannot be removed — assign another contact person first.\n", "operationId": "removeUserFromCustomer", "tags": [ "Customers" ], "parameters": [ { "in": "path", "name": "customerId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the customer. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "in": "query", "name": "userId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the user to remove from the customer. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_hr-employee-98765`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "User removed from customer successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/customers/{customerId}/product-catalog": { "get": { "summary": "Get customer product catalog", "description": "Get the customer's product catalog, this is a combination of the default product catalog configured in the system and\nother product catalogs assigned to the customer.\n", "operationId": "getCustomerProductCatalog", "tags": [ "Customers" ], "parameters": [ { "in": "path", "name": "customerId", "required": true, "description": "The unique identifier of the customer to fetch the product catalog for. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Customer product catalog.", "content": { "application/json": { "schema": { "type": "object", "description": "The customer's product catalog is a combination of the default product catalog configured in the system and\nother product catalogs assigned to the customer.\n", "additionalProperties": false, "properties": { "productOfferingGroups": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOfferingGroup" }, "description": "The product groups in this catalog." }, "productOfferings": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOffering" }, "description": "The product offerings available in this catalog." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions": { "get": { "summary": "List subscriptions", "description": "List all subscriptions.\n\nWill return all subscriptions the requester has access to.\n", "operationId": "listSubscriptions", "tags": [ "Subscriptions" ], "parameters": [ { "in": "query", "name": "customerId", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by customer. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "in": "query", "name": "status", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionStatus" } }, "description": "The status of the subscription to filter by." }, { "in": "query", "name": "type", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionType" } } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A list of subscriptions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "example": { "items": [ { "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4", "referenceId": "crm-subscription-12345", "status": "ACTIVATED", "type": "CELL", "display": "(555) 123-4567", "msisdn": "+15551234567", "customer": { "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "name": "Acme Corp" }, "productOffering": { "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "Seamless 10GB", "price": { "netPriceMinor": 2999, "currency": "USD", "priceType": "RECURRING", "billingCycle": { "period": "MONTHLY", "interval": 1 }, "standardDiscount": { "amountMinor": 500 }, "bindingContract": { "duration": { "unit": "MONTHS", "value": 12 }, "discount": { "amountMinor": 200 } }, "customUpfrontPayment": { "billingCycles": 3, "discount": { "amountMinor": 300 } }, "currencyOptionsMinor": { "USD": 2999, "SEK": 29900 } } }, "subscriber": { "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e", "name": "John Doe", "email": "john.doe@example.com" }, "sim": { "esim": true, "iccid": "8901240197155182976" }, "activatedAt": "2024-01-15T10:30:00Z", "createdAt": "2024-01-10T08:00:00Z", "updatedAt": "2024-01-15T10:30:00Z", "metadata": { "costCenter": "eng-42" } } ], "pagination": { "nextCursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "summary": "Create subscription", "description": "Create a new subscription for a customer.\n\n**Activation Modes:**\n\n1. **Immediate Activation**\n - Provide complete activation data in the request\n - Omit scheduleActivationAt or set to today's date\n - Subscription activates immediately (network availability permitting)\n\n2. **Scheduled Activation**\n - Provide complete activation data in the request\n - Set scheduleActivationAt to a future date\n - Subscription activates on or after the specified date\n\n3. **Deferred Activation (Shell Subscription)**\n - Omit activation data from the request\n - Subscription created in PENDING state\n - Use the activate endpoint later when activation details are available\n\n**Common use cases:**\n- Standard activation: Customer has all details ready (number choice, SIM type, porting info)\n- Scheduled activation: Activate on a specific date (e.g., start of billing cycle, go-live date)\n- Shell subscription: Bulk subscription creation, waiting for SIM delivery, phased onboarding\n\n**Note**: This endpoint may be disabled when Seamless OS manages billing. In that configuration,\nsubscriptions are created through the orders endpoint instead.\n", "operationId": "createSubscription", "tags": [ "Subscriptions" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionRequest" } } } }, "responses": { "201": { "description": "The created subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}": { "get": { "summary": "Get subscription", "description": "Retrieve detailed information about a specific subscription using its unique identifier.", "operationId": "getSubscriptionById", "tags": [ "Subscriptions" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" } ], "responses": { "200": { "description": "A subscription object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "example": { "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4", "referenceId": "crm-subscription-12345", "status": "ACTIVATED", "type": "CELL", "display": "(555) 123-4567", "msisdn": "+15551234567", "customer": { "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "name": "Acme Corp" }, "productOffering": { "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "Seamless 10GB", "price": { "netPriceMinor": 2999, "currency": "USD", "priceType": "RECURRING", "billingCycle": { "period": "MONTHLY", "interval": 1 }, "standardDiscount": { "amountMinor": 500 }, "bindingContract": { "duration": { "unit": "MONTHS", "value": 12 }, "discount": { "amountMinor": 200 } }, "customUpfrontPayment": { "billingCycles": 3, "discount": { "amountMinor": 300 } }, "currencyOptionsMinor": { "USD": 2999, "SEK": 29900 } } }, "subscriber": { "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e", "name": "John Doe", "email": "john.doe@example.com" }, "sim": { "esim": true, "iccid": "8901240197155182976" }, "activatedAt": "2024-01-15T10:30:00Z", "createdAt": "2024-01-10T08:00:00Z", "updatedAt": "2024-01-15T10:30:00Z", "metadata": { "costCenter": "eng-42" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/activate": { "post": { "summary": "Activate subscription", "description": "Activate a pending subscription by providing the necessary network activation details.\n\nUse this endpoint when a subscription was created as a \"shell\" without activation data.\n\nIf the subscription is not pending, an error will be returned.\n", "operationId": "activateSubscription", "tags": [ "Subscriptions" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateSubscriptionRequest" }, "example": { "activation": { "msisdn": "+15551234567", "leaseToken": "lease_abc123def456", "sim": { "esim": true } } } } } }, "responses": { "200": { "description": "Subscription activation scheduled or completed successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "example": { "subscriptionId": "d8174435-6378-4be5-a9f5-8b4aaadae5d4", "referenceId": "crm-subscription-12345", "status": "ACTIVATED", "type": "CELL", "display": "(555) 123-4567", "msisdn": "+15551234567", "customer": { "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "name": "Acme Corp" }, "productOffering": { "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "Seamless 10GB", "price": { "netPriceMinor": 2999, "currency": "USD", "priceType": "RECURRING", "billingCycle": { "period": "MONTHLY", "interval": 1 }, "standardDiscount": { "amountMinor": 500 }, "bindingContract": { "duration": { "unit": "MONTHS", "value": 12 }, "discount": { "amountMinor": 200 } }, "customUpfrontPayment": { "billingCycles": 3, "discount": { "amountMinor": 300 } }, "currencyOptionsMinor": { "USD": 2999, "SEK": 29900 } } }, "subscriber": { "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e", "name": "John Doe", "email": "john.doe@example.com" }, "sim": { "esim": true, "iccid": "8901240197155182976" }, "activatedAt": "2024-01-15T10:30:00Z", "createdAt": "2024-01-10T08:00:00Z", "updatedAt": "2024-01-15T10:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/in-porting": { "get": { "summary": "Get subscription in-porting", "description": "Retrieve the current porting information for a subscription that is in the process of porting in a number.", "operationId": "getSubscriptionInPorting", "tags": [ "Subscriptions", "Porting" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" } ], "responses": { "200": { "description": "Porting information retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Porting" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "summary": "Update subscription porting details", "description": "Update the porting details for a subscription that is in the process of\nporting in a number. This endpoint allows you to modify porting information\nwhile the port is still pending or in progress.\n", "operationId": "updateSubscriptionPorting", "tags": [ "Subscriptions", "Porting" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePortingRequest" }, "example": { "details": { "identity": "199001011234" } } } } }, "responses": { "200": { "description": "Porting details updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "$ref": "#/components/schemas/Subscription" }, "portingInfo": { "type": "object", "description": "Updated porting information and status.", "properties": { "portingId": { "type": "string", "description": "The unique identifier for this porting request." }, "status": { "type": "string", "enum": [ "pending", "in_progress", "scheduled", "completed", "failed" ], "description": "Current status of the porting process." }, "estimatedCompletion": { "type": "string", "format": "date-time", "description": "Estimated completion time for the port." }, "nextSteps": { "type": "array", "items": { "type": "string" }, "description": "Next steps required to complete the porting process." } } } } }, "example": { "subscription": { "subscriptionId": "7a1b9c3d-2e4f-4a6b-8c0d-9e8f7a6b5c4d", "status": "ACTIVATED", "type": "CELL", "display": "073-111 00 00", "msisdn": "+46731110000", "customer": { "customerId": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d", "name": "Volt AB" }, "productOffering": { "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "name": "Mobil 10GB", "price": { "netPriceMinor": 24900, "currency": "SEK", "priceType": "RECURRING", "billingCycle": { "period": "MONTHLY", "interval": 1 }, "standardDiscount": { "amountMinor": 5000 }, "bindingContract": { "duration": { "unit": "MONTHS", "value": 12 }, "discount": { "amountMinor": 2000 } }, "customUpfrontPayment": { "billingCycles": 3, "discount": { "amountMinor": 3000 } }, "currencyOptionsMinor": { "SEK": 24900, "USD": 2499 } } }, "subscriber": { "subscriberId": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e", "name": "Anna Andersson", "email": "anna.andersson@example.com" }, "sim": { "esim": false, "iccid": "8946071234567890123" }, "pendingMsisdn": { "msisdn": "+46701234567", "scheduledAt": "2025-02-01" }, "porting": { "msisdn": "+46701234567", "status": "IN_PROGRESS", "direction": "INBOUND", "scheduledAt": "2025-02-01" }, "activatedAt": "2025-01-10T09:00:00Z", "createdAt": "2025-01-08T08:00:00Z", "updatedAt": "2025-01-15T10:30:00Z" }, "portingInfo": { "portingId": "e5f6a7b8-c9d0-4123-8456-789abcdef012", "status": "in_progress", "estimatedCompletion": "2025-02-01T00:00:00Z", "nextSteps": [ "Waiting for the current provider to respond to the porting request", "No action required at this time" ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/product-offering-change": { "put": { "summary": "Change subscription product offering", "description": "Change the product offering of a subscription (upgrade or downgrade).\n\nTo get a list of to what and when the subscription can be changed,\nget change options for the subscription.\n\nWhen the change takes effect is dictated by what product offering is chosen,\nwhich in its place depends on the network setup, billing cycle.\n", "operationId": "changeSubscriptionProductOffering", "tags": [ "Subscriptions" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSubscriptionProductOfferingRequest" } } } }, "responses": { "200": { "description": "Product offering change scheduled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/product-offering-options": { "get": { "summary": "Get change options for subscription", "description": "Get all available product offerings a subscription can be changed to and\nwhen the change can take effect.\n\nWhen the subscription can be changed typically depends on the network setup,\nbilling cycle, and current product offering. As a rule of thumb (though not always),\nupgrades and lateral moves are immediate, while downgrades take effect at the next\nrenewal date.\n", "operationId": "getSubscriptionOfferingOptions", "tags": [ "Subscriptions" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" } ], "responses": { "200": { "description": "Available change options.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOfferingOption" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/addon-options": { "get": { "summary": "Get add-on options for subscription", "description": "Get the add-ons that can be added to this subscription now.\n\nAn add-on appears only when its product category matches the subscription's product offering. It must also be part of the customer's product catalog. For example, a travel package will not appear for a cell subscription, because their product categories do not match.\n\nAn order that adds an add-on not in this list will be refused.\n", "operationId": "getSubscriptionAddonOptions", "tags": [ "Subscription Addons" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" } ], "responses": { "200": { "description": "The add-on options available for this subscription.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOffering" }, "description": "The add-on product offerings available for this subscription." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/addons": { "get": { "summary": "List active add-ons for subscription", "description": "Get all active and pending add-ons for a subscription.\n\nThis endpoint returns only add-ons that are currently attached to the subscription,\nincluding their status and scheduling information. Use /addon-options to query available add-ons.\n", "operationId": "getSubscriptionAddons", "tags": [ "Subscription Addons" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "in": "query", "name": "status", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionAddonStatus" } }, "description": "Filter add-ons by status." } ], "responses": { "200": { "description": "Active add-ons for the subscription.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionAddon" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "summary": "Add subscription add-on", "description": "Add an add-on to a subscription.\n\nThis endpoint includes adding an add-on to a subscription. The add-on can be scheduled to be\nactivated immediately or at a future date.\n", "operationId": "addSubscriptionAddon", "tags": [ "Subscription Addons" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddAddonRequest" } } } }, "responses": { "201": { "description": "Add-on added successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionAddon" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/cancel": { "post": { "summary": "Cancel subscription", "description": "This endpoint allows cancelling a subscription with various timing options:\n- Next day cancellation\n- Beginning of next month cancellation\n- Specific date cancellation\n\nStandardized churn reasons help with reporting and analysis.\n", "operationId": "cancelSubscription", "tags": [ "Subscriptions" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelSubscriptionRequest" } } } }, "responses": { "200": { "description": "Subscription cancellation scheduled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/suspend": { "post": { "summary": "Suspend subscription", "description": "Temporarily suspend a subscription. The customer continues to pay but service is disabled.\nThis is typically used for payment issues or fraud prevention.\n\nSupports flexible scheduling:\n- Immediate suspension\n- Next day suspension\n- Beginning of next month suspension\n- Specific date suspension\n", "operationId": "suspendSubscription", "tags": [ "Subscriptions" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuspendSubscriptionRequest" } } } }, "responses": { "200": { "description": "Subscription suspension scheduled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/pause": { "post": { "summary": "Pause subscription", "description": "Pause a subscription. The customer stops paying and service is disabled.\nThis is typically used when a customer wants to temporarily stop service.\n\nSupports flexible scheduling:\n- Immediate pause\n- Next day pause\n- Beginning of next month pause\n- Specific date pause\n", "operationId": "pauseSubscription", "tags": [ "Subscriptions" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PauseSubscriptionRequest" } } } }, "responses": { "200": { "description": "Subscription pause scheduled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/restore": { "post": { "summary": "Restore subscription", "description": "Restore a suspended, paused, or blocked subscription back to active state.\n\nSupports flexible scheduling:\n- Immediate restore\n- Next day restoration\n- Beginning of next month restoration\n- Specific date restoration\n", "operationId": "restoreSubscription", "tags": [ "Subscriptions" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreSubscriptionRequest" } } } }, "responses": { "200": { "description": "Subscription restoration scheduled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/block-sim": { "post": { "summary": "Block SIM", "description": "Block the SIM card on a subscription, so it can no longer use the network. Use this when a\nsubscriber reports their SIM lost or stolen.\n\nThe block takes effect immediately and cannot be scheduled. Any changes already scheduled on the\nsubscription are cancelled, except an in-progress number port or a scheduled SIM card change,\nwhich both continue — a cancelled port would lose the subscriber their number.\n\nBlocking is not reversible through this endpoint: issue a new SIM card to bring the subscription\nback into service.\n", "operationId": "blockSim", "tags": [ "Subscriptions" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "SIM blocked successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/change-sim": { "post": { "summary": "Change subscription SIM card", "description": "Change the SIM card (ICC/ICCID) for a subscription. This is used when replacing\na lost, damaged, or upgraded SIM card.\n\nSupports flexible scheduling:\n- Immediate SIM card change\n- Next day SIM card change\n- Beginning of next month SIM card change\n- Specific date SIM card change\n", "operationId": "changeSubscriptionSim", "tags": [ "Subscriptions" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSubscriptionSimRequest" } } } }, "responses": { "200": { "description": "SIM card change scheduled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/addons/cancel": { "post": { "summary": "Cancel subscription add-on", "description": "Cancel an add-on on a subscription.\n\nThis endpoint allows cancelling active add-ons on a subscription.\nThe add-on will be canceled according to the specified schedule or immediately if no schedule is provided.\n", "operationId": "cancelSubscriptionAddon", "tags": [ "Subscription Addons" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelAddonRequest" } } } }, "responses": { "200": { "description": "Add-on cancellation scheduled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionAddon" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/addons/product-offering-change": { "put": { "summary": "Change subscription add-on product offering", "description": "Change an existing add-on to a different product offering (upgrade or downgrade).\n\nThis endpoint allows you to change an existing add-on attached to a subscription to a different\nadd-on product offering. The change can be scheduled for immediate or future execution.\n\nWhen the change takes effect depends on the new product offering chosen, billing cycle,\nand the preferred schedule date provided in the request.\n", "operationId": "changeSubscriptionAddonProductOffering", "tags": [ "Subscription Addons" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeAddonRequest" } } } }, "responses": { "200": { "description": "Add-on change scheduled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionAddon" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/addons/product-offering-options": { "get": { "summary": "Get change options for subscription add-on", "description": "Get all available product offerings an existing add-on can be changed to and\nwhen the change can take effect.\n\nWhen the add-on can be changed typically depends on the network setup,\nbilling cycle, and current add-on product offering. As a rule of thumb (though not always),\nupgrades and lateral moves are immediate, while downgrades take effect at the next\nrenewal date.\n", "operationId": "getSubscriptionAddonChangeOptions", "tags": [ "Subscription Addons" ], "parameters": [ { "in": "path", "name": "subscriptionId", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "in": "query", "name": "currentProductOfferingId", "required": true, "schema": { "type": "string" }, "description": "The current add-on product offering to get change options for." } ], "responses": { "200": { "description": "Available change options for the add-on.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOfferingOption" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/usage": { "get": { "summary": "Get subscription usage", "description": "Retrieve the current period's usage for a subscription.", "operationId": "getSubscriptionUsage", "tags": [ "Subscription Usage" ], "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Current usage statistics for the subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" }, "example": { "voice": { "national": [ { "name": "Unlimited National", "callSeconds": 3600, "callCount": 15, "callRemainingSeconds": 32400, "callTotalSeconds": 36000, "status": "ACTIVE", "validFrom": "2025-01-01T00:00:00Z", "validTo": "2025-02-01T00:00:00Z" } ], "ild": [ { "name": "ILD Top-up", "balanceMinor": 1550, "currency": "USD", "expiryDate": "2025-12-31" } ] }, "sms": { "national": [ { "name": "500 SMS National", "smsCount": 25, "smsRemaining": 475, "smsTotal": 500, "status": "ACTIVE", "validFrom": "2025-01-01T00:00:00Z", "validTo": "2025-02-01T00:00:00Z" } ] }, "data": { "national": [ { "name": "10GB National", "dataBytesUsed": 3221225472, "dataBytesRemaining": 7516192768, "dataBytesTotal": 10737418240, "status": "ACTIVE", "validFrom": "2025-01-01T00:00:00Z", "validTo": "2025-02-01T00:00:00Z" } ], "roaming": [ { "name": "Asia 5GB Roaming", "subscriptionAddonId": "a47ac10b-58cc-4372-a567-0e02b2c3d479", "dataBytesUsed": 1073741824, "dataBytesRemaining": 4294967296, "dataBytesTotal": 5368709120, "status": "ACTIVE", "validFrom": "2025-01-01T00:00:00Z", "validTo": "2025-02-01T00:00:00Z" } ] }, "updatedAt": "2025-01-15T10:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/{subscriptionId}/esim/qrcode": { "get": { "summary": "Get eSIM QR code", "description": "Retrieve QR code data and hosted URL for eSIM profile download.\n\nReturns both the raw QR code data (LPA format) and a hosted URL for the QR code image. Only available for eSIM subscriptions (`sim.esim: true`). QR codes expire for security and should be treated as sensitive data.\n", "operationId": "getSubscriptionEsimQrCode", "tags": [ "Subscriptions" ], "parameters": [ { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The identifier of the subscription. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-subscription-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" } ], "responses": { "200": { "description": "eSIM QR code data and hosted URL retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EsimQrCode" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscriptions/usage": { "get": { "summary": "Get usage for multiple subscriptions", "description": "Retrieve current usage statistics for multiple subscriptions by providing their IDs.", "operationId": "getSubscriptionsUsage", "tags": [ "Subscription Usage" ], "parameters": [ { "name": "subscriptionIds", "in": "query", "required": true, "description": "List of subscription IDs to retrieve usage for.", "schema": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100 } } ], "responses": { "200": { "description": "Usage statistics for the requested subscriptions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "description": "Usage information for each requested subscription.", "items": { "type": "object", "required": [ "subscriptionId", "usage" ], "additionalProperties": false, "properties": { "subscriptionId": { "type": "string", "description": "The unique identifier for the subscription.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "usage": { "$ref": "#/components/schemas/Usage" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscribers": { "get": { "summary": "List subscribers", "description": "List all subscribers.\n\nWill return all subscribers the requester has access to.\n", "operationId": "listSubscribers", "tags": [ "Subscribers" ], "parameters": [ { "in": "query", "name": "customerIds", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by customer. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "in": "query", "name": "subscriptionIds", "schema": { "type": "array", "items": { "type": "string" } }, "description": "The unique identifier of the subscription to filter by." }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A list of subscribers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriberListItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/subscribers/{subscriberId}": { "get": { "summary": "Get subscriber", "description": "Retrieve detailed information about a specific subscriber using its unique identifier.", "operationId": "getSubscriberById", "tags": [ "Subscribers" ], "parameters": [ { "in": "path", "name": "subscriberId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the subscriber." } ], "responses": { "200": { "description": "A subscriber object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscriber" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "summary": "Update subscriber", "description": "Update the details of an existing subscriber.", "operationId": "updateSubscriber", "tags": [ "Subscribers" ], "parameters": [ { "in": "path", "name": "subscriberId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the subscriber." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSubscriberRequest" } } } }, "responses": { "200": { "description": "Subscriber updated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscriber" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/licenses": { "get": { "summary": "List licenses", "description": "List all licenses.", "operationId": "listLicenses", "tags": [ "Licenses" ], "parameters": [ { "in": "query", "name": "customerId", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by customer. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n" }, { "in": "query", "name": "type", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LicenseType" } }, "description": "The type of license to filter by." }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A list of licenses.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/License" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "summary": "Create license", "description": "Create a new license", "operationId": "createLicense", "tags": [ "Licenses" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLicenseRequest" }, "examples": { "externalProduct": { "summary": "Standalone offering for an external product, which takes no assignment", "value": { "productOfferingId": "a7b8c9d0-e1f2-3456-7890-bcdef0123456", "customerId": "b8c9d0e1-f2a3-4567-8901-cdef01234567" } }, "subscriptionAssignment": { "summary": "Addon offering, which the request must assign to a subscription", "value": { "productOfferingId": "d0e1f2a3-b4c5-6789-0123-ef0123456789", "customerId": "b8c9d0e1-f2a3-4567-8901-cdef01234567", "assignedTo": { "type": "SUBSCRIPTION", "subscriptionId": "c9d0e1f2-a3b4-5678-9012-def012345678" }, "scheduleActivationAt": "2024-01-20" } }, "scheduledLicense": { "summary": "Addon offering activated on a future date", "value": { "productOfferingId": "d0e1f2a3-b4c5-6789-0123-ef0123456789", "customerId": "b8c9d0e1-f2a3-4567-8901-cdef01234567", "assignedTo": { "type": "SUBSCRIPTION", "subscriptionId": "c9d0e1f2-a3b4-5678-9012-def012345678" }, "scheduleActivationAt": "2024-02-01", "metadata": { "costCenter": "eng-42" } } } } } } }, "responses": { "201": { "description": "License created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/License" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/licenses/{licenseId}": { "get": { "summary": "Get license", "description": "Retrieve detailed information about a specific license using its unique identifier.", "operationId": "getLicenseById", "tags": [ "Licenses" ], "parameters": [ { "in": "path", "name": "licenseId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the license." } ], "responses": { "200": { "description": "A license object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/License" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/licenses/{licenseId}/product-offering-change": { "put": { "summary": "Change license product offering", "description": "Change the product offering of a license (upgrade or downgrade).\n\nTo get a list of what product offerings the license can be changed to and when,\nget change options for the license.\n\nWhen the change takes effect is dictated by what product offering is chosen,\nwhich in turn depends on the license terms and billing cycle.\n", "operationId": "changeLicenseProductOffering", "tags": [ "Licenses" ], "parameters": [ { "in": "path", "name": "licenseId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the license." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeLicenseProductOfferingRequest" } } } }, "responses": { "200": { "description": "Product offering change scheduled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/License" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/licenses/{licenseId}/product-offering-options": { "get": { "summary": "Get product offering options for license", "description": "Get all available product offerings a license can be changed to and\nwhen the change can take effect.\n\nWhen the license can be changed typically depends on the license terms,\nbilling cycle, and current product offering. As a rule of thumb (though not always),\nupgrades and lateral moves are immediate, while downgrades take effect at the next\nrenewal date.\n", "operationId": "getLicenseProductOfferingOptions", "tags": [ "Licenses" ], "parameters": [ { "in": "path", "name": "licenseId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the license." } ], "responses": { "200": { "description": "Available change options.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOfferingOption" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/licenses/{licenseId}/cancel": { "post": { "summary": "Cancel license", "description": "Cancel a license.\n\nThis endpoint allows cancelling a license with an optional scheduled date.\nThe cancellation will take effect according to the specified schedule or immediately if no schedule is provided.\n", "operationId": "cancelLicense", "tags": [ "Licenses" ], "parameters": [ { "in": "path", "name": "licenseId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the license." }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelLicenseRequest" } } } }, "responses": { "200": { "description": "License cancellation scheduled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/License" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/product-catalogs": { "get": { "summary": "List product catalogs", "description": "List all product catalogs with optional text search filtering and pagination.\n\nProduct catalogs define curated sets of product offerings for specific contexts such as customer segments, regions, or sales channels.\n", "operationId": "listProductCatalogs", "tags": [ "Product Catalogs" ], "parameters": [ { "in": "query", "name": "filter", "schema": { "type": "string" }, "description": "Filter by catalog name or ID prefix." }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A list of product catalogs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCatalogListItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/product-offerings": { "get": { "summary": "List product offerings", "description": "List all product offerings available to the customer.\n\nReturns product offerings based on the customer type and access permissions.\n", "operationId": "listProductOfferings", "tags": [ "Product Offerings" ], "parameters": [ { "in": "query", "name": "types", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductType" } }, "description": "Filter by product offering types." }, { "in": "query", "name": "categories", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCategory" } }, "description": "Filter by product offering categories." }, { "in": "query", "name": "customerType", "required": true, "schema": { "$ref": "#/components/schemas/CustomerType" }, "description": "Filter by customer type." }, { "in": "query", "name": "productCatalogId", "schema": { "type": "string" }, "description": "Filter by product catalog. Returns only product offerings that belong to the specified catalog.\nWhen combined with other filters, all filters are applied together.\n", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, { "in": "query", "name": "includeArchived", "schema": { "type": "boolean", "default": false }, "description": "Whether to include archived product offerings." }, { "in": "query", "name": "countries", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by country coverage using ISO 3166-1 alpha-3 codes.\nReturns offerings that provide coverage in any of the specified countries.\nThis includes offerings that have the country explicitly listed or are part of a region that includes the country.\n", "example": [ "USA", "CAN", "MEX" ] }, { "in": "query", "name": "regions", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by region coverage.\nReturns offerings that provide coverage in any of the specified regions.\nRetrieve the available region identifiers from the List Travel eSIM countries endpoint.\n", "example": [ "EUROPE", "NORTH_AMERICA" ] }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A list of product offerings.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductOffering" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "example": { "items": [ { "productOfferingId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "status": "AVAILABLE", "name": "Seamless 10GB", "description": "Mobile plan with 10GB data and unlimited calls and texts", "product": { "productId": "d4e5f6a7-b8c9-0123-4567-890123456789", "internalName": "seamless_cell_10gb_us", "type": "SUBSCRIPTION", "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL", "networkProviderId": "tmobile-us", "features": { "dataMb": 10240, "includedCallSeconds": 36000, "includedSms": 500 } }, "price": { "netPriceMinor": 2999, "currency": "USD", "priceType": "RECURRING", "billingCycle": { "period": "MONTHLY", "interval": 1 }, "standardDiscount": { "amountMinor": 500 }, "bindingContract": { "duration": { "unit": "MONTHS", "value": 12 }, "discount": { "amountMinor": 200 } }, "customUpfrontPayment": { "billingCycles": 3, "discount": { "amountMinor": 300 } }, "currencyOptionsMinor": { "USD": 2999, "SEK": 29900 } }, "group": { "productOfferingGroupId": "mobile-plans", "name": "Mobile Plans", "category": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL" }, "customerType": "BUSINESS", "imageUrl": "https://cdn.example.com/images/seamless-10gb.png" } ], "pagination": { "nextCursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/product-offerings/{productOfferingId}": { "get": { "summary": "Get product offering", "description": "Get a product offering by ID.", "operationId": "getProductOffering", "tags": [ "Product Offerings" ], "parameters": [ { "in": "path", "name": "productOfferingId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the product offering." } ], "responses": { "200": { "description": "Product offering details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductOffering" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/product-offerings/countries": { "get": { "summary": "List Travel eSIM countries", "description": "List all countries and regions available across travel eSIM product offerings.\n\nReturns a deduplicated list of countries with their names and ISO codes,\nplus regions that appear on offerings with their constituent country codes.\n", "operationId": "listProductOfferingCountries", "tags": [ "Product Offerings" ], "parameters": [ { "in": "query", "name": "customerType", "required": true, "schema": { "$ref": "#/components/schemas/CustomerType" }, "description": "Filter by customer type." } ], "responses": { "200": { "description": "A list of countries and regions available across product offerings.", "content": { "application/json": { "schema": { "type": "object", "required": [ "countries", "regions" ], "additionalProperties": false, "properties": { "countries": { "type": "array", "items": { "type": "object", "required": [ "code", "name" ], "additionalProperties": false, "properties": { "code": { "type": "string", "description": "ISO 3166-1 alpha-3 country code.", "example": "USA" }, "name": { "type": "string", "description": "The English name of the country.", "example": "United States" } } } }, "regions": { "type": "array", "items": { "type": "object", "required": [ "region", "countries" ], "additionalProperties": false, "properties": { "region": { "type": "string", "description": "The region identifier.", "example": "EUROPE" }, "countries": { "type": "array", "items": { "type": "string" }, "description": "ISO 3166-1 alpha-3 country codes available within this region.", "example": [ "SWE", "DEU", "FRA" ] } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/discounts/promotions/promo-code/{promoCode}": { "get": { "summary": "Get promotion by code", "description": "Look up a promotion by its promotional code to check availability and details.", "operationId": "getPromotion", "tags": [ "Product Discounts" ], "parameters": [ { "in": "path", "name": "promoCode", "required": true, "schema": { "type": "string" }, "description": "The promotional code to look up.", "example": "SUMMER25" } ], "responses": { "200": { "description": "Promotion details including associated discount information.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Promotion" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders": { "post": { "tags": [ "Orders" ], "summary": "Create order", "description": "Create a new order with initial configuration. Orders can be created with minimal information and progressively configured.", "operationId": "createOrder", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" }, "example": { "customerType": "BUSINESS", "customer": { "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479" }, "billing": { "name": "John Doe", "email": "billing@acme.com", "address": { "street": "123 Main Street", "city": "New York", "zip": "10001", "state": "NY", "country": "US" } }, "lineItems": [ { "type": "SUBSCRIPTION", "lineItemId": "line-item-1", "productOfferingId": "mobile-plan-basic", "sim": { "esim": true }, "subscriber": { "name": "John Doe", "email": "john.doe@example.com" } } ], "promoCode": "SUMMER2023", "metadata": { "source": "partner-storefront" } } } } }, "responses": { "201": { "description": "Order created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "state": "PENDING", "customer": { "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479", "customerType": "BUSINESS", "name": "Acme Corporation", "newCustomer": false }, "billing": { "name": "John Doe", "email": "billing@acme.com", "address": { "street": "123 Main Street", "city": "New York", "zip": "10001", "state": "NY", "country": "US" } }, "promoCode": "SUMMER2023", "lineItems": [ { "type": "SUBSCRIPTION", "lineItemId": "line-item-1", "productOfferingId": "mobile-plan-basic", "sim": { "esim": true }, "subscriber": { "name": "John Doe", "email": "john.doe@example.com" }, "status": "PENDING" } ], "pricing": { "subtotalMinor": 2999, "taxAmountMinor": 0, "totalMinor": 2999, "taxIncluded": false, "currency": "USD", "calculatedAt": "2024-01-15T10:00:00Z" }, "validation": { "isValid": false, "lineItemValidation": [ { "lineItemId": "line-item-1", "isValid": false, "missingFields": [ "subscriber.address" ] } ] }, "requirements": { "requiresPayment": "REQUIRED", "requiresPaymentProfile": "NOT_REQUIRED", "requiresSigning": "NOT_REQUIRED" }, "expiresAt": "2024-01-22T10:00:00Z", "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T10:00:00Z", "metadata": { "source": "partner-storefront" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Orders" ], "summary": "List orders", "description": "List orders with optional filtering and pagination.", "operationId": "listOrders", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "state", "in": "query", "description": "Filter by order state", "schema": { "$ref": "#/components/schemas/OrderState" } }, { "name": "userId", "in": "query", "description": "Filter by user ID", "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "description": "Filter by customer. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n", "schema": { "type": "string" } }, { "name": "expiresAfter", "in": "query", "description": "Filter orders expiring after this date", "schema": { "type": "string", "format": "date-time" } }, { "name": "expiresBefore", "in": "query", "description": "Filter orders expiring before this date", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Orders retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderListItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/{orderId}": { "get": { "tags": [ "Orders" ], "summary": "Get order", "description": "Retrieve a specific order by ID with all line items and current status.", "operationId": "getOrder", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "The unique identifier of the order", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "state": "PENDING", "customer": { "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479", "customerType": "BUSINESS", "name": "Acme Corporation", "newCustomer": false }, "billing": { "name": "John Doe", "email": "billing@acme.com", "address": { "street": "123 Main Street", "city": "New York", "zip": "10001", "state": "NY", "country": "US" } }, "promoCode": "SUMMER2023", "lineItems": [ { "type": "SUBSCRIPTION", "lineItemId": "line-item-1", "productOfferingId": "mobile-plan-basic", "sim": { "esim": true }, "subscriber": { "name": "John Doe", "email": "john.doe@example.com", "address": { "street": "123 Main Street", "city": "New York", "zip": "10001", "state": "NY", "country": "US" } }, "status": "PENDING" } ], "pricing": { "subtotalMinor": 2999, "taxAmountMinor": 240, "totalMinor": 3239, "taxIncluded": false, "currency": "USD", "calculatedAt": "2024-01-15T10:30:00Z" }, "validation": { "isValid": true }, "requirements": { "requiresPayment": "REQUIRED", "requiresPaymentProfile": "NOT_REQUIRED", "requiresSigning": "NOT_REQUIRED" }, "expiresAt": "2024-01-22T10:30:00Z", "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T10:30:00Z", "metadata": { "source": "partner-storefront" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "tags": [ "Orders" ], "summary": "Update order", "description": "Update order details (excluding line items). Order must be in PENDING status.", "operationId": "updateOrder", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "The unique identifier of the order", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrderRequest" } } } }, "responses": { "200": { "description": "Order updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/{orderId}/line-items": { "post": { "tags": [ "Orders" ], "summary": "Add line item", "description": "Add a new line item to an order. Order must be in PENDING status.", "operationId": "addOrderLineItem", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "The unique identifier of the order", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddLineItemRequest" } } } }, "responses": { "201": { "description": "Line item added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderLineItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/{orderId}/line-items/{lineItemId}": { "put": { "tags": [ "Orders" ], "summary": "Update line item", "description": "Update a line item configuration. Order must be in PENDING status.", "operationId": "updateOrderLineItem", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "The unique identifier of the order", "schema": { "type": "string" } }, { "name": "lineItemId", "in": "path", "required": true, "description": "The unique identifier of the line item", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLineItemRequest" } } } }, "responses": { "200": { "description": "Line item updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderLineItem" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Orders" ], "summary": "Remove line item", "description": "Remove a line item from an order. Order must be in PENDING status.", "operationId": "removeOrderLineItem", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "The unique identifier of the order", "schema": { "type": "string" } }, { "name": "lineItemId", "in": "path", "required": true, "description": "The unique identifier of the line item", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Line item removed successfully" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/{orderId}/calculate-price": { "post": { "tags": [ "Orders" ], "summary": "Calculate order price", "deprecated": true, "description": "Deprecated. The order's pricing is recalculated on every change and returned as `pricing`\non the order itself; read it from `GET /orders/{orderId}` instead. This endpoint returns\nthat same stored pricing.\n\nInvalid orders cannot be priced. Fetch the order to see validation errors.\n", "operationId": "calculateOrderPrice", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "The unique identifier of the order", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Price calculation completed successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "pricing" ], "additionalProperties": false, "properties": { "pricing": { "$ref": "#/components/schemas/OrderPricing" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/{orderId}/submit": { "post": { "tags": [ "Orders" ], "summary": "Submit order", "description": "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.", "operationId": "submitOrder", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "The unique identifier of the order", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitOrderRequest" }, "example": { "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901" } } } }, "responses": { "200": { "description": "Order submitted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" }, "example": { "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "state": "PROCESSING", "customer": { "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479", "customerType": "BUSINESS", "name": "Acme Corporation", "newCustomer": false }, "billing": { "name": "John Doe", "email": "billing@acme.com", "address": { "street": "123 Main Street", "city": "New York", "zip": "10001", "state": "NY", "country": "US" } }, "promoCode": "SUMMER2023", "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901", "lineItems": [ { "type": "SUBSCRIPTION", "lineItemId": "line-item-1", "productOfferingId": "mobile-plan-basic", "sim": { "esim": true }, "subscriber": { "name": "John Doe", "email": "john.doe@example.com", "address": { "street": "123 Main Street", "city": "New York", "zip": "10001", "state": "NY", "country": "US" } }, "status": "RUNNING" } ], "pricing": { "subtotalMinor": 2999, "taxAmountMinor": 240, "totalMinor": 3239, "taxIncluded": false, "currency": "USD", "calculatedAt": "2024-01-15T10:30:00Z" }, "validation": { "isValid": true }, "requirements": { "requiresPayment": "REQUIRED", "requiresPaymentProfile": "NOT_REQUIRED", "requiresSigning": "NOT_REQUIRED" }, "expiresAt": "2024-01-22T10:30:00Z", "submittedAt": "2024-01-15T14:30:00Z", "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T14:30:00Z", "metadata": { "source": "partner-storefront" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/{orderId}/cancel": { "post": { "tags": [ "Orders" ], "summary": "Cancel order", "description": "Cancel an order before it has been submitted. Only orders in PENDING status can be canceled.\nThis prevents the order from being submitted and cleans up any reserved resources.\n", "operationId": "cancelOrder", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "The unique identifier of the order", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "metadata": { "$ref": "#/components/schemas/Metadata" } } } } } }, "responses": { "200": { "description": "Order canceled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/orders/{orderId}/approve": { "post": { "tags": [ "Orders" ], "summary": "Approve order", "description": "Approve an order that requires admin or manager approval. Only orders in PENDING_APPROVAL\nstatus can be approved. The approving user must have the appropriate role for the approval\ntype required by the order.\n", "operationId": "approveOrder", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "The unique identifier of the order", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveOrderRequest" } } } }, "responses": { "200": { "description": "Order approved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/{orderId}/handoff-token": { "post": { "tags": [ "Orders" ], "summary": "Create order handoff token", "description": "Mint a short-lived token that lets a checkout pick up this draft order, so an\norder built over the API can be configured further and paid by the customer in\na storefront checkout.\n\nThe order must still be open (PENDING or PENDING_PAYMENT). The token expires on\nits own, and it stops working as soon as the order is no longer open. Anyone\nholding the token can view and complete the order, so pass it only to the\nperson the order is for.\n", "operationId": "createOrderHandoffToken", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "The unique identifier of the order", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Handoff token created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderHandoffToken" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/orders/claim-handoff": { "post": { "tags": [ "Orders" ], "summary": "Claim order handoff", "description": "Resolve a handoff token to the order it hands off. A checkout calls this with\nthe token it received and then continues the order under its own session.\n\nFails when the token is unknown or expired, or when the order is no longer open.\n", "operationId": "claimOrderHandoff", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "handoffToken" ], "additionalProperties": false, "properties": { "handoffToken": { "type": "string", "description": "The handoff token to resolve.", "example": "oht_f47ac10b58cc4372a5670e02b2c3d479" } } } } } }, "responses": { "200": { "description": "The order the token hands off", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderHandoffClaim" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/invoices": { "get": { "summary": "List invoices", "description": "Retrieve a paginated list of invoices with optional filtering by status, customer, or date range.", "operationId": "listInvoices", "tags": [ "Invoices" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "customerId", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter invoices by customer IDs", "example": [ "a9b0c1d2-e3f4-5678-9012-789012345678", "b0c1d2e3-f4a5-6789-0123-890123456789" ] }, { "name": "status", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceStatus" } }, "description": "Filter invoices by status", "example": [ "DRAFT", "SENT" ] }, { "name": "fromDate", "in": "query", "schema": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date" }, "description": "Filter invoices created from this date", "example": "2024-01-01" }, { "name": "toDate", "in": "query", "schema": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date" }, "description": "Filter invoices created up to this date", "example": "2024-12-31" }, { "name": "dueDateFrom", "in": "query", "schema": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date" }, "description": "Filter invoices with due date from this date", "example": "2024-01-01" }, { "name": "dueDateTo", "in": "query", "schema": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date" }, "description": "Filter invoices with due date up to this date", "example": "2024-12-31" } ], "responses": { "200": { "description": "Invoices retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/InvoiceListItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "example": { "items": [ { "invoiceId": "094f10ca-616e-441c-b264-9a2305d6692d", "customerId": "456789ab-cdef-0123-4567-89abcdef0123", "invoiceNumber": "INV-2024-001", "status": "SENT", "dueDate": "2024-02-15", "subtotalAmountMinor": 2999, "totalAmountMinor": 3239, "currency": "USD", "sentAt": "2024-01-15T10:00:00Z", "invoiceUrl": "https://invoices.yourapp.com/094f10ca-616e-441c-b264-9a2305d6692d", "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T10:00:00Z" }, { "invoiceId": "123e4567-e89b-12d3-a456-426614174000", "customerId": "456789ab-cdef-0123-4567-89abcdef0123", "invoiceNumber": "INV-2024-002", "status": "PAID", "dueDate": "2024-03-15", "subtotalAmountMinor": 2999, "totalAmountMinor": 3239, "currency": "USD", "sentAt": "2024-02-15T10:00:00Z", "paidAt": "2024-03-10T14:30:00Z", "invoiceUrl": "https://invoices.yourapp.com/123e4567-e89b-12d3-a456-426614174000", "createdAt": "2024-02-15T10:00:00Z", "updatedAt": "2024-03-10T14:30:00Z" } ], "pagination": { "nextCursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/invoices/{invoiceId}": { "get": { "summary": "Get invoice", "description": "Retrieve details of a specific invoice by its identifier, including status, due date, and payment information.", "operationId": "getInvoice", "tags": [ "Invoices" ], "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the invoice to retrieve.", "example": "094f10ca-616e-441c-b264-9a2305d6692d" } ], "responses": { "200": { "description": "Invoice retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/invoices/{invoiceId}/mark-paid": { "post": { "summary": "Mark invoice as paid", "description": "Mark an invoice as paid when you manage your own payment processing.\n\nUse this when you handle payment collection while Telness manages invoice generation and taxation. Only available for invoices in `SENT` or `OVERDUE` status. Triggers subscription renewals and prevents service cancellation.\n", "operationId": "markInvoiceAsPaid", "tags": [ "Invoices" ], "parameters": [ { "in": "path", "name": "invoiceId", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the invoice to mark as paid.", "example": "123e4567-e89b-12d3-a456-426614174000" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkInvoiceAsPaidRequest" } } } }, "responses": { "200": { "description": "Invoice successfully marked as paid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payment-links": { "get": { "summary": "List payment links", "description": "Get a list of payment links.", "operationId": "listPaymentLinks", "tags": [ "Payment Links" ], "parameters": [ { "name": "status", "in": "query", "description": "Filter by payment link status.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLinkStatus" } } }, { "name": "customerId", "in": "query", "description": "Filter by customer ID.", "schema": { "type": "string" } }, { "name": "orderId", "in": "query", "description": "Filter by order ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "List of payment links.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "summary": "Create payment link", "description": "Create a new payment link that can be shared with customers to collect payments.\n\nPayment links provide a hosted checkout experience without requiring integration\nwith payment widgets or handling sensitive payment data directly.\n\nThe order must be complete and ready for submission — an order that would fail\nsubmission validation is rejected before any payment is collected. Once the\npayment succeeds, the order is submitted automatically.\n", "operationId": "createPaymentLink", "tags": [ "Payment Links" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkRequest" }, "example": { "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "description": "Pay for your mobile subscription order", "savePaymentProfile": true, "returnUrl": "https://example.com/order/confirmation", "cancelUrl": "https://example.com/order/checkout" } } } }, "responses": { "201": { "description": "Payment link created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" }, "example": { "paymentLinkId": "j47ac10b-58cc-4372-a567-0e02b2c3d479", "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "customerId": "a47ac10b-58cc-4372-a567-0e02b2c3d479", "paymentProvider": "STRIPE", "hostedUrl": "https://checkout.example.com/pay/j47ac10b-58cc-4372-a567-0e02b2c3d479", "status": "ACTIVE", "description": "Pay for your mobile subscription order", "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T10:00:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payment-links/{paymentLinkId}": { "get": { "summary": "Get payment link", "description": "Retrieve details of a specific payment link.", "operationId": "getPaymentLink", "tags": [ "Payment Links" ], "parameters": [ { "name": "paymentLinkId", "in": "path", "required": true, "description": "The unique identifier for the payment link.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment link details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payment-links/{paymentLinkId}/cancel": { "post": { "summary": "Cancel payment link", "description": "Cancel an active payment link, preventing further payment attempts through the link.", "operationId": "cancelPaymentLink", "tags": [ "Payment Links" ], "parameters": [ { "name": "paymentLinkId", "in": "path", "required": true, "description": "The unique identifier for the payment link.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Payment link details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payment-intents": { "get": { "summary": "List payment intents", "description": "Retrieve a paginated list of payment intents with optional filtering by status, customer, or date range.", "operationId": "listPaymentIntents", "tags": [ "Payment Intents" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "customerId", "in": "query", "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter payment intents by customer IDs", "example": [ "e7f8a9b0-c1d2-3456-7890-567890123456", "f8a9b0c1-d2e3-4567-8901-678901234567" ] }, { "name": "status", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentIntentStatus" } }, "description": "Filter payment intents by status" } ], "responses": { "200": { "description": "Payment intents retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentIntentListItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payment-intents/{paymentIntentId}": { "get": { "summary": "Get payment intent", "description": "Get a payment intent by ID, including its charge attempts, refunds, and line items.", "operationId": "getPaymentIntent", "tags": [ "Payment Intents" ], "parameters": [ { "name": "paymentIntentId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the payment intent to retrieve.", "example": "64870b5c-fb61-4c9a-955a-e148e0826c20" } ], "responses": { "200": { "description": "Payment intent retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentIntent" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payment-sessions": { "post": { "summary": "Create payment session", "description": "Create a new payment session to collect payment information for an order. For orders with a\npositive total, this initiates payment collection. For zero-total orders, consider creating a\npayment profile session instead. The order must be complete and ready for submission — an order\nthat would fail submission validation is rejected before any payment is collected. Once the\npayment succeeds, the order is submitted automatically.\n\nSet hosted to false to collect the payment inside your own checkout page. The response then\ncarries providerContext instead of hostedUrl. Only this call returns providerContext, because\nit contains a credential that is not stored. To show the form again, create a new session.\n", "operationId": "createPaymentSession", "tags": [ "Payment Sessions" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentSessionRequest" }, "example": { "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "paymentProvider": "STRIPE", "savePaymentProfile": true, "returnUrl": "https://example.com/order/confirmation", "cancelUrl": "https://example.com/order/checkout", "metadata": { "source": "web-checkout" } } } } }, "responses": { "201": { "description": "Payment session created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSession" }, "example": { "paymentSessionId": "d2e3f4a5-b6c7-8901-2345-012345678901", "orderId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "paymentProvider": "STRIPE", "savePaymentProfile": true, "hostedUrl": "https://payments.example.com/checkout/d2e3f4a5-b6c7-8901-2345-012345678901", "returnUrl": "https://example.com/order/confirmation", "cancelUrl": "https://example.com/order/checkout", "status": "PENDING", "metadata": { "source": "web-checkout" }, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:30:00Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payment-sessions/{paymentSessionId}": { "get": { "summary": "Get payment session", "description": "Retrieve details of a specific payment session by its identifier.", "operationId": "getPaymentSession", "tags": [ "Payment Sessions" ], "parameters": [ { "name": "paymentSessionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the payment session to retrieve.", "example": "f2a3b4c5-d6e7-8901-2345-012345678901" } ], "responses": { "200": { "description": "Payment session retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payment-sessions/{paymentSessionId}/cancel": { "post": { "summary": "Cancel payment session", "description": "Cancel an active payment session, preventing further payment attempts.", "operationId": "cancelPaymentSession", "tags": [ "Payment Sessions" ], "parameters": [ { "name": "paymentSessionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the payment session to cancel.", "example": "a3b4c5d6-e7f8-9012-3456-123456789012" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPaymentSessionRequest" } } } }, "responses": { "200": { "description": "Payment session canceled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payment-profiles": { "get": { "summary": "List payment profiles for customer", "description": "List saved payment profiles for the customer.", "operationId": "listPaymentProfiles", "tags": [ "Payment Profiles" ], "parameters": [ { "name": "customerId", "in": "query", "required": true, "description": "Filter profiles for a specific customer.", "schema": { "type": "string" }, "example": "d0e1f2a3-b4c5-6789-0123-ef0123456789" } ], "responses": { "200": { "description": "Payment profiles retrieved successfully.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "description": "List of saved payment profiles.", "items": { "$ref": "#/components/schemas/EmbeddedPaymentProfile" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payment-profiles/{paymentProfileId}": { "get": { "summary": "Get payment profile", "description": "Retrieve details of a specific saved payment method by its identifier.", "operationId": "getPaymentProfile", "tags": [ "Payment Profiles" ], "parameters": [ { "name": "paymentProfileId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the payment profile to retrieve.", "example": "e1f2a3b4-c5d6-7890-1234-f01234567890" } ], "responses": { "200": { "description": "Payment profile retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProfile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "summary": "Delete payment profile", "description": "Remove a saved payment method permanently. This action cannot be undone and will prevent future use of this payment profile.\n\nIf a payment profile is set as default for a customer, it must first be changed before deletion.\n", "operationId": "deletePaymentProfile", "tags": [ "Payment Profiles" ], "parameters": [ { "name": "paymentProfileId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the payment profile to delete.", "example": "e1f2a3b4-c5d6-7890-1234-f01234567890" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "204": { "description": "Payment profile deleted successfully" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payment-profiles/sessions": { "post": { "summary": "Create payment profile session", "description": "Create a new payment profile session to set up and save a payment method for future use.\n\nUsed for zero-cost orders where payment collection isn't needed but payment method setup is required.\n", "operationId": "createPaymentProfileSession", "tags": [ "Payment Profile Sessions" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentProfileSessionRequest" } } } }, "responses": { "201": { "description": "Payment profile session created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProfileSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "412": { "$ref": "#/components/responses/PreconditionFailed" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payment-profiles/sessions/{paymentProfileSessionId}": { "get": { "summary": "Get payment profile session", "description": "Retrieve details of a specific payment profile session by its identifier.", "operationId": "getPaymentProfileSession", "tags": [ "Payment Profile Sessions" ], "parameters": [ { "name": "paymentProfileSessionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the payment profile session to retrieve.", "example": "b4c5d6e7-f8a9-0123-4567-234567890123" } ], "responses": { "200": { "description": "Payment profile session retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProfileSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/payment-profiles/sessions/{paymentProfileSessionId}/cancel": { "post": { "summary": "Cancel payment profile session", "description": "Cancel an active payment profile session, preventing further setup attempts.", "operationId": "cancelPaymentProfileSession", "tags": [ "Payment Profile Sessions" ], "parameters": [ { "name": "paymentProfileSessionId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the payment profile session to cancel.", "example": "c5d6e7f8-a9b0-1234-5678-345678901234" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelPaymentProfileSessionRequest" } } } }, "responses": { "200": { "description": "Payment profile session canceled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentProfileSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/signing": { "get": { "summary": "List signing sessions", "description": "Retrieve a list of signing sessions with optional filtering by order or status.", "operationId": "listSigningSessions", "x-internal": true, "tags": [ "Signing sessions" ], "parameters": [ { "name": "orderId", "in": "query", "description": "Filter by order ID.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by signing status.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SigningStatus" } } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "List of signing sessions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SigningSession" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "summary": "Create signing session", "description": "Create a new contract signing session for an order that requires legal signature.\n\nThis endpoint initiates the signing process by:\n- Creating a signing session with the specified provider\n- Generating a redirect URL for the user to complete signing\n- Setting up callbacks for completion/failure handling\n\nThe response includes a redirect URL that the user should be sent to complete the signing process.\n", "operationId": "createSigningSession", "x-internal": true, "tags": [ "Signing sessions" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSigningSessionRequest" } } } }, "responses": { "201": { "description": "Signing session created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/signing/providers": { "get": { "summary": "List signing providers", "description": "Retrieve available signing providers and their requirements for signer details.\n\nThis endpoint helps you understand:\n- Which signing providers are available in your configuration\n- What information is required from signers for each provider\n- Which countries and languages are supported by each provider\n- Additional capabilities of each provider\n\nUse this information to build appropriate forms and validation for the signing process.\n", "operationId": "listSigningProviders", "x-internal": true, "tags": [ "Signing sessions" ], "parameters": [ { "name": "country", "in": "query", "description": "Filter providers by supported country code.", "schema": { "type": "string", "example": "SE" } }, { "name": "language", "in": "query", "description": "Filter providers by supported language code.", "schema": { "type": "string", "example": "sv" } } ], "responses": { "200": { "description": "List of available signing providers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items" ], "additionalProperties": false, "properties": { "items": { "type": "array", "description": "Available signing providers and their requirements.", "items": { "$ref": "#/components/schemas/SigningProvider" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/signing/{signingSessionId}": { "get": { "summary": "Get signing session", "description": "Retrieve the details and current status of a specific signing session.", "operationId": "getSigningSession", "x-internal": true, "tags": [ "Signing sessions" ], "parameters": [ { "name": "signingSessionId", "in": "path", "required": true, "description": "The unique identifier for the signing session.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Signing session details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "summary": "Cancel signing session", "description": "Cancel an active signing session.\n\nThis can be used to cancel a signing session that is no longer needed or if the order has been canceled.\nOnce canceled, the signing session cannot be resumed.\n", "operationId": "cancelSigningSession", "x-internal": true, "tags": [ "Signing sessions" ], "parameters": [ { "name": "signingSessionId", "in": "path", "required": true, "description": "The unique identifier for the signing session.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Signing session canceled successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningSession" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/tools/validate-address": { "post": { "summary": "Validate address", "description": "Validate an address and get suggestions for corrections if the address is invalid.\n\nThis is particularly important for US addresses where precise addressing is required\nfor service delivery and regulatory compliance.\n\nDepending on setup, address validation is either shape based (e.g. this looks like an address),\nor verified against an address registry.\n", "operationId": "validateAddress", "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateAddressRequest" } } } }, "responses": { "200": { "description": "Address validation completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidationResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/tools/check-porting-eligibility": { "post": { "summary": "Check number porting eligibility", "description": "Check if a phone number is eligible for porting to this network.\n\nThis helps validate numbers before creating subscription line items with porting details.\nReturns information about the current carrier and porting requirements.\n", "operationId": "checkPortingEligibility", "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckPortingEligibilityRequest" } } } }, "responses": { "200": { "description": "Porting eligibility check completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortingEligibilityResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/tools/get-device-info": { "post": { "summary": "Get device information by IMEI", "description": "Get detailed information about a device using its IMEI number.\n\nThis helps validate device compatibility and capabilities before creating\nsubscription line items. Particularly useful for eSIM activation requirements.\n", "operationId": "getDeviceInfo", "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetDeviceInfoRequest" } } } }, "responses": { "200": { "description": "Device information retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceInfo" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/tools/search-devices": { "post": { "summary": "Find devices by name", "description": "Find devices whose name matches a query, with the capabilities of each one.\n\nUse this when the customer knows their device by its everyday name and not by its IMEI. It\nanswers whether each match supports eSIM, so the customer can pick the right SIM type before\nthey order.\n", "operationId": "searchDevices", "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchDevicesRequest" } } } }, "responses": { "200": { "description": "The matching devices.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceSearchResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/tools/check-network-coverage": { "post": { "summary": "Check network coverage", "description": "Check whether the network serves a location, and how well.\n\nA shopper can read the verdict before they place an order.\n\nNetworks differ in what they can answer. Some place the exact address and grade the signal\nthere. Others read the zip code alone and only qualify the postal area for activation. Read\n`scope` on the response to know which answer you got.\n", "operationId": "checkNetworkCoverage", "tags": [ "Tools" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckNetworkCoverageRequest" } } } }, "responses": { "200": { "description": "Network coverage information retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkCoverage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "501": { "$ref": "#/components/responses/NotImplemented" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/inventory/lease-numbers": { "post": { "summary": "Lease phone numbers", "description": "Reserve phone numbers from inventory for use in orders. This allows customers to choose specific\nnumbers before completing their order.\n\n**Availability**: This feature is part of our premium number selection offering and may not be\navailable for all product offerings. Check the response for availability information.\n\n**Usage Flow**:\n1. Lease numbers to get a lease token\n2. Use the lease token and chosen msisdn in subscription line items\n3. Numbers are automatically released if not used before expiry\n\n**Important**: Leased numbers expire after a short time (typically 1 hour) to\nprevent inventory hoarding.\n", "operationId": "leaseNumbers", "tags": [ "Inventory" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaseNumbersRequest" } } } }, "responses": { "200": { "description": "Numbers leased successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NumberLeaseResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Not enough numbers available or number leasing not available for this product offering.", "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/inventory/sims/{iccid}": { "get": { "summary": "Get SIM details", "description": "Retrieve details of a SIM card from inventory by its ICCID.\n\nFor eSIM cards linked to a subscription, the response includes live installation status\nfrom the network operator, showing whether the profile has been downloaded, installed,\nor enabled on a device.\n", "operationId": "getInventorySim", "tags": [ "Inventory" ], "parameters": [ { "name": "iccid", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ICCID of the SIM card to retrieve.", "example": "8946200508271016579" } ], "responses": { "200": { "description": "SIM details retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventorySim" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/workflows/webhook/{path...}": { "post": { "summary": "Trigger workflow via webhook", "description": "Trigger a registered workflow via webhook. The wildcard path is matched against registered workflow webhook paths.\n\nIf at least one workflow is registered with the matching path, the request body is forwarded to the workflow(s) and a 200 response is returned.\n\nIf no workflows match the provided path, a 400 Bad Request is returned.\n", "operationId": "triggerWorkflowWebhook", "security": [], "tags": [ "Workflows" ], "parameters": [ { "name": "path...", "in": "path", "required": true, "description": "The wildcard webhook path to match against registered workflows. Leading slashes in the workflow registration are ignored, so `support/intents/reward/topup` and `/support/intents/reward/topup` are equivalent.\n\nThis is a greedy path parameter, meaning it captures the entire remainder of the URL path.\n", "schema": { "type": "string" }, "example": "support/intents/reward/topup" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "description": "The webhook payload. Can be any valid JSON object. The payload data is passed to the matching workflow(s) which can access and use any properties from it.\n", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "responses": { "200": { "description": "Webhook successfully delivered to at least one registered workflow.", "content": { "application/json": { "schema": { "type": "object", "required": [ "workflowTasks" ], "additionalProperties": false, "properties": { "workflowTasks": { "type": "array", "description": "List of workflow tasks that were triggered by this webhook.", "items": { "$ref": "#/components/schemas/EmbeddedWorkflowTask" } } }, "example": { "workflowTasks": [ { "workflowTaskId": "f47ac10b-58cc-4372-a567-0e2b2c3d479", "name": "Reward customer with data top-up", "description": "Rewards a customer's subscription with the specified data top-up product offering.", "createdAt": "2024-01-15T10:35:00Z" } ] } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/reports": { "get": { "summary": "List reports", "description": "List platform-generated report runs for a given report key, newest first.\n\nOnly report runs created within the last 30 days are returned.\n", "operationId": "listReportRuns", "tags": [ "Reports" ], "parameters": [ { "in": "query", "name": "reportKey", "required": true, "schema": { "type": "string" }, "description": "The key identifying the report to list runs for." }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ], "responses": { "200": { "description": "A list of report runs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ReportRun" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "example": { "items": [ { "reportRunId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "reportKey": "subscriber_base_and_revenue", "status": "SUCCEEDED", "downloadUrl": "https://example-bucket.s3.amazonaws.com/reports/f47ac10b.csv?X-Amz-Signature=...", "createdAt": "2024-01-10T08:00:00Z", "completedAt": "2024-01-10T08:02:31Z" } ], "pagination": { "nextCursor": null } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/reports/{reportRunId}": { "get": { "summary": "Get report", "description": "Retrieve a generated report by its identifier. Once the report has finished generating, the response includes a time-limited link to download the file directly.", "operationId": "getReportRun", "tags": [ "Reports" ], "parameters": [ { "in": "path", "name": "reportRunId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "The identifier of the report run." } ], "responses": { "200": { "description": "A report run object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportRun" }, "example": { "reportRunId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "reportKey": "subscriber_base_and_revenue", "status": "SUCCEEDED", "downloadUrl": "https://example-bucket.s3.amazonaws.com/reports/f47ac10b.csv?X-Amz-Signature=...", "createdAt": "2024-01-10T08:00:00Z", "completedAt": "2024-01-10T08:02:31Z" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "webhooks": { "subscription.created": { "post": { "operationId": "onSubscriptionCreated", "summary": "Subscription created", "description": "Sent when a new subscription has been successfully created.\n", "tags": [ "Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.created", "description": "The event type identifier." }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Subscription snapshot at the time of this event." } } } ] } } } }, "responses": { "200": { "description": "Webhook acknowledged - no further retries will be attempted." }, "4XX": { "description": "Temporary failure - delivery will be retried with backoff." }, "5XX": { "description": "Temporary failure - delivery will be retried with backoff." } } } }, "subscription.updated": { "post": { "operationId": "onSubscriptionUpdated", "summary": "Subscription updated", "description": "Sent when mutable fields on an existing subscription are changed (e.g. status transition, product offering change, MSISDN assignment, metadata updates).\n", "tags": [ "Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.updated", "description": "The event type identifier." }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Subscription snapshot at the time of this event." } } } ] } } } }, "responses": { "200": { "description": "Webhook acknowledged - no further retries will be attempted." }, "4XX": { "description": "Temporary failure - delivery will be retried with backoff." }, "5XX": { "description": "Temporary failure - delivery will be retried with backoff." } } } }, "subscription.cancelled": { "post": { "operationId": "onSubscriptionCancelled", "summary": "Subscription cancelled", "description": "Sent when a subscription cancellation is confirmed (end-of-term or immediate as applicable).\n", "tags": [ "Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.cancelled" }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Subscription snapshot at the time of this event." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "subscription.activated": { "post": { "operationId": "onSubscriptionActivated", "summary": "Subscription activated", "description": "Sent when a subscription enters ACTIVE state.\n", "tags": [ "Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.activated" }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Current subscription in ACTIVE state." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "subscription.first_activated": { "post": { "operationId": "onSubscriptionFirstActivated", "summary": "Subscription first activated", "description": "Sent the first time a subscription enters ACTIVE state. A later activation sends\n`subscription.activated` instead, so this event marks the start of the subscription\nand arrives one time only.\n", "tags": [ "Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.first_activated" }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Subscription in ACTIVE state, at its first activation." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "subscription.suspended": { "post": { "operationId": "onSubscriptionSuspended", "summary": "Subscription suspended", "description": "Sent when a subscription is suspended. A suspended subscription keeps its number and\nits plan, and the network refuses its traffic until a restore.\n", "tags": [ "Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.suspended" }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Subscription after the suspension." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "subscription.paused": { "post": { "operationId": "onSubscriptionPaused", "summary": "Subscription paused", "description": "Sent when a subscription is paused. A paused subscription keeps its number and its\nplan, and it does not renew until a restore.\n", "tags": [ "Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.paused" }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Subscription after the pause." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "subscription.restored": { "post": { "operationId": "onSubscriptionRestored", "summary": "Subscription restored", "description": "Sent when a subscription returns to service after a pause or a suspension.\n", "tags": [ "Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.restored" }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Subscription after the restore." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "subscription.renewed": { "post": { "operationId": "onSubscriptionRenewed", "summary": "Subscription renewed", "description": "Sent when a subscription successfully renews into a new billing period/term.\n", "tags": [ "Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.renewed" }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Subscription snapshot at start of new term/period." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "subscription.ended": { "post": { "operationId": "onSubscriptionEnded", "summary": "Subscription ended", "description": "Sent when a subscription reaches its final end (no longer billable / usable).\n", "tags": [ "Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.ended" }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Final subscription state." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "subscription.portIn.created": { "post": { "operationId": "onSubscriptionPortInCreated", "summary": "Subscription port-in initiated", "description": "Sent when a port-in request is created for a subscription.\n", "tags": [ "Subscription Port-In" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.portIn.created" }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Subscription snapshot including porting embed." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "subscription.portIn.updated": { "post": { "operationId": "onSubscriptionPortInUpdated", "summary": "Subscription port-in updated", "description": "Sent when port-in details (schedule, status) change.\n", "tags": [ "Subscription Port-In" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.portIn.updated" }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Updated subscription snapshot (porting section changed)." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "subscription.portIn.completed": { "post": { "operationId": "onSubscriptionPortInCompleted", "summary": "Subscription port-in completed", "description": "Sent when the number porting completes successfully.\n", "tags": [ "Subscription Port-In" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.portIn.completed" }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Subscription snapshot at the time of this event." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "subscription.portIn.failed": { "post": { "operationId": "onSubscriptionPortInFailed", "summary": "Subscription port-in failed", "description": "Sent when a number port-in attempt fails irrecoverably or requires manual intervention.\n", "tags": [ "Subscription Port-In" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.portIn.failed" }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Subscription snapshot including failed porting state." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "subscription.quotaNotification": { "post": { "operationId": "onSubscriptionQuotaNotification", "summary": "Subscription quota threshold exceeded", "description": "Sent when a subscription quota threshold is exceeded (e.g. 80%, 100% of data, SMS, or voice allowance).\n", "tags": [ "Subscription Usage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.quotaNotification" }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Subscription snapshot at the time of this event." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "subscription.subscriber_set": { "post": { "operationId": "onSubscriptionSubscriberSet", "summary": "Subscription subscriber set", "description": "Sent when a subscriber is assigned to a subscription.\n", "tags": [ "Subscriptions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "subscription.subscriber_set" }, "data": { "$ref": "#/components/schemas/Subscription", "description": "Subscription snapshot at the time of this event." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "license.created": { "post": { "operationId": "onLicenseCreated", "summary": "License created", "description": "Sent when a license is created.\n", "tags": [ "Licenses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "license.created" }, "data": { "$ref": "#/components/schemas/License", "description": "License snapshot." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "license.updated": { "post": { "operationId": "onLicenseUpdated", "summary": "License updated", "description": "Sent when a license changes.\n", "tags": [ "Licenses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "license.updated" }, "data": { "$ref": "#/components/schemas/License", "description": "Updated license snapshot." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "license.cancelled": { "post": { "operationId": "onLicenseCancelled", "summary": "License cancelled", "description": "Sent when a license cancellation is confirmed.\n", "tags": [ "Licenses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "license.cancelled" }, "data": { "$ref": "#/components/schemas/License", "description": "License snapshot at the time of this event." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "license.activated": { "post": { "operationId": "onLicenseActivated", "summary": "License activated", "description": "Sent when a license becomes ACTIVE.\n", "tags": [ "Licenses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "license.activated" }, "data": { "$ref": "#/components/schemas/License", "description": "Active license snapshot." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "license.renewed": { "post": { "operationId": "onLicenseRenewed", "summary": "License renewed", "description": "Sent when a license renews into a new term/period.\n", "tags": [ "Licenses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "license.renewed" }, "data": { "$ref": "#/components/schemas/License", "description": "License snapshot at renewal." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "license.ended": { "post": { "operationId": "onLicenseEnded", "summary": "License ended", "description": "Sent when a license reaches final end state.\n", "tags": [ "Licenses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "license.ended" }, "data": { "$ref": "#/components/schemas/License", "description": "Final license snapshot." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "order.created": { "post": { "operationId": "onOrderCreated", "summary": "Order created", "description": "Sent when an order is created.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "order.created" }, "data": { "$ref": "#/components/schemas/Order", "description": "Order snapshot at creation." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "order.updated": { "post": { "operationId": "onOrderUpdated", "summary": "Order updated", "description": "Sent when an order changes (line items, metadata, pricing recalculation).\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "order.updated" }, "data": { "$ref": "#/components/schemas/Order", "description": "Updated order snapshot." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "order.cancelled": { "post": { "operationId": "onOrderCancelled", "summary": "Order cancelled", "description": "Sent when an order is cancelled.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "order.cancelled" }, "data": { "$ref": "#/components/schemas/Order", "description": "Cancelled order snapshot." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "order.statusChanged": { "post": { "operationId": "onOrderStatusChanged", "summary": "Order status changed", "description": "Sent when an order status transitions (e.g. PENDING -\u003e SUBMITTED, PROCESSING -\u003e COMPLETED, etc.).\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "order.statusChanged" }, "data": { "$ref": "#/components/schemas/Order", "description": "Order snapshot at the time of this event." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "order.submitted": { "post": { "operationId": "onOrderSubmitted", "summary": "Order submitted", "description": "Sent when an order is formally submitted for processing/fulfillment.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "order.submitted" }, "data": { "$ref": "#/components/schemas/Order", "description": "Order snapshot at submission." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "order.expired": { "post": { "operationId": "onOrderExpired", "summary": "Order expired", "description": "Sent when an order expires before completion.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "order.expired" }, "data": { "$ref": "#/components/schemas/Order", "description": "Expired order snapshot." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "order.lineItemStatusChanged": { "post": { "operationId": "onOrderLineItemStatusChanged", "summary": "Order line item status changed", "description": "Sent when a single line item within an order changes fulfillment status\n(e.g. PENDING -\u003e RUNNING -\u003e COMPLETED or RUNNING -\u003e FAILED).\n\nTriggered independently of the order's overall status; an order can complete\nwhile individual line items continue running or end in FAILED.\n", "tags": [ "Orders" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "order.lineItemStatusChanged" }, "data": { "type": "object", "required": [ "order", "lineItemId", "status" ], "additionalProperties": false, "properties": { "order": { "$ref": "#/components/schemas/Order", "description": "Order snapshot at the time of this event." }, "lineItemId": { "type": "string", "description": "The line item within the order whose status changed.", "example": "line-item-1" }, "status": { "$ref": "#/components/schemas/OrderLineItemStatus" } } } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "customer.created": { "post": { "operationId": "onCustomerCreated", "summary": "Customer created", "description": "Sent when a new customer is created in the system.\n", "tags": [ "Customers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "customer.created", "description": "The event type identifier." }, "data": { "$ref": "#/components/schemas/Customer", "description": "Customer snapshot at the time of this event." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "customer.updated": { "post": { "operationId": "onCustomerUpdated", "summary": "Customer updated", "description": "Sent when customer information is modified, including profile changes, billing updates, or status changes.\n", "tags": [ "Customers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "customer.updated", "description": "The event type identifier." }, "data": { "$ref": "#/components/schemas/Customer", "description": "Customer snapshot at the time of this event." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "customer.deleted": { "post": { "operationId": "onCustomerDeleted", "summary": "Customer deleted", "description": "Sent when a customer account is permanently deleted from the system.\n", "tags": [ "Customers" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "customer.deleted", "description": "The event type identifier." }, "data": { "$ref": "#/components/schemas/Customer", "description": "Customer snapshot at the time of this event." } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } }, "report.ready": { "post": { "operationId": "onReportReady", "summary": "Report ready", "description": "Sent when a report has finished generating and its file is ready to download. Fetch the report by its identifier to obtain a time-limited download link.\n", "tags": [ "Reports" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "report.ready", "description": "The event type identifier." }, "data": { "$ref": "#/components/schemas/ReportRun", "description": "The report that just became ready, including a time-limited download link." } } } ] } } } }, "responses": { "200": { "description": "Webhook acknowledged - no further retries will be attempted." }, "4XX": { "description": "Temporary failure - delivery will be retried with backoff." }, "5XX": { "description": "Temporary failure - delivery will be retried with backoff." } } } }, "custom.workflow_triggered": { "post": { "operationId": "onCustomWorkflowTriggered", "summary": "Custom workflow triggered", "description": "Sent from within a workflow and content is defined by the workflow configuration.\n", "tags": [ "Custom" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EventEnvelope" }, { "type": "object", "required": [ "type", "data" ], "properties": { "type": { "type": "string", "const": "custom.workflow_triggered", "description": "The event type identifier." }, "data": { "type": "array", "description": "A list of key value pairs defined by the workflow configuration. Always includes a \"customType\" entry with the custom event type (e.g. \"telna.esim_status_change\").", "items": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "description": "The key of the data item." }, "value": { "type": "string", "description": "The value of the data item." } } } } } } ] } } } }, "responses": { "200": { "description": "Acknowledged" }, "4XX": { "description": "Temporary failure - will retry" }, "5XX": { "description": "Temporary failure - will retry" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Bearer authentication with JWT tokens is used to authenticate users.\n\nDo note that a valid API keys is also required to access the API to prove that requests are made by a trusted party.\n\nRequests with a JWT token is scoped to the permissions of the user the token belongs to, regardless of the API key used.\n" }, "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "An API key that grants access to the API. You can create and manage API keys in the portal.\n" } }, "schemas": { "StartEmailLoginRequest": { "type": "object", "description": "Request to initiate an email-based login flow. A verification code will be sent to the provided email address.", "required": [ "email" ], "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "description": "The email address to send the verification code to.", "example": "john.doe@example.com" } } }, "StartEmailLoginResponse": { "type": "object", "description": "Response from initiating an email login. Contains the nonce needed for verification and timing information.", "required": [ "nonce", "expiresIn", "createdAt", "expiresAt" ], "properties": { "nonce": { "type": "string", "description": "Token to reference this authentication request during verification.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "expiresIn": { "type": "integer", "description": "Number of seconds until the verification code expires.", "example": 300 }, "createdAt": { "type": "string", "format": "date-time", "description": "When the authentication request was created.", "example": "2024-01-15T10:30:00Z" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the verification code will expire.", "example": "2024-01-15T10:35:00Z" } } }, "Any": { "description": "A string, number, boolean, object, or array value. The concrete type depends on the field the value is returned for.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object", "additionalProperties": true }, { "type": "array" } ] }, "Error": { "type": "object", "description": "The error body returned by every endpoint when a request fails. Use `internalCode` for programmatic\nhandling, show `message` to a human, and check `details` for field-level problems when the request\nwas invalid.\n", "required": [ "message", "code" ], "properties": { "message": { "type": "string", "description": "A human-readable message providing more details about the error.", "example": "The requested customer could not be found." }, "code": { "type": "string", "deprecated": true, "description": "Deprecated. Use `internalCode`.\n\nThis field mixes three unrelated codes and does not say which one you have: a code that we\npublish, an operator's own code when the failure came from an operator, or the request status\nwhen there is neither. Do not branch on it.\n", "example": "not_found" }, "internalCode": { "type": "string", "description": "Names the condition that failed, from our own registry. It is independent of which system\nreported the failure and of the HTTP status, and it is stable across releases. Branch on this\nfield. An unexpected failure on our side can carry no code. Then use the HTTP status.\n", "example": "4009" }, "details": { "type": "array", "description": "Additional details about the error, typically one entry per invalid field on validation failures.", "items": { "type": "object", "required": [ "message", "code" ], "properties": { "message": { "type": "string", "description": "A human-readable message providing more details about the error.", "example": "Email format is invalid." }, "code": { "type": "string", "description": "A machine-readable code for the specific detail.", "example": "invalid_email" }, "property": { "type": "string", "description": "The property or field related to the error. May be nested using dot notation (e.g., \"billing.email\").", "example": "contact.email" }, "suggestion": { "$ref": "#/components/schemas/Any", "description": "A suggested value for the particular property.\n\nFor example, this may be set when validating an address with an alias, suggesting the expected value by the operator.\n" } } } }, "hint": { "type": "string", "description": "A hint to help resolve the error.", "example": "Verify the customerId and try again." }, "traceId": { "type": "string", "description": "Identifies the trace this request produced. Quote it when reporting a failure — it is what\nlets us find the request among everything else the platform served.\n", "example": "cc4a73acca1bb07e0e54bd41f5ce1e7e" }, "spanId": { "type": "string", "description": "The span within the trace that failed.", "example": "37cec694d3b99f0f" } } }, "VerifyEmailLoginRequest": { "type": "object", "description": "Request to verify an email login by providing the verification code sent to the email address.", "required": [ "email", "nonce", "code" ], "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "description": "The email address used to initiate the login.", "example": "john.doe@example.com" }, "nonce": { "type": "string", "description": "The nonce returned from the start login request.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "code": { "type": "string", "pattern": "^[0-9]{6}$", "description": "The 6-digit verification code sent to the email address.", "example": "123456" } } }, "TokenResponse": { "type": "object", "description": "OAuth2-compatible token response containing the access token for authenticating API requests.", "required": [ "accessToken", "tokenType", "expiresIn" ], "properties": { "accessToken": { "type": "string", "description": "JWT access token for authenticating API requests. Include in the Authorization header as \"Bearer {accessToken}\".", "example": "\u003caccess-token\u003e" }, "tokenType": { "type": "string", "enum": [ "Bearer" ], "description": "The type of token issued. Always \"Bearer\" for JWT tokens.", "example": "Bearer" }, "expiresIn": { "type": "integer", "description": "Number of seconds until the access token expires.", "example": 604800 }, "userId": { "type": "string", "description": "The unique identifier of the authenticated user.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } } }, "Identity": { "type": "string", "description": "A government or company registration identifier for the entity, such as a personal identification number\nfor consumers or an organization number for businesses. The expected format depends on the country and\ncustomer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number.\n", "example": "12-3456789" }, "EmbeddedCustomer": { "type": "object", "description": "Customer information embedded in responses. Sensitive details require separate API calls with appropriate authorization.", "required": [ "customerId", "name" ], "properties": { "customerId": { "type": "string", "description": "The unique identifier for the customer. Use it with the customer endpoints to fetch full details.", "example": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" }, "name": { "type": "string", "description": "The customer's display name — the company name for business customers or the person's full name for consumers.", "example": "John Doe" } } }, "Metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format.\nProvided by API clients and returned as-is; the platform does not interpret the values.\n" }, "User": { "type": "object", "description": "A person who can sign in and manage one or more customers' accounts.\n\nUsers are distinct from subscribers: a user administers customers and their services, while a subscriber is the end user of a subscription.\n", "required": [ "userId", "name" ], "properties": { "userId": { "type": "string", "description": "Unique identifier for the user.", "example": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e" }, "name": { "type": "string", "description": "The user's full name, shown in account management and used when the user is listed as a customer's contact person.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "The user's email address. This is their sign-in identity — login verification codes are sent to it — and it is used to reach them when they are a customer's contact person.", "example": "john.doe@example.com" }, "msisdn": { "type": "string", "format": "phone", "description": "The user's mobile phone number in E.164 format, used to reach them when they are a customer's contact person.", "example": "+15551234567" }, "identity": { "$ref": "#/components/schemas/Identity" }, "referenceId": { "type": "string", "description": "A reference identifier provided by API clients to identify this user in their\nown systems. Must be unique per tenant. Use this field to look up users or\nto create/retrieve users during order creation.\n", "example": "hr-employee-98765", "maxLength": 255 }, "customers": { "type": "array", "description": "The customers this user is associated with. The user can sign in and act on behalf of each of these customers.", "items": { "$ref": "#/components/schemas/EmbeddedCustomer" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time when the user was created.", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time when the user was last updated.", "example": "2024-01-20T14:45:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "Pagination": { "type": "object", "description": "Cursor-based pagination information returned by list endpoints.\nPass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page.\n", "required": [ "nextCursor" ], "properties": { "nextCursor": { "type": [ "string", "null" ], "description": "Opaque token for fetching the next page. Null when no more results.", "example": "eyJvZmZzZXQiOjEwMH0" } } }, "CreateUserRequest": { "type": "object", "description": "The details needed to create a user and associate them with a customer they can manage.\n", "required": [ "name", "email", "customerId" ], "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The user's full name, shown in account management and used when the user is listed as a customer's contact person.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "The user's email address. This becomes their sign-in identity — login verification codes are sent to it.", "example": "john.doe@example.com" }, "msisdn": { "type": "string", "format": "phone", "description": "The user's mobile phone number in E.164 format, used to reach them when they are a customer's contact person.", "example": "+15551234567" }, "role": { "type": "string", "enum": [ "MEMBER", "MANAGER", "ADMIN" ], "default": "MEMBER", "description": "The role of the user when assigned to a customer. Defaults to 'MEMBER' if not specified." }, "customerId": { "type": "string", "description": "The unique identifier for the customer to whom the user will belong. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n", "example": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" }, "referenceId": { "type": "string", "description": "A reference identifier provided by API clients to identify this user in their\nown systems. Must be unique per tenant. Use this field to look up users by\nyour external identifier.\n", "example": "hr-employee-98765", "maxLength": 255 }, "identity": { "$ref": "#/components/schemas/Identity" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "UpdateUserRequest": { "type": "object", "description": "The user fields to change. Only provided fields are updated; omitted fields keep their current values.\n", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The user's full name, shown in account management and used when the user is listed as a customer's contact person.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "The user's email address. This is their sign-in identity — changing it changes where login verification codes are sent.", "example": "john.doe@example.com" }, "msisdn": { "type": "string", "format": "phone", "description": "The user's mobile phone number in E.164 format, used to reach them when they are a customer's contact person.", "example": "+15551234567" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "CustomerType": { "type": "string", "description": "Whether the customer is a private individual (CONSUMER) or a company (BUSINESS).\nDetermines the expected identity format and which billing rules apply.\n", "enum": [ "CONSUMER", "BUSINESS" ] }, "CustomerBillingMethod": { "type": "string", "enum": [ "E_INVOICE", "EMAIL_INVOICE", "PAPER_INVOICE" ], "description": "How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE).\nEMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address.\n" }, "Address": { "type": "object", "description": "A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks.\n", "required": [ "street1", "city", "zip", "country" ], "properties": { "street": { "type": "string", "description": "The first line of the address, typically street and house number.", "example": "500 S Main St" }, "street1": { "type": "string", "deprecated": true, "description": "Deprecated. Use `street` instead.\n\nThe first line of the address, typically street and house number.\n" }, "street2": { "type": "string", "description": "The second line of the address, typically apartment, suite, unit, building, floor, etc.", "example": "Apt 1" }, "city": { "type": "string", "description": "The city or municipality of the address.", "example": "Natick" }, "zip": { "type": "string", "description": "The zip code of the address.\n\nDepending on the country, this may be referred to as a postal code or postcode.\n\nSpecifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').\n", "example": "01701" }, "country": { "type": "string", "description": "The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).", "pattern": "^[A-Z]{2}$", "example": "US" }, "state": { "type": "string", "description": "For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).", "example": "CA" }, "region": { "type": "string", "description": "A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan).", "example": "Ontario" }, "attention": { "type": "string", "description": "An optional line for specifying a person, department, or attention to a specific entity within an address.", "example": "John Doe" } } }, "Currency": { "type": "string", "description": "The three-letter ISO 4217 code of the currency used for prices, billing, and payments.", "example": "USD" }, "UserRole": { "type": "string", "description": "The user's level of access when managing the customer's account.\nADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access.\n", "enum": [ "MEMBER", "MANAGER", "ADMIN" ] }, "EmbeddedCustomerUser": { "type": "object", "description": "A user associated with a customer, including the role that governs what they can manage on the customer's account.\nContains essential details only — use the user endpoints for the full profile.\n", "required": [ "userId", "name" ], "properties": { "userId": { "type": "string", "description": "Unique identifier for the user. Use it with the user endpoints to fetch full details.", "example": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e" }, "name": { "type": "string", "description": "The user's full name.", "example": "John Doe" }, "role": { "$ref": "#/components/schemas/UserRole" } } }, "Shipping": { "type": "object", "description": "Shipping information for order fulfillment. Only required if the order contains shippable items.", "required": [ "name", "address" ], "properties": { "name": { "type": "string", "description": "Full name of the person or department receiving the delivery, printed on the shipping label.", "example": "John Doe" }, "msisdn": { "type": "string", "format": "phone", "description": "Phone number the carrier can use to reach the recipient about the delivery.", "example": "+15551234567" }, "address": { "$ref": "#/components/schemas/Address" }, "instructions": { "type": "string", "description": "Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.", "example": "Leave at front door" } } }, "Customer": { "type": "object", "description": "A customer is a billable entity, the person or organization responsible for paying for services.\n\nThe customer is the owner of subscribers and subscriptions. Users are associated with a customer, but are not owned by the customer.\n", "required": [ "customerId", "customerType", "name", "contact" ], "properties": { "customerId": { "type": "string", "description": "Unique identifier for the customer.", "example": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" }, "customerType": { "$ref": "#/components/schemas/CustomerType" }, "name": { "type": "string", "description": "The customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API.", "example": "John Doe" }, "identity": { "$ref": "#/components/schemas/Identity" }, "preferredLocale": { "type": "string", "description": "The preferred locale for the customer, in IETF BCP 47 format (e.g., \"en-US\", \"sv-SE\").", "example": "en-US", "default": "en-US" }, "humanReadableId": { "type": "string", "description": "A human-readable identifier for the customer that customers can state in support requests.\n", "example": "29A-BY3Z-X78" }, "referenceId": { "type": "string", "description": "A reference identifier provided by API clients to identify this customer in their\nown systems. Must be unique per tenant. Use this field to look up customers or\nto create/retrieve customers during order creation.\n", "example": "crm-customer-12345", "maxLength": 255 }, "contact": { "type": "object", "description": "Contact details for the customer.", "properties": { "email": { "type": "string", "format": "email", "description": "The primary contact email for the customer.", "example": "john.doe@example.com" }, "msisdn": { "type": "string", "format": "phone", "description": "The primary contact phone number for the customer.", "example": "+15551234567" } } }, "billing": { "type": "object", "description": "Billing configuration and payment preferences for the customer.", "required": [ "method", "currency" ], "additionalProperties": false, "properties": { "method": { "$ref": "#/components/schemas/CustomerBillingMethod", "description": "How invoices should be delivered to the customer." }, "email": { "type": "string", "format": "email", "description": "The email address to send invoices to.\nRequired if billing method is EMAIL_INVOICE.\n", "example": "billing@company.com" }, "address": { "$ref": "#/components/schemas/Address", "description": "The billing address for the customer.\nRequired if billing method is PAPER_INVOICE.\n" }, "currency": { "$ref": "#/components/schemas/Currency", "description": "The currency for customer billing and payments." }, "defaultPaymentProfileId": { "type": "string", "description": "Default payment profile to use for automatic payments and new orders.\nIf specified, enables automatic payment collection for invoices and bills.\n", "example": "c1d2e3f4-a5b6-7890-1234-901234567890" }, "autoPay": { "type": "boolean", "description": "Whether the customer authorized automatic charges to their default payment profile.\nAn automatic charge also needs an active default payment profile that works off-session.\n", "example": true, "default": false } } }, "users": { "type": "array", "description": "The users associated with this customer, each with the role that governs what they can manage on the customer's account.", "items": { "$ref": "#/components/schemas/EmbeddedCustomerUser" } }, "contactPerson": { "$ref": "#/components/schemas/EmbeddedCustomerUser", "description": "The primary contact person for the customer." }, "shipping": { "$ref": "#/components/schemas/Shipping", "description": "The shipping address for the customer.\n\nThis address is used for shipping physical goods to the customer, such as SIM cards or devices.\nIt is also used to pre-fill the address when ordering physical goods.\n" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "ShippingInput": { "type": "object", "description": "Shipping information for order fulfillment. Only required if the order contains shippable items.", "required": [ "name", "address" ], "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Full name of the person or department receiving the delivery, printed on the shipping label.", "example": "John Doe" }, "msisdn": { "type": "string", "format": "phone", "description": "Phone number the carrier can use to reach the recipient about the delivery.", "example": "+15551234567" }, "address": { "$ref": "#/components/schemas/Address" }, "instructions": { "type": "string", "description": "Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference.", "example": "Leave at front door" } } }, "CreateCustomerRequest": { "type": "object", "description": "The details needed to create a customer: who they are, how to reach them, how they should be billed, and which users can manage the account.\n", "required": [ "customerType", "name", "contact", "billing", "contactPersonUserId", "userIds" ], "additionalProperties": false, "properties": { "customerType": { "$ref": "#/components/schemas/CustomerType" }, "name": { "type": "string", "description": "The customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API.", "example": "John Doe" }, "identity": { "$ref": "#/components/schemas/Identity" }, "referenceId": { "type": "string", "description": "Optional reference ID to assign to the customer.\nMust be unique per tenant.\n", "example": "crm-customer-12345", "maxLength": 255 }, "preferredLocale": { "type": "string", "description": "The preferred locale for the customer, in IETF BCP 47 format (e.g., \"en-US\", \"sv-SE\").", "example": "en-US", "default": "en-US" }, "contact": { "type": "object", "description": "Contact details for the customer.", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "The primary contact email for the customer.", "example": "john.doe@example.com" }, "msisdn": { "type": "string", "format": "phone", "description": "The primary contact phone number for the customer.", "example": "+15551234567" } } }, "billing": { "type": "object", "description": "Billing configuration and payment preferences for the customer.", "required": [ "method", "currency" ], "additionalProperties": false, "properties": { "method": { "$ref": "#/components/schemas/CustomerBillingMethod", "description": "How invoices should be delivered to the customer." }, "email": { "type": "string", "format": "email", "description": "The email address to send invoices to.\nRequired if billing method is EMAIL_INVOICE.\n", "example": "billing@company.com" }, "address": { "$ref": "#/components/schemas/Address", "description": "The billing address for the customer. Used for invoicing and tax calculation.\n" }, "currency": { "$ref": "#/components/schemas/Currency", "description": "The currency for customer billing and payments." }, "defaultPaymentProfileId": { "type": "string", "description": "Default payment profile to use for automatic payments and new orders.\nMust be a payment profile that will be accessible to this customer.\n", "example": "l47ac10b-58cc-4372-a567-0e02b2c3d479" }, "autoPay": { "type": "boolean", "description": "Whether to automatically charge the default payment profile for invoices and bills.\nRequires defaultPaymentProfileId to be set.\n", "example": true, "default": false } } }, "userIds": { "type": "array", "description": "List of user IDs to associate with this customer.\n\nDepending on the user's role they will either be a member of the customer or given access to manage it.\n", "items": { "type": "string" } }, "contactPersonUserId": { "type": "string", "description": "The user ID of the contact person for this customer.\n\nThis user will be set as the primary contact for the customer and will receive important notifications.\n", "example": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e" }, "shipping": { "$ref": "#/components/schemas/ShippingInput", "description": "The default shipping address for the customer.\n\nThis address is used for shipping physical goods to the customer, such as SIM cards or devices.\nIt is also used to pre-fill the address when ordering physical goods.\n" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "UpdateCustomerRequest": { "type": "object", "description": "The customer fields to change. Only provided fields are updated; omitted fields keep their current values.\n", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "The customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API.", "example": "John Doe" }, "identity": { "$ref": "#/components/schemas/Identity" }, "preferredLocale": { "type": "string", "description": "The preferred locale for the customer, in IETF BCP 47 format (e.g., \"en-US\", \"sv-SE\").", "example": "en-US" }, "contact": { "type": "object", "description": "Contact details for the customer.", "properties": { "email": { "type": "string", "format": "email", "description": "The primary contact email for the customer.", "example": "john.doe@example.com" }, "msisdn": { "type": "string", "format": "phone", "description": "The primary contact phone number for the customer.", "example": "+15551234567" } } }, "billing": { "type": "object", "description": "Billing details for the customer.", "properties": { "method": { "$ref": "#/components/schemas/CustomerBillingMethod" }, "email": { "type": "string", "format": "email", "description": "The email address to send invoices to.\n\nRequired if billing method is EMAIL_INVOICE.\n", "example": "billing@example.com" }, "address": { "$ref": "#/components/schemas/Address", "description": "The billing address for the customer.\n\nRequired if billing method is PAPER_INVOICE.\n" }, "currency": { "$ref": "#/components/schemas/Currency", "description": "The currency for the customer billing." }, "defaultPaymentProfileId": { "type": "string", "description": "Default payment profile to use for automatic payments and new orders.\nMust be a valid payment profile owned by this customer.\nSet to null to disable automatic payments.\n", "example": "m47ac10b-58cc-4372-a567-0e02b2c3d479" }, "autoPay": { "type": "boolean", "description": "Whether to automatically pay invoices for this customer if a valid payment method is available.", "example": false } } }, "userIds": { "type": "array", "description": "User IDs to associate with this customer, in addition to those already associated.\n\nDepending on the user's role they will either be a member of the customer or given access to manage it.\nTo remove a user, use the remove-user endpoint instead.\n", "items": { "type": "string" } }, "shippingAddress": { "$ref": "#/components/schemas/Address", "description": "The shipping address for the customer.\n\nThis address is used for shipping physical goods to the customer, such as SIM cards or devices.\nIt is also used to pre-fill the address when ordering physical goods.\n" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "ProductCategory": { "type": "string", "x-extensible-enum": true, "description": "A product category is a sub-type for grouping offerings of the same type.\n\nTypically, product offerings of the same type with the same category allow\nfor switching between them. For upgrading and downgrading subscriptions and\nlicenses, we recommend using their corresponding endpoints though.\n\nCategories are grouped by their product type:\n\n**SUBSCRIPTION categories:**\n- `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription\n- `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription\n- `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription\n- `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription\n- `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming\n\n**SUBSCRIPTION_ADDON categories:**\n- `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon\n- `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage\n- `PRODUCT_CATEGORY_ABROAD` - International roaming addon\n\n**EXTERNAL_PRODUCT categories:**\n- `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product\n- `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product\n\n**SIM_CARD categories:**\n- `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription\n", "enum": [ "PRODUCT_CATEGORY_SUBSCRIPTION_CELL", "PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM", "PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND", "PRODUCT_CATEGORY_SUBSCRIPTION_M2M", "PRODUCT_CATEGORY_TRAVEL_ESIM", "PRODUCT_CATEGORY_EXTRA_DATA", "PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE", "PRODUCT_CATEGORY_ABROAD", "PRODUCT_CATEGORY_EXTERNAL_PRODUCT", "PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON", "PRODUCT_CATEGORY_SIM_CARD" ], "example": "PRODUCT_CATEGORY_SUBSCRIPTION_CELL" }, "ProductOfferingGroup": { "type": "object", "description": "A product group organizes related product offerings.", "required": [ "productOfferingGroupId", "name", "category" ], "properties": { "productOfferingGroupId": { "type": "string", "description": "Unique identifier for the product group.", "example": "mobile-plans" }, "name": { "type": "string", "description": "Name of the product group in the requested locale.", "example": "Mobile Plans" }, "description": { "type": "string", "description": "Description of the product group in the requested locale.", "example": "Bundled cell subscriptions with unlimited calls and SMS with ILD enabled." }, "category": { "$ref": "#/components/schemas/ProductCategory" }, "internalDescription": { "type": "string", "description": "Internal description of the product group for operational use only.", "example": "Core mobile offerings targeting consumer and business segments" } } }, "ProductType": { "type": "string", "x-extensible-enum": true, "description": "The type of product offering determines how it can be used and what kind of resource it creates.\n\n**SUBSCRIPTION**\nCreates a standalone subscription resource (e.g., mobile plan, broadband, travel eSIM).\n- Includes categories like `SUBSCRIPTION_CELL`, `TRAVEL_ESIM`\n- Can be created via order or directly depending on configuration\n- Has its own lifecycle (activation, suspension, termination)\n\n**SUBSCRIPTION_ADDON**\nAdds features or resources to an existing subscription.\n- Includes categories like `TRAVEL_ESIM_PACKAGE`\n- Must be attached to a parent subscription\n\n**LICENSE**\nCreates a license for business/PBX features.\n- Typically used for enterprise telephony features\n\n**EXTERNAL_PRODUCT**\nRepresents purchasable items outside the core telecom platform.\n- Can only be ordered via orders, not created directly\n\n**SIM_CARD**\nReplaces the SIM card for an existing subscription through a subscription change order.\n", "enum": [ "SUBSCRIPTION", "SUBSCRIPTION_ADDON", "LICENSE", "EXTERNAL_PRODUCT", "SIM_CARD" ], "example": "SUBSCRIPTION" }, "EmbeddedProduct": { "type": "object", "description": "Embedded representation of a product.", "required": [ "productId", "internalName", "type", "category" ], "properties": { "productId": { "type": "string", "description": "The unique identifier for the product.", "example": "d4e5f6a7-b8c9-0123-4567-890123456789" }, "internalName": { "type": "string", "description": "The name used to identify the product internally in the catalog. Not intended for customer display — use the product offering name instead.", "example": "us-mobile-unlimited-5gb" }, "type": { "$ref": "#/components/schemas/ProductType" }, "category": { "$ref": "#/components/schemas/ProductCategory" }, "networkProviderId": { "type": "string", "description": "The unique identifier for the network provider.", "example": "tmobile-us" }, "features": { "type": "object", "description": "The features included with the product, if any. Typically used for telecom products.", "properties": { "dataMb": { "type": "number", "description": "Megabytes of data included with the product.\nPresent for cellular, data, and travel eSIM products.\n", "example": 2048 }, "includedCallSeconds": { "type": "integer", "description": "Outbound call seconds included with the product.\nPresent for cellular subscription categories.\n", "example": 1000 }, "includedSms": { "type": "integer", "description": "Number of SMS messages included with the product.\nPresent for cellular subscription categories.\n", "example": 500 }, "validityDays": { "type": "integer", "description": "Number of days the product is valid for.\nPresent for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`).\n", "example": 30 }, "countries": { "type": "array", "items": { "type": "string" }, "description": "ISO 3166-1 alpha-3 country codes where the product provides coverage.\nPresent for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`).\nUse the `countries` query parameter on list endpoints to filter by coverage.\n", "example": [ "USA", "CAN", "MEX" ] }, "regions": { "type": "array", "items": { "type": "string" }, "description": "Named regions covered by the product.\nPresent for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`).\nUse the `regions` query parameter on list endpoints to filter by coverage.\n", "example": [ "NORTH_AMERICA" ] }, "activationType": { "type": "string", "description": "How the travel eSIM package activates.\nPresent for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`).\n", "enum": [ "INSTANT", "FIRST_USE" ], "example": "INSTANT" }, "simCardType": { "type": "string", "description": "The SIM format for a SIM card product.", "enum": [ "PSIM", "ESIM" ], "example": "PSIM" } } } } }, "PriceType": { "type": "string", "description": "How the price is charged.\n\n- ONE_TIME: Charged once (e.g., a setup fee or hardware purchase).\n- RECURRING: Charged every billing cycle (e.g., a monthly subscription fee).\n", "enum": [ "ONE_TIME", "RECURRING" ] }, "Duration": { "type": "object", "description": "A length of time, expressed as a count of some unit.", "required": [ "unit", "value" ], "properties": { "unit": { "type": "string", "description": "The unit of time being counted. Currently only months are supported.", "enum": [ "MONTHS" ] }, "value": { "type": "integer", "description": "How many of the unit the duration lasts.", "example": 3 } } }, "PriceDiscount": { "type": "object", "description": "A recurring amount that comes off the price when you price the order. The amount applies to one\nbilling period, the same as the price, and it is not a total. For example, a discount of 500 for\n3 periods takes 500 off each of the first three periods, and 1500 in all.\n", "required": [ "amountMinor" ], "properties": { "amountMinor": { "type": "integer", "format": "int64", "description": "The amount that comes off each billing period, in minor currency units.", "example": 500 }, "duration": { "$ref": "#/components/schemas/Duration", "description": "How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it\ncovers the billing cycles that the customer pays for in advance. The other two sources omit\nthe duration when the discount never stops. The discount then comes off every charge for as\nlong as the price is in effect. For a one-time price that is the single charge.\n" }, "source": { "type": "string", "description": "What the customer must do to get the discount:\n\n- `STANDARD` is given to every customer who orders the offering.\n- `BINDING_CONTRACT` needs the customer to commit for the contract's length.\n- `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once.\n", "enum": [ "STANDARD", "BINDING_CONTRACT", "UPFRONT_PAYMENT" ], "example": "STANDARD" }, "invoicingDescription": { "type": "string", "description": "What the brand calls this discount on an invoice. Omitted when the brand gave the discount\nno name of its own.\n", "example": "Campaign discount" } } }, "BindingContract": { "type": "object", "description": "A commitment to keep the subscription for a fixed term, usually in exchange\nfor a discount that runs for the length of the commitment.\n", "required": [ "duration" ], "properties": { "duration": { "$ref": "#/components/schemas/Duration" }, "discount": { "$ref": "#/components/schemas/PriceDiscount" } } }, "UpfrontPayment": { "type": "object", "description": "Billing cycles the customer pays for in advance when ordering, usually at a discount.\nBilling returns to the normal cycle once the prepaid cycles run out.\n", "required": [ "billingCycles" ], "properties": { "billingCycles": { "type": "integer", "description": "How many billing cycles are paid for upfront. This counts cycles, not months: three\ncycles of a price that bills quarterly covers nine months.\n", "example": 3 }, "discount": { "$ref": "#/components/schemas/PriceDiscount" } } }, "BillingCycle": { "type": "object", "description": "How often a recurring price is charged.", "required": [ "period", "interval" ], "properties": { "period": { "type": "string", "description": "The unit of time between charges. Currently only monthly billing is supported.", "enum": [ "MONTHLY" ] }, "interval": { "type": "integer", "description": "The quantity of periods between charges. For example, a MONTHLY period with an interval of\n1 bills each month, and an interval of 3 bills each three months.\n", "example": 1 } } }, "Price": { "type": "object", "description": "The cost of a product offering, as configured in the catalog. A price is either one-time or\nrecurring, and the priceType field tells you which. Amounts are integers in the minor units of\nthe currency. For example, 2999 is $29.99 when the currency is USD.\n", "required": [ "currency", "priceType" ], "properties": { "netPrice": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `netPriceMinor` instead.\n\nThe configured price of the offering, in major currency units.\n", "example": 29.99 }, "netPriceMinor": { "type": "integer", "format": "int64", "description": "The configured price of the offering, in minor currency units.", "example": 2999 }, "currency": { "type": "string", "description": "The ISO 4217 currency code the price is expressed in (e.g., \"USD\").", "example": "USD" }, "priceType": { "$ref": "#/components/schemas/PriceType" }, "bindingContract": { "$ref": "#/components/schemas/BindingContract" }, "standardDiscount": { "$ref": "#/components/schemas/PriceDiscount" }, "customUpfrontPayment": { "$ref": "#/components/schemas/UpfrontPayment" }, "billingCycle": { "$ref": "#/components/schemas/BillingCycle" }, "currencyOptions": { "type": "object", "additionalProperties": { "type": "number", "format": "decimal" }, "deprecated": true, "description": "Deprecated. Use `currencyOptionsMinor` instead.\n\nPer-currency price overrides keyed by three-letter ISO currency code (e.g. \"USD\", \"SEK\"). Each value is the cost in that currency, in major currency units.\n" }, "currencyOptionsMinor": { "type": "object", "additionalProperties": { "type": "integer", "format": "int64" }, "description": "Per-currency price overrides keyed by three-letter ISO currency code (e.g. \"USD\", \"SEK\"). Each value is the cost in that currency, in minor currency units." }, "boundMonths": { "type": "integer", "deprecated": true, "description": "Deprecated. Use `bindingContract.duration` instead.\n\nLength of the binding period in months for recurring prices. The customer commits to this price for the given number of months; absent when there is no binding period.\n" } } }, "ProductOffering": { "type": "object", "description": "A product offering is a product combined with a price that is offered to customers.\n\nThe offering's `type` and `category` are available via the nested `product` object.\nSee ProductType and ProductCategory schemas for available values and their meanings.\n", "required": [ "productOfferingId", "status", "name", "price", "customerType", "product" ], "properties": { "productOfferingId": { "type": "string", "description": "Unique identifier for the product offering.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "status": { "type": "string", "enum": [ "AVAILABLE", "ARCHIVED" ], "description": "The status of the product offering.\n\nArchived offerings are not allowed to be created/ordered by customers, but can still be used for existing subscriptions.\n", "example": "AVAILABLE" }, "name": { "type": "string", "description": "Name of the product offering.", "example": "Seamless 10GB" }, "description": { "type": "string", "description": "Description of the product offering.", "example": "Basic mobile plan with 5GB data and unlimited calls" }, "richContent": { "type": "string", "description": "Rich HTML content with detailed information about the product offering.", "example": "\u003ch3\u003eFeatures\u003c/h3\u003e\u003cul\u003e\u003cli\u003e5GB monthly data\u003c/li\u003e\u003cli\u003eUnlimited calls \u0026 texts\u003c/li\u003e\u003cli\u003eNo setup fees\u003c/li\u003e\u003c/ul\u003e" }, "uspList": { "type": "array", "items": { "type": "string" }, "description": "Short plain-text selling points, in the order the brand put them. A storefront shows them as a checklist.\n", "example": [ "5GB of data every month", "Unlimited calls and texts", "No setup fee" ] }, "product": { "$ref": "#/components/schemas/EmbeddedProduct" }, "price": { "$ref": "#/components/schemas/Price" }, "group": { "$ref": "#/components/schemas/ProductOfferingGroup" }, "customerType": { "$ref": "#/components/schemas/CustomerType" }, "addonCategories": { "type": "array", "items": { "$ref": "#/components/schemas/ProductCategory" }, "description": "List of product categories this addon is applicable for.\nOnly populated when type is `SUBSCRIPTION_ADDON`.\nFor example, a `TRAVEL_ESIM_PACKAGE` addon might be applicable to `TRAVEL_ESIM` subscriptions.\n" }, "internalDescription": { "type": "string", "description": "Internal description of the product offering for operational use only.", "example": "seamless_cell_10gb_us" }, "imageUrl": { "type": "string", "format": "uri", "description": "URL to the image representing the product offering.", "example": "https://cdn.example.com/images/mobile-basic.png" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "SubscriptionStatus": { "type": "string", "description": "Current stage of the subscription lifecycle.\n\n- PENDING: Created but not yet activated in the network\n- ACTIVATED: Active and billable; service is available\n- BLOCKED: Service disabled by the operator, typically for fraud prevention or policy violations\n- CANCELLED: Permanently terminated\n- PAUSED: Temporarily stopped at the customer's request; billing stops and service is disabled\n- SUSPENDED: Temporarily disabled, typically for payment issues; billing continues but service is disabled\n", "enum": [ "PENDING", "ACTIVATED", "BLOCKED", "CANCELLED", "PAUSED", "SUSPENDED" ] }, "SubscriptionType": { "type": "string", "description": "The kind of telecommunications service the subscription provides.\n\nCommon values include `CELL` (mobile voice/SMS/data), `DATA` (data-only SIM), `MBB` (mobile broadband),\n`M2M` (machine-to-machine/IoT), and `TRAVEL_ESIM` (travel eSIM for international roaming).\nDetermined by the product offering the subscription was created with.\n", "example": "CELL" }, "EmbeddedProductOffering": { "type": "object", "description": "Essential information about a product offering — what is being sold and at what price — without the full catalog details.", "required": [ "productOfferingId", "name", "price" ], "properties": { "productOfferingId": { "type": "string", "description": "The unique identifier for the product offering. Use it with the product offering endpoints to fetch full details.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "name": { "type": "string", "description": "The customer-facing name of the product offering, suitable for display in checkout and account views.", "example": "Mobile Unlimited" }, "price": { "$ref": "#/components/schemas/Price" }, "group": { "$ref": "#/components/schemas/ProductOfferingGroup" }, "imageUrl": { "type": "string", "format": "uri", "description": "URL to the image representing the product offering.", "example": "https://cdn.example.com/images/mobile-basic.png" } } }, "EmbeddedSubscriber": { "type": "object", "description": "The person who uses the service on a subscription, as distinct from the customer who pays for it.", "required": [ "subscriberId", "name" ], "properties": { "subscriberId": { "type": "string", "description": "The unique identifier of the subscriber. Use it with the subscriber endpoints to fetch full details.", "example": "d0e1f2a3-b4c5-6789-0123-456789012345" }, "name": { "type": "string", "description": "The subscriber's full name.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "The subscriber's email address, if one has been provided.", "example": "john.doe@example.com" }, "address": { "description": "The address of the subscriber.\n\nIn the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.\n", "$ref": "#/components/schemas/Address" }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time when the subscriber was created.", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time when the subscriber was last updated.", "example": "2024-01-20T14:45:00Z" } } }, "PortingStatus": { "type": "string", "enum": [ "PENDING", "IN_PROGRESS", "SCHEDULED", "COMPLETED", "FAILED" ], "description": "Current status of the porting process.\n\n- PENDING: Porting request created but not yet submitted to the carriers\n- IN_PROGRESS: Request submitted and awaiting a response from the losing carrier\n- SCHEDULED: Accepted by the losing carrier; the transfer will execute on the scheduled date\n- COMPLETED: The number has been transferred and is active\n- FAILED: The request was rejected, canceled, or could not be completed\n" }, "PortingDirection": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "The direction of the number transfer. INBOUND means the number is being ported into this platform from another carrier; OUTBOUND means the number is leaving this platform for another carrier." }, "EmbeddedPorting": { "type": "object", "description": "Number porting information for subscriptions, indicating scheduled number transfers.\n\nTo get the detailed porting information, use the porting endpoint.\n", "required": [ "msisdn", "status", "direction", "scheduledAt" ], "properties": { "msisdn": { "type": "string", "description": "The pending phone number that the subscription will be ported in with. This will always be a non-active number.", "example": "+15551234567" }, "status": { "$ref": "#/components/schemas/PortingStatus" }, "direction": { "$ref": "#/components/schemas/PortingDirection" }, "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the number porting is scheduled to occur.", "example": "2024-02-01" } } }, "Subscription": { "type": "object", "description": "A subscription represents a telecommunications service provisioned for a customer with embedded product and pricing details.", "required": [ "subscriptionId", "status", "type", "display", "msisdn", "sim", "customer", "createdAt", "updatedAt" ], "properties": { "subscriptionId": { "type": "string", "description": "The unique identifier for the subscription.", "example": "d8174435-6378-4be5-a9f5-8b4aaadae5d4" }, "referenceId": { "type": "string", "description": "A reference identifier provided by API clients to identify this subscription in their\nown systems. Must be unique per tenant. Use this field to look up subscriptions by your\nexternal identifier or to create/retrieve subscriptions during order creation.\n", "example": "crm-subscription-12345", "maxLength": 255 }, "status": { "$ref": "#/components/schemas/SubscriptionStatus" }, "type": { "$ref": "#/components/schemas/SubscriptionType" }, "display": { "type": "string", "description": "Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.", "example": "(555) 123-4567" }, "msisdn": { "type": "string", "format": "phone", "description": "The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.", "example": "+15551234567" }, "customer": { "$ref": "#/components/schemas/EmbeddedCustomer" }, "productOffering": { "$ref": "#/components/schemas/EmbeddedProductOffering" }, "subscriber": { "$ref": "#/components/schemas/EmbeddedSubscriber" }, "extensions": { "type": "object", "description": "Additional subscription extensions fields provided for custom subscription types.", "additionalProperties": { "type": "string" } }, "sim": { "type": "object", "description": "SIM card information for the subscription. Sensitive details like PUK require separate API calls.\n\nUse dedicated SIM API endpoints with proper authorization to access sensitive information such as PUK.\n", "required": [ "esim" ], "properties": { "esim": { "type": "boolean", "description": "Whether the subscription uses eSIM (embedded SIM) technology, a digital SIM profile downloaded to the device, instead of a physical SIM card.", "example": true }, "imei": { "type": "string", "description": "International Mobile Equipment Identity (IMEI), the 15-digit number that uniquely identifies the mobile device hardware.\n\nOnly applicable for eSIM.\n", "example": "356938035643809" }, "iccid": { "type": "string", "description": "Integrated Circuit Card Identifier (ICCID), the 19-20 digit serial number that uniquely identifies the SIM card (or eSIM profile) in use.", "example": "8901240197155182976" } } }, "pendingMsisdn": { "type": "object", "required": [ "msisdn" ], "description": "A phone number change that has been requested but not yet applied. Present only while a number change is scheduled; the current number remains in `msisdn` until the change takes effect.", "properties": { "msisdn": { "type": "string", "format": "phone", "description": "The phone number the subscription will switch to when the scheduled change takes effect, in E.164 format.", "example": "+15559876543" }, "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the pending number change is scheduled to occur.", "example": "2024-02-01" } } }, "pendingStatus": { "type": "object", "required": [ "status" ], "description": "A status change that has been requested but not yet applied, for example a scheduled cancellation or pause. Present only while a status change is scheduled.", "properties": { "status": { "$ref": "#/components/schemas/SubscriptionStatus" }, "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the pending status change is scheduled to occur.", "example": "2024-02-01" } } }, "pendingProductOffering": { "type": "object", "description": "A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in `productOffering` until the scheduled date.", "required": [ "scheduledAt", "product" ], "properties": { "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the pending product offering change is scheduled to occur.", "example": "2024-02-01" }, "product": { "$ref": "#/components/schemas/EmbeddedProductOffering" } } }, "porting": { "$ref": "#/components/schemas/EmbeddedPorting" }, "activatedAt": { "type": "string", "format": "date-time", "description": "The date and time when the subscription was activated. Absent until the subscription has been activated.", "example": "2024-01-15T10:30:00Z" }, "cancelledAt": { "type": "string", "format": "date-time", "description": "The date and time when the subscription was cancelled (if applicable).", "example": "2024-06-30T00:00:00Z" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time when the subscription was created.", "example": "2024-01-10T08:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time when the subscription was last updated.", "example": "2024-01-15T10:30:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "PortingDetailsUS": { "title": "USPortingDetails", "type": "object", "description": "Information required to port a US phone number. Provide firstName, lastName, and address in the\ninitial request; accountNumber and passcode (often called a Number Transfer PIN) may be omitted at\nfirst but must be supplied before the port can be activated. US carriers validate a transfer\nagainst the losing carrier's account records, and mismatches are the most common cause of rejected\nports, so these values must match the losing carrier's records exactly.\n", "required": [ "firstName", "lastName", "address" ], "properties": { "accountNumber": { "type": "string", "description": "The account number with the current provider.\n\nIf not provided here, must be provided in the future for activation on-demand.\n", "example": "987654321" }, "passcode": { "type": "string", "description": "The passcode or PIN associated with the account at the current provider, often called a\nNumber Transfer PIN or port-out PIN. Most US carriers require the account holder to generate\nthis in their account settings before the number can be released.\n\nIf not provided here, must be provided in the future for activation on-demand.\n", "example": "123456" }, "firstName": { "type": "string", "description": "The first name of the account holder at the current provider.", "example": "John" }, "lastName": { "type": "string", "description": "The last name of the account holder at the current provider.", "example": "Doe" }, "address": { "$ref": "#/components/schemas/Address" } } }, "PortingDetailsSweden": { "title": "SwedishPortingDetails", "type": "object", "description": "Information required to port a Swedish phone number. Swedish carriers approve a transfer based on\nthe national identity number of the number's current owner, so no account number or PIN is needed.\n", "required": [ "identity" ], "properties": { "identity": { "type": "string", "description": "The identity of the number's current owner as registered with the losing carrier: a Swedish\npersonal identity number (personnummer) for individuals, or a company registration number\n(organisationsnummer) for businesses. The transfer is rejected if this does not match the\nlosing carrier's records.\n", "example": "199001011234" } } }, "PortingDetails": { "description": "Ownership and account information the carriers need to approve a number transfer. The required\ninformation varies by country: provide US details for US numbers and Swedish details for Swedish numbers.\n", "oneOf": [ { "$ref": "#/components/schemas/PortingDetailsUS" }, { "$ref": "#/components/schemas/PortingDetailsSweden" } ] }, "SubscriptionActivation": { "type": "object", "description": "Configuration and details required to activate a subscription in the telecommunications network.\n\nThis includes the phone number (MSISDN), SIM card details, and optional number porting information.\nAll subscriptions require this activation data before they can be used for telecommunications services.\n", "additionalProperties": false, "required": [ "sim" ], "properties": { "msisdn": { "type": "string", "description": "The phone number for this subscription.\n\n- Leave empty to have a number automatically assigned from the available pool\n- Provide a specific number when using a leased number from the number pool\n- Provide the number to be ported when transferring from another carrier\n", "example": "+15551234567" }, "leaseToken": { "type": "string", "description": "Token received when leasing a number from the available number pool.\n\nRequired only when providing a specific msisdn that was leased from the number pool.\nNot needed for auto-assigned numbers or ported numbers.\n", "example": "lease_abc123def456" }, "porting": { "type": "object", "description": "Details required to port (transfer) an existing phone number from another carrier.\n\nProvide this when the subscriber wants to keep their existing phone number.\nThe porting process may take several days depending on the carrier and regulatory requirements.\n", "required": [ "details" ], "properties": { "details": { "$ref": "#/components/schemas/PortingDetails" } } }, "sim": { "type": "object", "description": "SIM card technology and configuration for this subscription.", "required": [ "esim" ], "additionalProperties": false, "properties": { "esim": { "type": "boolean", "description": "Whether this subscription uses eSIM (embedded SIM) technology.\n\n- true: Digital eSIM profile will be provisioned to the device\n- false: Physical SIM card will be used\n", "example": true }, "iccid": { "type": "string", "description": "Integrated Circuit Card Identifier (ICCID) of an existing SIM card.\n\nProvide this when activating a subscription with a pre-existing physical SIM card.\nOnly applicable to certain networks that support BYO (Bring Your Own) SIM.\n", "example": "8931440400000000000" } } }, "deliveryAddress": { "$ref": "#/components/schemas/Address", "description": "The address a physical SIM card is posted to.\n\nAn eSIM subscription needs no delivery address. The address the\nsubscription is served at is separate, and a delivery address does not\nchange it.\n" } } }, "CreateSubscriptionRequest": { "type": "object", "description": "Create a new subscription for a customer.\n\n**Activation Options:**\n1. **Immediate activation**: Provide activation data without scheduleActivationAt\n2. **Scheduled activation**: Provide activation data with scheduleActivationAt for future activation\n3. **Shell subscription**: Omit activation data to create a subscription that will be activated later\n\n**When to use shell subscriptions:**\n- When activation details are not yet available (e.g., waiting for SIM card delivery)\n- When activation requires additional approval or processing\n- When bulk-creating subscriptions for later activation\n\nNote: This endpoint is disabled when Seamless OS manages billing. In that case, subscriptions are created through orders.\n", "required": [ "productOfferingId", "customerId", "subscriber" ], "additionalProperties": false, "properties": { "productOfferingId": { "type": "string", "description": "The unique identifier for the product offering to subscribe to.\n\nThis controls what type of subscription is being created.\n", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "customerId": { "type": "string", "description": "The identifier of the existing customer who will own this subscription. Accepts\neither an internal UUID or an external referenceId previously assigned to the\ncustomer.\n", "example": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" }, "referenceId": { "type": "string", "description": "Optional reference ID to assign to the subscription. Must be unique per tenant.\nOnce set, this value can be used in place of the subscriptionId in path parameters\nand request bodies across the API.\n", "example": "crm-subscription-12345", "maxLength": 255 }, "activation": { "description": "Everything needed to bring the subscription online in the mobile network: the phone number\n(a specific number, a leased number, or empty for automatic assignment), the SIM configuration\n(eSIM or physical SIM), and optional porting details when the subscriber keeps their existing\nnumber from another carrier.\n\n**When to provide:**\n- Provide activation details to have the subscription provisioned in the network — immediately,\n or on the date given in `scheduleActivationAt`\n- Omit to create a \"shell\" subscription that stays in PENDING status until you activate it later\n via POST /subscriptions/{subscriptionId}/activate, for example when SIM or porting details are\n not yet known\n", "allOf": [ { "$ref": "#/components/schemas/SubscriptionActivation" }, { "type": "object", "description": "Activation configuration for this subscription.\n\n**When to provide:**\n- Provide activation details to create an active subscription immediately or scheduled for the future\n- Omit to create a \"shell\" subscription that must be activated later via the activate endpoint\n\n**Use cases:**\n- **Immediate activation**: Provide activation data without scheduleActivationAt\n- **Scheduled activation**: Provide activation data with scheduleActivationAt set to a future date\n- **Deferred activation**: Omit activation data entirely - use the activate endpoint later when ready\n" } ] }, "scheduleActivationAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Date when the subscription should be activated in the network.\n\nOnly applicable when activation data is provided. If omitted, activation will be immediate or as soon as network resources are available.\n\n**Note**: Network availability and porting timelines may affect the exact activation time. This date is a preference, not a guarantee.\n", "example": "2024-01-15" }, "extensions": { "type": "object", "description": "Additional subscription extensions fields for custom subscription types.", "additionalProperties": { "type": "string" } }, "display": { "type": "string", "description": "Custom display name for the subscription. If not provided, will be auto-generated from msisdn.", "example": "John's work phone" }, "subscriber": { "type": "object", "description": "Subscriber details for this subscription.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The full name of the subscriber.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "The email address of the subscriber.", "example": "john.doe@example.com" }, "address": { "$ref": "#/components/schemas/Address" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "ActivateSubscriptionRequest": { "type": "object", "description": "Request to activate a pending subscription in the telecommunications network.\n\nUse this endpoint to activate subscriptions that were created as \"shells\" without initial activation data,\nor to activate subscriptions that are in a state where network activation is needed.\n\n**Activation timing:**\n- Omit scheduleActivationAt for immediate activation (or as soon as network resources are available)\n- Provide scheduleActivationAt to schedule activation for a future date\n", "additionalProperties": false, "required": [ "activation" ], "properties": { "activation": { "$ref": "#/components/schemas/SubscriptionActivation", "description": "Complete activation configuration required to bring the subscription online in the network.\n\nThis includes the phone number assignment, SIM card details, and any number porting information.\n" }, "scheduleActivationAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Date when the subscription should be scheduled for activation.\n\nIf not provided, activation will be immediate or as soon as possible based on network availability.\n\n**Note**: Network availability and porting timelines may affect exact timing. This date is considered\na preference, not a guarantee. The actual activation may occur on or after this date.\n", "example": "2025-01-01" } } }, "Porting": { "type": "object", "description": "A request to transfer (port) a phone number between carriers, either into this platform from the subscriber's previous carrier or out to another carrier. Tracks the number, the transfer's progress, and the ownership details required by the carriers involved.", "required": [ "msisdn", "status", "direction", "details", "createdAt" ], "properties": { "msisdn": { "type": "string", "description": "The phone number to be ported, in E.164 format.", "example": "+15551234567" }, "status": { "$ref": "#/components/schemas/PortingStatus" }, "direction": { "$ref": "#/components/schemas/PortingDirection" }, "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the porting is scheduled to occur.", "example": "2024-02-01" }, "details": { "$ref": "#/components/schemas/PortingDetails" }, "updatedAt": { "type": "string", "format": "date-time", "description": "The timestamp of the last update to the porting request.", "example": "2024-01-20T09:00:00Z" }, "createdAt": { "type": "string", "format": "date-time", "description": "The timestamp when the porting request was created.", "example": "2024-01-15T10:30:00Z" } } }, "UpdatePortingRequest": { "description": "Request to correct or complete the porting details of a subscription's in-progress port-in,\nfor example after the losing carrier rejected the transfer because the owner details did not match.\n", "type": "object", "required": [ "details" ], "properties": { "details": { "$ref": "#/components/schemas/PortingDetails" } } }, "ChangeSubscriptionProductOfferingRequest": { "type": "object", "description": "Request to change the product offering of a subscription.", "required": [ "productOfferingId" ], "additionalProperties": false, "properties": { "productOfferingId": { "type": "string", "description": "The unique identifier of the new product offering. Use the product-offering-options endpoint to discover which offerings the subscription can be changed to.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.", "example": "2024-02-01" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "ProductOfferingChangeSchedule": { "type": "string", "description": "The schedule type for when a product offering change can take effect.\n\n- INSTANT: Change takes effect immediately\n- FIRST_OF_NEXT_MONTH: Change takes effect on the first day of the next calendar month\n- NEXT_RENEWAL_DAY: Change takes effect on the next renewal date\n- NEXT_PAYMENT_DAY: Change takes effect at the end of the prepaid period, the next payment day\n", "enum": [ "INSTANT", "FIRST_OF_NEXT_MONTH", "NEXT_RENEWAL_DAY", "NEXT_PAYMENT_DAY" ] }, "ProductOfferingOption": { "type": "object", "description": "A product offering option available for subscription changes with scheduling information.", "required": [ "productOffering", "changeSchedule", "changeScheduleDate" ], "properties": { "productOffering": { "$ref": "#/components/schemas/EmbeddedProductOffering" }, "changeSchedule": { "$ref": "#/components/schemas/ProductOfferingChangeSchedule" }, "changeScheduleDate": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the product offering change can take effect.", "example": "2024-02-01" } } }, "SubscriptionAddonStatus": { "type": "string", "description": "The status of an add-on on a subscription.\n\n- PENDING: Add-on is scheduled but not yet active\n- ACTIVE: Add-on is currently active and billable\n- CANCELLED: Add-on has been cancelled and is no longer active\n- EXPIRED: Add-on has expired and is no longer active\n", "enum": [ "PENDING", "ACTIVE", "CANCELLED", "EXPIRED" ] }, "LicenseStatus": { "type": "string", "description": "Current stage of the license lifecycle.\n\n- PENDING: Created but not yet activated\n- ACTIVE: Active and billable; the licensed feature is available\n- PAUSED: Temporarily stopped; the licensed feature is disabled\n- CANCELLED: Permanently terminated\n- BLOCKED: Disabled by the operator, typically for policy or payment reasons\n", "enum": [ "PENDING", "ACTIVE", "PAUSED", "CANCELLED", "BLOCKED" ] }, "LicenseType": { "type": "string", "description": "The kind of feature the license unlocks. Most types cover business telephony (PBX) features,\nsuch as `PBX_USER_LEVEL` (a PBX seat for one user), `PBX_SOFTPHONE` (softphone client),\n`PBX_ROUTE_IVR`, `PBX_ROUTE_GROUP`, `PBX_ROUTE_QUEUE`, and `PBX_ROUTE_VOICEMAIL` (call routing\nfeatures), plus `EXTERNAL_PRODUCT` for licenses tied to products outside the telecom platform.\n", "example": "PBX_USER_LEVEL" }, "EmbeddedAssignedTo": { "type": "object", "description": "The entity that a license is assigned to, with the display information for it.\nA license is always assigned to a subscription.\n", "required": [ "type", "subscriptionId" ], "properties": { "type": { "type": "string", "enum": [ "SUBSCRIPTION" ], "description": "The type of assignment" }, "subscriptionId": { "type": "string", "description": "The unique identifier for the subscription", "example": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786" }, "subscriptionDisplay": { "type": "string", "description": "Display name for the subscription (typically the phone number)", "example": "+1 (555) 123-4567" } } }, "EmbeddedLicense": { "type": "object", "description": "Essential license information without sensitive details.", "required": [ "licenseId", "status", "productOffering", "assignedTo" ], "properties": { "licenseId": { "type": "string", "description": "The unique identifier for the license.", "example": "b3c4d5e6-f7a8-9012-3456-789012345678" }, "status": { "$ref": "#/components/schemas/LicenseStatus" }, "type": { "$ref": "#/components/schemas/LicenseType" }, "productOffering": { "$ref": "#/components/schemas/EmbeddedProductOffering" }, "assignedTo": { "$ref": "#/components/schemas/EmbeddedAssignedTo" }, "customer": { "$ref": "#/components/schemas/EmbeddedCustomer" }, "activatedAt": { "type": "string", "format": "date-time", "description": "When the license was activated.", "example": "2024-01-15T10:30:00Z" } } }, "SubscriptionAddon": { "type": "object", "description": "An add-on attached to a subscription, providing extra services or resources (for example additional data, roaming packages, or travel eSIM bundles) on top of the base plan.", "required": [ "subscriptionAddonId", "subscriptionId", "status" ], "properties": { "subscriptionAddonId": { "type": "string", "description": "The unique identifier of the subscription add-on.", "example": "a47ac10b-58cc-4372-a567-0e02b2c3d479" }, "subscriptionId": { "type": "string", "description": "The unique identifier of the subscription this add-on belongs to.", "example": "d8174435-6378-4be5-a9f5-8b4aaadae5d4" }, "referenceId": { "type": "string", "description": "A reference identifier provided by API clients or upstream provider integrations\nto identify this subscription add-on in their own systems. Unique per tenant when\nset. Use this field to look up add-ons by your external identifier (for example a\nprovider-side package ID). Typically populated by a workflow once the add-on has\nbeen provisioned with the underlying network provider.\n", "example": "telna-package-12345", "maxLength": 255 }, "productOffering": { "$ref": "#/components/schemas/EmbeddedProductOffering" }, "status": { "$ref": "#/components/schemas/SubscriptionAddonStatus" }, "group": { "$ref": "#/components/schemas/ProductOfferingGroup" }, "license": { "$ref": "#/components/schemas/EmbeddedLicense" }, "pendingStatus": { "type": "object", "description": "A status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.", "properties": { "status": { "$ref": "#/components/schemas/SubscriptionAddonStatus" }, "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the pending status change is scheduled to occur.", "example": "2024-02-01" } } }, "pendingProductOffering": { "type": "object", "description": "A product offering change (upgrade or downgrade) that has been requested for this add-on but not yet applied. Present only while a change is scheduled; the current offering remains in `productOffering` until the scheduled date.", "properties": { "productOffering": { "$ref": "#/components/schemas/EmbeddedProductOffering" }, "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the pending product offering change is scheduled to occur.", "example": "2024-02-01" } } }, "addedAt": { "type": "string", "format": "date-time", "description": "The date and time when the add-on was added to the subscription.", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time when the add-on was last updated.", "example": "2024-01-20T09:00:00Z" }, "cancelledAt": { "type": "string", "format": "date-time", "description": "The date and time when the add-on was canceled (if applicable).", "example": "2024-06-30T00:00:00Z" }, "expiredAt": { "type": "string", "format": "date-time", "description": "The date and time when the add-on expired (if applicable).", "example": "2024-07-15T00:00:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "AddAddonRequest": { "type": "object", "description": "Request to add an add-on to a subscription.", "required": [ "productOfferingId" ], "additionalProperties": false, "properties": { "productOfferingId": { "type": "string", "description": "The unique identifier of the add-on product offering to add. Use the addon-options endpoint to discover which add-ons are available for the subscription.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the add-on should be added. If not provided, the add-on will be added immediately or according to the default schedule.", "example": "2024-03-01" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "CancelSubscriptionRequest": { "type": "object", "description": "Request to cancel a subscription.", "required": [ "cancelAt" ], "additionalProperties": false, "properties": { "cancelAt": { "description": "When the subscription should be cancelled.", "oneOf": [ { "type": "object", "title": "CancelNextDay", "required": [ "nextDay" ], "additionalProperties": false, "properties": { "nextDay": { "type": "boolean", "description": "Cancel the subscription the next day.", "example": true } } }, { "type": "object", "title": "CancelAtBeginningOfNextMonth", "required": [ "nextMonth" ], "additionalProperties": false, "properties": { "nextMonth": { "type": "boolean", "description": "Cancel the subscription at the beginning of next month.", "example": true } } }, { "type": "object", "title": "CancelAtDate", "required": [ "date" ], "additionalProperties": false, "properties": { "date": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Cancel the subscription on a specific date.", "example": "2024-02-01" } } } ] }, "churn": { "type": "string", "description": "Standardized reason for the cancellation used for reporting and analysis.\n\nIf OTHER is provided, please also provide a comment.\n", "enum": [ "BETTER_DEAL_PRICE", "NOT_HAPPY_MISSING_FUNCTIONS", "NOT_HAPPY_COVERAGE_SLA", "NOT_HAPPY_COMPLEX_ADMIN", "NOT_HAPPY_SUPPORT_ENGAGEMENT", "FRAUD", "FRAUD_ATTEMPT", "TEST_OR_MARKETING", "NO_NEED", "WRONG_ORDER", "OTHER" ] }, "comment": { "type": "string", "description": "Optional comment about the cancellation.", "example": "Switching to a different provider" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "SuspendSubscriptionRequest": { "type": "object", "description": "Request to temporarily suspend a subscription. The customer continues to pay but service is disabled.", "additionalProperties": false, "properties": { "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Suspend the subscription on a specific date.", "example": "2024-02-01" }, "reason": { "type": "string", "description": "Optional reason for the suspension.", "example": "Payment overdue" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "PauseSubscriptionRequest": { "type": "object", "description": "Request to pause a subscription. The customer stops paying and service is disabled.", "additionalProperties": false, "properties": { "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Earliest date to perform the pause on. If the pause schedule doesn't fit this date, the earliest date after this will be chosen.", "example": "2024-02-01" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "RestoreSubscriptionRequest": { "type": "object", "description": "Request to restore a suspended, paused, or blocked subscription back to active state.", "additionalProperties": false, "properties": { "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Restore the subscription on a specific date.", "example": "2024-02-01" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "ChangeSubscriptionSimRequest": { "type": "object", "description": "Request to change the SIM card (ICC/ICCID) for a subscription.", "required": [ "icc", "simCardType" ], "additionalProperties": false, "properties": { "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Change the SIM card on a specific date.", "example": "2024-02-01" }, "icc": { "type": "string", "description": "The ICCID (Integrated Circuit Card Identifier) of the new SIM card — the 19-20 digit serial number printed on the SIM or embedded in the eSIM profile.", "example": "89012345678901234567" }, "simCardType": { "type": "string", "description": "The type of SIM card being installed.", "enum": [ "PHYSICAL", "ESIM" ], "example": "PHYSICAL" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "CancelAddonRequest": { "type": "object", "description": "Request to cancel an add-on from a subscription.", "required": [ "subscriptionAddonId" ], "additionalProperties": false, "properties": { "subscriptionAddonId": { "type": "string", "description": "The identifier of the subscription add-on to cancel. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_telna-package-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n", "example": "a47ac10b-58cc-4372-a567-0e02b2c3d479" }, "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the add-on should be canceled. If not provided, the add-on will be canceled immediately or according to the default schedule.", "example": "2024-03-01" }, "reason": { "type": "string", "description": "Free-text explanation of why the add-on is being canceled. Stored with the cancellation for audit and reporting; not shown to the subscriber.", "example": "No longer needed" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "ChangeAddonRequest": { "type": "object", "description": "Request to change an existing add-on to a different product offering.", "required": [ "subscriptionAddonId", "productOfferingId" ], "additionalProperties": false, "properties": { "subscriptionAddonId": { "type": "string", "description": "The identifier of the subscription add-on to change. May be the entity's internal UUID or an external reference identifier.\nReference identifiers MUST be prefixed with `rid_` (e.g., `rid_telna-package-12345`) so the API\ncan distinguish them from internal UUIDs. The prefix is stripped before lookup.\n", "example": "a47ac10b-58cc-4372-a567-0e02b2c3d479" }, "productOfferingId": { "type": "string", "description": "The unique identifier of the new add-on product offering to change to.", "example": "addon-data-5gb" }, "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.", "example": "2024-02-01" }, "reason": { "type": "string", "description": "Free-text explanation of why the add-on is being changed. Stored with the change for audit and reporting; not shown to the subscriber.", "example": "Customer upgrade request" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "UsagePackageStatus": { "type": "string", "description": "Whether a usage package is currently consumable.\n\n- ACTIVE: The package is in its validity window and usage draws from it\n- NOT_ACTIVE: The package exists but is not currently consumable, for example a purchased package whose validity window has not started yet\n- EXPIRED: The package's validity window has ended; any remaining allowance is no longer usable\n", "enum": [ "ACTIVE", "NOT_ACTIVE", "EXPIRED" ] }, "UsageVoicePackage": { "type": "object", "description": "A single voice allowance bucket — either the base plan's included calling allowance or one granted by an add-on — reporting how much call time has been used and how much remains, in seconds.", "required": [ "name", "callSeconds", "callCount", "callRemainingSeconds", "callTotalSeconds", "status" ], "properties": { "subscriptionAddonId": { "type": "string", "description": "The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "name": { "type": "string", "description": "Human-readable name of the package, as shown to end users.", "example": "Unlimited National" }, "callSeconds": { "type": "integer", "format": "int64", "description": "Call time consumed from this allowance so far, in seconds.", "example": 3600 }, "callCount": { "type": "integer", "format": "int64", "description": "Number of calls placed against this allowance.", "example": 15 }, "callRemainingSeconds": { "type": "integer", "format": "int64", "description": "Call time still available in this allowance, in seconds.", "example": 32400 }, "callTotalSeconds": { "type": "integer", "format": "int64", "description": "The full call time allowance of this package, in seconds.", "example": 36000 }, "status": { "$ref": "#/components/schemas/UsagePackageStatus", "description": "The status of this package." }, "validFrom": { "type": "string", "format": "date-time", "description": "Start of the period this allowance applies to.", "example": "2025-01-01T00:00:00Z" }, "validTo": { "type": "string", "format": "date-time", "description": "End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.", "example": "2025-02-01T00:00:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "UsageVoiceIldPackage": { "type": "object", "description": "An international long distance (ILD) calling balance. Unlike national and roaming allowances, ILD calling is prepaid as a monetary amount that is drawn down per call, rather than a bucket of minutes.", "required": [ "name" ], "properties": { "subscriptionAddonId": { "type": "string", "description": "The subscription add-on that granted this balance. Present only when the balance comes from an add-on.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "name": { "type": "string", "description": "Human-readable name of the package, as shown to end users.", "example": "ILD Top-up" }, "balance": { "type": "number", "format": "double", "deprecated": true, "description": "Deprecated. Use `balanceMinor` instead.\n\nRemaining prepaid amount available for international long distance calls, in major units of the currency given by `currency`.\n", "example": 15.5 }, "balanceMinor": { "type": "integer", "format": "int64", "description": "Remaining prepaid amount available for international long distance calls, in minor units of the currency given by `currency`. Each ILD call deducts from this balance at the destination's per-minute rate.", "example": 1550 }, "currency": { "type": "string", "description": "Three-letter ISO 4217 code for the currency the balance is denominated in. Matches the subscription's billing currency.", "example": "USD" }, "expiryDate": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date the remaining balance expires and can no longer be used. Absent when the balance does not expire.", "example": "2025-12-31" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "UsageVoice": { "type": "object", "description": "Voice call usage for a subscription, split by where and to whom calls are made: national\n(domestic calls), roaming (calls made while abroad), and ILD (international long distance —\ncalls placed from the home country to foreign numbers).\n", "properties": { "national": { "type": "array", "description": "Allowance buckets for calls made within the home country, including the base plan's voice allowance and any add-on packages.", "items": { "$ref": "#/components/schemas/UsageVoicePackage" } }, "roaming": { "type": "array", "description": "Allowance buckets for calls made while roaming abroad.", "items": { "$ref": "#/components/schemas/UsageVoicePackage" } }, "ild": { "type": "array", "description": "International long distance (ILD) balances for calls placed from the home country to foreign numbers. Tracked as a monetary balance rather than minutes.", "items": { "$ref": "#/components/schemas/UsageVoiceIldPackage" } } } }, "UsageSmsPackage": { "type": "object", "description": "A single SMS allowance bucket — either the base plan's included message allowance or one granted by an add-on — reporting how many messages have been sent and how many remain.", "required": [ "name", "smsCount", "smsRemaining", "smsTotal", "status" ], "properties": { "subscriptionAddonId": { "type": "string", "description": "The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "name": { "type": "string", "description": "Human-readable name of the package, as shown to end users.", "example": "500 SMS National" }, "smsCount": { "type": "integer", "format": "int64", "description": "Number of messages consumed from this allowance so far.", "example": 25 }, "smsRemaining": { "type": "integer", "format": "int64", "description": "Number of messages still available in this allowance.", "example": 475 }, "smsTotal": { "type": "integer", "format": "int64", "description": "The full message allowance of this package.", "example": 500 }, "status": { "$ref": "#/components/schemas/UsagePackageStatus", "description": "The status of this package." }, "validFrom": { "type": "string", "format": "date-time", "description": "Start of the period this allowance applies to.", "example": "2025-01-01T00:00:00Z" }, "validTo": { "type": "string", "format": "date-time", "description": "End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.", "example": "2025-02-01T00:00:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "UsageSms": { "type": "object", "description": "SMS usage for a subscription, split by where and to whom messages are sent: national\n(domestic messages), roaming (messages sent while abroad), and ILD (international long\ndistance — messages sent from the home country to foreign numbers).\n", "properties": { "national": { "type": "array", "description": "Allowance buckets for messages sent within the home country, including the base plan's SMS allowance and any add-on packages.", "items": { "$ref": "#/components/schemas/UsageSmsPackage" } }, "roaming": { "type": "array", "description": "Allowance buckets for messages sent while roaming abroad.", "items": { "$ref": "#/components/schemas/UsageSmsPackage" } }, "ild": { "type": "array", "description": "Allowance buckets for messages sent from the home country to foreign numbers (international long distance).", "items": { "$ref": "#/components/schemas/UsageSmsPackage" } } } }, "UsageMmsPackage": { "type": "object", "description": "A single MMS allowance bucket — either the base plan's included multimedia message allowance or one granted by an add-on — reporting how many messages have been sent and how many remain.", "required": [ "name", "mmsCount", "mmsRemaining", "mmsTotal" ], "properties": { "subscriptionAddonId": { "type": "string", "description": "The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "name": { "type": "string", "description": "Human-readable name of the package, as shown to end users.", "example": "100 MMS National" }, "mmsCount": { "type": "integer", "format": "int64", "description": "Number of multimedia messages consumed from this allowance so far.", "example": 10 }, "mmsRemaining": { "type": "integer", "format": "int64", "description": "Number of multimedia messages still available in this allowance.", "example": 90 }, "mmsTotal": { "type": "integer", "format": "int64", "description": "The full multimedia message allowance of this package.", "example": 100 }, "validFrom": { "type": "string", "format": "date-time", "description": "Start of the period this allowance applies to.", "example": "2025-01-01T00:00:00Z" }, "validTo": { "type": "string", "format": "date-time", "description": "End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.", "example": "2025-02-01T00:00:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "UsageMms": { "type": "object", "description": "MMS (multimedia message) usage for a subscription, split by where and to whom messages are\nsent: national (domestic messages), roaming (messages sent while abroad), and ILD (international\nlong distance — messages sent from the home country to foreign numbers).\n", "properties": { "national": { "type": "array", "description": "Allowance buckets for multimedia messages sent within the home country, including the base plan's MMS allowance and any add-on packages.", "items": { "$ref": "#/components/schemas/UsageMmsPackage" } }, "roaming": { "type": "array", "description": "Allowance buckets for multimedia messages sent while roaming abroad.", "items": { "$ref": "#/components/schemas/UsageMmsPackage" } }, "ild": { "type": "array", "description": "Allowance buckets for multimedia messages sent from the home country to foreign numbers (international long distance).", "items": { "$ref": "#/components/schemas/UsageMmsPackage" } } } }, "UsageDataNationalPackage": { "type": "object", "description": "A single data allowance bucket for use in the home country — either the base plan's included data or a package granted by an add-on — reporting bytes used and remaining. Also carries the package's RLAH (Roam Like At Home) counters when part of the allowance can be used while roaming in RLAH regions (such as the EU/EEA) at no extra cost.", "required": [ "name", "dataBytesUsed", "dataBytesRemaining", "dataBytesTotal", "status" ], "properties": { "subscriptionAddonId": { "type": "string", "description": "The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included allowance.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "name": { "type": "string", "description": "Human-readable name of the package, as shown to end users.", "example": "10GB National" }, "dataBytesUsed": { "type": "integer", "format": "int64", "description": "Data consumed from this allowance so far, in bytes.", "example": 3221225472 }, "dataBytesRemaining": { "type": "integer", "format": "int64", "description": "Data still available in this allowance, in bytes.", "example": 7516192768 }, "dataBytesTotal": { "type": "integer", "format": "int64", "description": "The full data allowance of this package, in bytes.", "example": 10737418240 }, "rlahBytesUsed": { "type": "integer", "format": "int64", "description": "Data consumed while roaming under RLAH (Roam Like At Home) rules, in bytes. Present only when the package includes an RLAH allowance.", "example": 1073741824 }, "rlahBytesRemaining": { "type": "integer", "format": "int64", "description": "RLAH data still available, in bytes. Once exhausted, roaming usage may incur additional charges even though national data remains.", "example": 4294967296 }, "rlahBytesTotal": { "type": "integer", "format": "int64", "description": "The portion of this package usable while roaming under RLAH rules, in bytes. Often lower than the full national allowance.", "example": 5368709120 }, "status": { "$ref": "#/components/schemas/UsagePackageStatus", "description": "The status of this package." }, "validFrom": { "type": "string", "format": "date-time", "description": "Start of the period this allowance applies to.", "example": "2025-01-01T00:00:00Z" }, "validTo": { "type": "string", "format": "date-time", "description": "End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.", "example": "2025-02-01T00:00:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "UsageDataRoamingPackage": { "type": "object", "description": "A single data allowance bucket for use while roaming abroad — from the base plan's roaming allowance or a dedicated roaming add-on — reporting bytes used and remaining.", "required": [ "name", "dataBytesUsed", "dataBytesRemaining", "dataBytesTotal", "status" ], "properties": { "subscriptionAddonId": { "type": "string", "description": "The subscription add-on that granted this allowance. Present only when the package comes from an add-on; absent for the base plan's included roaming allowance.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "name": { "type": "string", "description": "Human-readable name of the package, as shown to end users.", "example": "Asia 5GB Roaming" }, "dataBytesUsed": { "type": "integer", "format": "int64", "description": "Data consumed from this allowance so far, in bytes.", "example": 1073741824 }, "dataBytesRemaining": { "type": "integer", "format": "int64", "description": "Data still available in this allowance, in bytes.", "example": 4294967296 }, "dataBytesTotal": { "type": "integer", "format": "int64", "description": "The full data allowance of this package, in bytes.", "example": 5368709120 }, "status": { "$ref": "#/components/schemas/UsagePackageStatus", "description": "The status of this package." }, "validFrom": { "type": "string", "format": "date-time", "description": "Start of the period this allowance applies to.", "example": "2025-01-01T00:00:00Z" }, "validTo": { "type": "string", "format": "date-time", "description": "End of the period this allowance applies to. For base plan allowances this is the end of the current billing period (when the allowance resets); for time-limited add-on packages it is when the package itself expires.", "example": "2025-02-01T00:00:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "UsageData": { "type": "object", "description": "Mobile data usage for a subscription, split by where the data is consumed: national (used in\nthe home country) and roaming (used while abroad).\n", "properties": { "national": { "type": "array", "description": "Allowance buckets for data used in the home country, including the base plan's data allowance and any add-on packages.", "items": { "$ref": "#/components/schemas/UsageDataNationalPackage" } }, "roaming": { "type": "array", "description": "Allowance buckets for data used while roaming abroad, from the base plan's roaming allowance or dedicated roaming add-on packages.", "items": { "$ref": "#/components/schemas/UsageDataRoamingPackage" } } } }, "Usage": { "type": "object", "description": "Current usage statistics for a subscription, organized by service type (voice, SMS, MMS, data).\nWithin each service type, usage is broken down into per-package allowance buckets: the base plan's\nincluded allowance plus any add-on packages, each reporting used, remaining, and total amounts.\nA service type is omitted entirely when the subscription has no allowances of that type.\n", "required": [ "updatedAt" ], "properties": { "voice": { "$ref": "#/components/schemas/UsageVoice", "description": "Voice call usage across all scopes and packages." }, "sms": { "$ref": "#/components/schemas/UsageSms", "description": "SMS usage across all scopes and packages." }, "mms": { "$ref": "#/components/schemas/UsageMms", "description": "MMS usage across all scopes and packages." }, "data": { "$ref": "#/components/schemas/UsageData", "description": "Data usage across all scopes and packages." }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the usage information was last refreshed from the network. Usage counters are not real-time; recent activity may not be reflected yet.", "example": "2024-01-15T10:30:00Z" } } }, "EsimQrCode": { "type": "object", "description": "eSIM QR code data for a subscription's eSIM profile, with an optional hosted image URL.", "required": [ "subscriptionId", "qrCodeData" ], "properties": { "subscriptionId": { "type": "string", "description": "The unique identifier of the subscription this QR code belongs to.", "example": "d8174435-6378-4be5-a9f5-8b4aaadae5d4" }, "qrCodeData": { "type": "string", "description": "The QR code data string that contains the eSIM profile download information (LPA format).", "example": "LPA:1$rsp-prod.example.com$12345678-1234-1234-1234-123456789012" }, "qrCodeUrl": { "type": "string", "format": "uri", "description": "Hosted URL where the QR code image can be accessed for display or download. Omitted when no hosted image is available; render the qrCodeData string as a QR code instead.", "example": "https://esim.your-domain.com/qr/d8174435-6378-4be5-a9f5-8b4aaadae5d4" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the QR code and any hosted URL expire. After this time, a new QR code should be requested. Omitted when no expiry applies.", "example": "2024-12-31T23:59:59Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "SubscriberListItem": { "type": "object", "description": "Simplified representation of a subscriber (the end user of a subscription) optimized for list operations. Use the detailed Subscriber schema for individual subscriber views.", "required": [ "subscriberId", "name" ], "properties": { "subscriberId": { "type": "string", "description": "The unique identifier of the subscriber.", "example": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e" }, "name": { "type": "string", "description": "The full name of the subscriber.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "Optional email address of the subscriber.", "example": "john.doe@example.com" }, "address": { "description": "The address of the subscriber.\nIn the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.\n", "$ref": "#/components/schemas/Address" }, "customerId": { "type": "string", "description": "The unique identifier of the customer the subscriber belongs to.", "example": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" }, "subscriptionIds": { "type": "array", "description": "List of subscriptions ids associated with the subscriber.\n\nTypically a subscriber has exactly one subscription, but in rare cases, a subscriber may have multiple subscriptions.\n", "items": { "type": "string", "description": "The unique identifier of the subscription.", "example": "d8174435-6378-4be5-a9f5-8b4aaadae5d4" } }, "createdAt": { "type": "string", "format": "date-time", "description": "Date and time when the subscriber was created.", "example": "2024-01-10T08:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Date and time when the subscriber was last updated.", "example": "2024-01-15T10:30:00Z" } } }, "Subscriber": { "type": "object", "description": "The person or entity that uses a subscription's service (the end user), as opposed to the customer, who pays for it. For example, an employee using a company-paid phone plan.", "required": [ "subscriberId", "name", "customer" ], "properties": { "subscriberId": { "type": "string", "description": "The unique identifier of the subscriber.", "example": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e" }, "name": { "type": "string", "description": "The full name of the subscriber.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "Optional email address of the subscriber.", "example": "john.doe@example.com" }, "contactNumber": { "type": "string", "format": "phone", "description": "A phone number for reaching the subscriber, separate from the number their subscription provides.", "example": "+15551234567" }, "address": { "description": "The address of the subscriber.\nIn the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.\n", "$ref": "#/components/schemas/Address" }, "customer": { "$ref": "#/components/schemas/EmbeddedCustomer" }, "subscriptions": { "type": "array", "description": "List of subscriptions associated with the subscriber.\n\nTypically a subscriber has exactly one subscription, but in rare cases, a subscriber may have multiple subscriptions.\n", "items": { "$ref": "#/components/schemas/Subscription" } } } }, "UpdateSubscriberRequest": { "type": "object", "description": "Request to update a subscriber's information.", "properties": { "name": { "type": "string", "description": "The full name of the subscriber.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "The email address of the subscriber.", "example": "john.doe@example.com" }, "contactNumber": { "type": "string", "format": "phone", "description": "A phone number for reaching the subscriber, separate from the number their subscription provides.", "example": "+15551234567" }, "address": { "description": "The address of the subscriber.\n\nIn the US, this refers to the E911 address associated with the subscriber's phone number, which is used for emergency services.\nChanging it schedules an update with the network operator, so the new address becomes the one emergency services receive.\n", "$ref": "#/components/schemas/Address" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "License": { "type": "object", "description": "A license represents a permission to use a software product with embedded customer and product offering details.", "required": [ "licenseId", "status", "type", "customer", "productOffering", "activatedAt" ], "properties": { "licenseId": { "type": "string", "description": "The unique identifier for the license.", "example": "c9d0e1f2-a3b4-5678-9012-def012345678" }, "status": { "$ref": "#/components/schemas/LicenseStatus" }, "type": { "$ref": "#/components/schemas/LicenseType" }, "customer": { "$ref": "#/components/schemas/EmbeddedCustomer" }, "productOffering": { "$ref": "#/components/schemas/EmbeddedProductOffering" }, "assignedTo": { "$ref": "#/components/schemas/EmbeddedAssignedTo" }, "details": { "type": "object", "description": "Additional license details specific to certain license types.", "additionalProperties": true }, "pendingStatus": { "type": "object", "description": "A status change that has been requested but not yet applied, for example a scheduled cancellation. Present only while a status change is scheduled.", "required": [ "status", "scheduledAt" ], "properties": { "status": { "$ref": "#/components/schemas/LicenseStatus" }, "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the pending status change is scheduled to occur.", "example": "2024-02-01" } } }, "pendingProductOffering": { "type": "object", "description": "A product offering change (upgrade or downgrade) that has been requested but not yet applied. Present only while a change is scheduled; the current offering remains in `productOffering` until the scheduled date.", "required": [ "scheduledAt", "product" ], "properties": { "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the pending product offering change is scheduled to occur.", "example": "2024-02-01" }, "product": { "$ref": "#/components/schemas/EmbeddedProductOffering" } } }, "activatedAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the license was activated.", "example": "2024-01-15" }, "cancelledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the license was canceled (if applicable).", "example": "2024-06-30" }, "pausedAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the license was paused (if applicable).", "example": "2024-03-01" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "AssignedTo": { "description": "The entity that a license is assigned to. A license is always assigned to a subscription.\n", "oneOf": [ { "type": "object", "title": "Subscription", "required": [ "type", "subscriptionId" ], "properties": { "type": { "type": "string", "enum": [ "SUBSCRIPTION" ], "description": "The type of entity the license is assigned to." }, "subscriptionId": { "type": "string", "description": "The unique identifier of the subscription the license is assigned to.", "example": "c9a4d8d4-24c0-4164-ac8d-c77c4103b786" } } } ] }, "CreateLicenseRequest": { "type": "object", "description": "Create a new license.\n\nThe product offering sets the type of the license. A license for an external product is\nstandalone and takes no `assignedTo`. Every other license needs `assignedTo`, and the\nsubscription must belong to the same customer.\n", "required": [ "productOfferingId", "customerId" ], "additionalProperties": false, "properties": { "productOfferingId": { "type": "string", "description": "The unique identifier for the product offering to subscribe to.\n\nThe offering sets the type of the license.\n", "example": "a7b8c9d0-e1f2-3456-7890-bcdef0123456" }, "customerId": { "type": "string", "format": "uuid", "description": "The unique identifier for the existing customer who will own this license.", "example": "b8c9d0e1-f2a3-4567-8901-cdef01234567" }, "licenseType": { "$ref": "#/components/schemas/LicenseType", "deprecated": true, "description": "Deprecated. The product offering sets the type of the license.\n\nThe platform rejects a value that does not agree with the product offering.\n" }, "assignedTo": { "$ref": "#/components/schemas/AssignedTo" }, "scheduleActivationAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Date when the license must be activated. The platform activates the license today when you\nomit this date. A date in the past is not permitted.\n", "example": "2024-01-15" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "example": { "productOfferingId": "d0e1f2a3-b4c5-6789-0123-ef0123456789", "customerId": "b8c9d0e1-f2a3-4567-8901-cdef01234567", "assignedTo": { "type": "SUBSCRIPTION", "subscriptionId": "c9d0e1f2-a3b4-5678-9012-def012345678" }, "scheduleActivationAt": "2024-01-20" } }, "ChangeLicenseProductOfferingRequest": { "type": "object", "description": "Request to change the product offering of a license.", "required": [ "productOfferingId" ], "additionalProperties": false, "properties": { "productOfferingId": { "type": "string", "description": "The unique identifier of the new product offering. Use the product-offering-options endpoint to discover which offerings the license can be changed to.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Earliest date to perform the change on. If the change schedule doesn't fit this date, the earliest date after this will be chosen.", "example": "2024-02-01" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "CancelLicenseRequest": { "type": "object", "description": "Request to cancel a license.", "additionalProperties": false, "properties": { "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the license should be cancelled. If not provided, the license will be cancelled immediately or according to the default schedule.", "example": "2024-03-01" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "ProductCatalogListItem": { "type": "object", "description": "A product catalog defines a curated set of product offerings for a specific context such as customer segment, region, or sales channel.\n", "required": [ "productCatalogId", "name", "extendsDefault" ], "properties": { "productCatalogId": { "type": "string", "description": "Unique identifier for the product catalog.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "name": { "type": "string", "description": "Name of the product catalog.", "example": "US Consumer Catalog" }, "description": { "type": "string", "description": "Description of the product catalog.", "example": "Product catalog for US consumer customers" }, "extendsDefault": { "type": "boolean", "description": "Whether this catalog extends the default product catalog. When true, the catalog inherits all offerings from the default catalog in addition to its own." }, "isDefault": { "type": "boolean", "description": "Whether this is the default catalog for its customer type. A customer with no catalog of their own is served the default one." }, "customerType": { "$ref": "#/components/schemas/CustomerType", "description": "The kind of customer this catalog serves. Absent on catalogs that have not been assigned a customer type." } } }, "EmbeddedDiscount": { "type": "object", "description": "Essential discount information without sensitive details.", "required": [ "discountId", "description" ], "properties": { "discountId": { "type": "string", "description": "The unique identifier for the discount.", "example": "80df6fdf-c450-406e-948b-f77d4ac1cdb8" }, "description": { "type": "string", "description": "A description of what the discount provides.", "example": "25% Off Summer Promo" }, "tag": { "type": "string", "description": "A short label or category for the discount.", "example": "SUMMER25" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the discount was created.", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the discount was last updated.", "example": "2024-01-20T14:45:00Z" } } }, "Promotion": { "type": "object", "description": "A promotion that applies a discount when the promotional code is used.", "required": [ "promotionId", "discountId", "promoCode", "discountPeriodMonths", "discount" ], "properties": { "promotionId": { "type": "string", "description": "The unique identifier for the promotion.", "example": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, "promoCode": { "type": "string", "description": "The promotional code that customers can use to activate this promotion.", "example": "SUMMER25" }, "discountPeriodMonths": { "type": "integer", "description": "The number of months the discount will be applied.", "example": 12 }, "validFrom": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "When the promotion becomes valid and can be used.\n\nIf not provided, the promotion is valid immediately.\n" }, "validTo": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "When the promotion expires and can no longer be used.\n\nIf not provided, the promotion does not expire.\n" }, "discountId": { "type": "string", "description": "The unique identifier for the discount that this promotion applies to.", "example": "80df6fdf-c450-406e-948b-f77d4ac1cdb8" }, "discount": { "$ref": "#/components/schemas/EmbeddedDiscount" } } }, "OrderState": { "type": "string", "description": "The status of an order in its lifecycle.\n\n- PENDING: Order is in cart state, can be modified\n- PENDING_PAYMENT: Order is locked and awaiting payment completion\n- SUBMITTED: Order has been submitted for processing\n- PENDING_APPROVAL: Order is pending approval\n- PROCESSING: Order is being fulfilled\n- COMPLETED: Order has been successfully fulfilled\n- CANCELLED: Order was cancelled before completion\n- EXPIRED: Order expired due to inactivity\n- FAILED: Order fulfillment failed\n", "enum": [ "PENDING", "PENDING_PAYMENT", "SUBMITTED", "PENDING_APPROVAL", "PROCESSING", "COMPLETED", "CANCELLED", "EXPIRED", "FAILED" ] }, "OrderListItem": { "type": "object", "description": "Optimized order representation for list operations.", "required": [ "orderId", "state", "createdAt", "updatedAt" ], "properties": { "orderId": { "type": "string", "description": "The unique identifier for the order.", "example": "ce0539b4-ec57-4709-b72e-47892586d05a" }, "state": { "$ref": "#/components/schemas/OrderState" }, "customer": { "$ref": "#/components/schemas/EmbeddedCustomer" }, "pricing": { "type": "object", "description": "Summary pricing information for the order.", "required": [ "totalMinor", "currency" ], "additionalProperties": false, "properties": { "total": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `totalMinor` instead.\n\nFinal order total including all taxes and fees, in major currency units.\n" }, "totalMinor": { "type": "integer", "format": "int64", "description": "Final order total including all taxes and fees, in minor currency units.", "example": 13739 }, "currency": { "type": "string", "description": "ISO 4217 currency code.", "example": "USD" } } }, "validationStatus": { "type": "string", "enum": [ "VALID", "INVALID", "PENDING_VALIDATION" ], "description": "Whether the order is complete and ready for submission. Fetch the full order to see which fields are missing or invalid." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the order was created.", "example": "2024-01-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the order was last updated.", "example": "2024-01-15T10:30:00Z" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the order will expire if not submitted.", "example": "2024-01-22T10:30:00Z" } } }, "OrderCustomerType": { "$ref": "#/components/schemas/CustomerType", "description": "The type of customer this order is for. This scopes the order to the customer type's context,\nwhich affects which product offerings can be ordered, who is authorized to place the order, and what is required to submit it.\n\nFor logged in orders, this must match the customer's type.\n" }, "OrderUserReference_NewUser": { "type": "object", "title": "NewUser", "additionalProperties": false, "required": [ "name", "email" ], "description": "Details for creating a new user together with the order. The user is created when payment\nis initiated, or at submission for orders that collect no payment, and can then log in to\nmanage the services they ordered.\n", "properties": { "name": { "type": "string", "description": "The user's full name.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "The email the user logs in with and receives order confirmations on.", "example": "john.doe@example.com" }, "identity": { "$ref": "#/components/schemas/Identity" }, "msisdn": { "type": "string", "format": "phone", "description": "The user's phone number.", "example": "+15551234567" }, "address": { "$ref": "#/components/schemas/Address", "deprecated": true, "description": "Deprecated. The platform does not store this address. A user is a sign-in\nidentity, and the address of the person belongs to the customer that pays.\nGive the address in `customer` instead.\n" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "OrderUserReference": { "oneOf": [ { "type": "object", "title": "ExistingUserById", "additionalProperties": false, "required": [ "userId" ], "description": "Reference to an existing user. Only accepted from an authenticated caller who is that user or\nis authorized for their organisation.\n", "properties": { "userId": { "type": "string", "description": "The user's internal ID.", "example": "d47ac10b-58cc-4372-a567-0e02b2c3d479" } } }, { "type": "object", "title": "AuthenticatedUser", "additionalProperties": false, "required": [ "authenticatedUser" ], "description": "Use the authenticated user the request is made on behalf of, without naming them.\nRequires a bearer token for that user; an anonymous caller is refused.\n", "properties": { "authenticatedUser": { "type": "boolean", "description": "Always true.", "example": true } } }, { "$ref": "#/components/schemas/OrderUserReference_NewUser" } ], "description": "The person who will log in and manage the services in this order. Provide a userId for a\nreturning user, let the authenticated user be resolved from their token, or provide details to\ncreate a new user together with the order.\n" }, "OrderCustomerReference_NewCustomer": { "type": "object", "title": "NewCustomer", "required": [ "name", "customerType" ], "description": "Details for creating a new customer together with the order.\n\nThe customer's default payment profile can be set via the save payment profile endpoint once the customer is created.\n\nIf referenceId is provided and a customer already exists with that referenceId,\nthe existing customer will be used instead of creating a new one.\n", "properties": { "referenceId": { "type": "string", "description": "Optional reference ID to assign to the new customer. If a customer with\nthis referenceId already exists, that customer will be used instead of\ncreating a new one.\n", "example": "crm-customer-12345", "maxLength": 255 }, "name": { "type": "string", "description": "Name for the new customer.", "example": "Acme Corporation" }, "customerType": { "$ref": "#/components/schemas/CustomerType" }, "identity": { "$ref": "#/components/schemas/Identity" }, "preferredLocale": { "type": "string", "description": "Preferred locale for the customer.", "example": "en-US" }, "contact": { "type": "object", "description": "Contact information for the new customer.", "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email", "description": "Primary contact email for the new customer.", "example": "billing@acme.com" }, "msisdn": { "type": "string", "format": "phone", "description": "Primary contact phone number for the new customer.", "example": "+15551234567" } } }, "billing": { "type": "object", "description": "Billing configuration and payment preferences for the new customer.", "required": [ "method", "currency" ], "additionalProperties": false, "properties": { "method": { "$ref": "#/components/schemas/CustomerBillingMethod", "description": "How invoices should be delivered to the customer." }, "email": { "type": "string", "format": "email", "description": "The email address to send invoices to.\nRequired if billing method is EMAIL_INVOICE.\n", "example": "billing@acme.com" }, "address": { "$ref": "#/components/schemas/Address", "description": "The billing address for the customer. Used for invoicing and tax calculation.\n" }, "currency": { "$ref": "#/components/schemas/Currency", "description": "The currency for customer billing and payments." }, "autoPay": { "type": "boolean", "description": "Whether to automatically charge the default payment profile for invoices and bills.\nRequires defaultPaymentProfileId to be set to have any effect.\n", "example": true, "default": false } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "OrderCustomerReference": { "oneOf": [ { "type": "object", "title": "ExistingCustomerById", "additionalProperties": false, "required": [ "customerId" ], "description": "Reference to an existing customer by internal ID or external reference ID.\nOnly accepted from an authenticated caller who is authorized for that customer.\n", "properties": { "customerId": { "type": "string", "description": "The customer's internal ID (UUID) or external reference ID.\nBoth formats are accepted and will be resolved automatically.\n", "example": "a47ac10b-58cc-4372-a567-0e02b2c3d479" } } }, { "type": "object", "title": "AuthenticatedCustomer", "additionalProperties": false, "required": [ "authenticatedCustomer" ], "description": "Use the customer of the authenticated user the request is made on behalf of, without naming it.\nRequires a bearer token for that user; an anonymous caller is refused.\n", "properties": { "authenticatedCustomer": { "type": "boolean", "description": "Always true.", "example": true } } }, { "$ref": "#/components/schemas/OrderCustomerReference_NewCustomer" } ], "description": "Reference to a customer of the order. Provide a customerId (which accepts both internal UUIDs and external reference IDs),\nlet the authenticated user's own customer be resolved, or provide details to create a new customer.\n" }, "OrderBillingInput": { "type": "object", "description": "Billing information for an order.\n\nFor existing customers, we suggest you pre-fill this with the customer's billing information,\nhowever it is possible to override this at the order level.\n", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Billing contact name.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "Billing contact email.", "example": "billing@example.com" }, "address": { "$ref": "#/components/schemas/Address" } } }, "LineItemSim": { "type": "object", "title": "Line Item SIM", "description": "The choice between eSIM and physical SIM plus related device details.", "additionalProperties": false, "required": [ "esim" ], "properties": { "esim": { "type": "boolean", "description": "Whether this line item uses eSIM technology.", "example": true }, "imei": { "type": "string", "description": "International Mobile Equipment Identity for eSIM activation.\n\nSome networks require this to activate the eSIM.\n", "example": "356938035643809" }, "iccid": { "type": "string", "description": "Integrated Circuit Card identifier for existing SIM.\nProvide if using a pre-existing SIM card.\n\nThis feature only applies to certain networks.\n", "example": "8931440400000000000" } } }, "OrderLineItemStatus": { "type": "string", "description": "The current fulfillment status of an order line item.\n\nResolved dynamically from the underlying entity (subscription action, activation).\nAn order can complete while individual line items remain RUNNING or FAILED; failures on\none line item do not block completion of the rest of the order.\n", "enum": [ "PENDING", "RUNNING", "COMPLETED", "FAILED" ] }, "SubscriptionLineItem": { "type": "object", "title": "Subscription", "description": "Create a new subscription in this order. This will set up a new phone service for a customer with their chosen plan and phone number.", "required": [ "type", "lineItemId", "productOfferingId" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "SUBSCRIPTION" ], "description": "Identifies this line item as a new subscription purchase. Always SUBSCRIPTION." }, "lineItemId": { "type": "string", "description": "Unique identifier for this line item within the order.", "example": "line-item-1" }, "productOfferingId": { "type": "string", "description": "The product offering to create a subscription for.", "example": "mobile-plan-basic" }, "msisdn": { "type": "string", "description": "The phone number for this subscription.\n- Leave empty to have one assigned.\n- When the number pool is available, you can choose a number from the pool and provide the leaseToken.\n- When porting a number, provide the number and porting details.\n", "example": "+15551234567" }, "leaseToken": { "type": "string", "description": "Token received when leasing a number. Required when an msisdn is provided from the number pool.", "example": "lease_8f3b1c2d4e5f6789" }, "tempNumber": { "type": "boolean", "description": "Whether to use a temporary number until the porting is completed.\n\nIf true, a temporary number will be assigned and activated as soon as possible until the porting is finalized.\n\nCan only be used when porting in a number (i.e., when msisdn and porting details are provided).\n", "example": true }, "portingRequested": { "type": "boolean", "description": "If true, the number is a port-in.", "example": true }, "porting": { "type": "object", "description": "Details needed to port in a number for this subscription.", "required": [ "details" ], "additionalProperties": false, "properties": { "details": { "$ref": "#/components/schemas/PortingDetails" } } }, "extensions": { "type": "object", "description": "Additional subscription extensions fields for custom subscription types.", "additionalProperties": { "type": "string" } }, "display": { "type": "string", "description": "Custom display name for the subscription. If not provided, will be auto-generated from msisdn.", "example": "John Doe - Work phone" }, "subscriber": { "type": "object", "description": "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.", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Name of the subscriber.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "Contact email of the subscriber.", "example": "john.doe@example.com" }, "msisdn": { "type": "string", "format": "phone", "description": "Contact phone number of the subscriber. May be the same as the subscription's msisdn.", "example": "+15551234567" }, "address": { "$ref": "#/components/schemas/Address", "description": "The address of the subscriber. Depending on local regulations, this may be required for certain subscriptions.\n\nIn the US, this is the E911 address.\n" } } }, "sim": { "$ref": "#/components/schemas/LineItemSim", "description": "The choice between eSIM and physical SIM plus related device details.\n\nThis value is optional while the order is a draft. You must give it before you submit the order.\n" }, "scheduleActivationAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Date when the subscription should be activated. Cannot be combined with activateOnDemand.", "example": "2024-02-01" }, "activateOnDemand": { "type": "boolean", "description": "Whether the subscription waits for the subscriber to activate it rather than being activated on a date.\n\nThe subscription is created when the order is fulfilled and stays pending until the subscriber\nrequests activation; only then is it activated in the network. Use this when the subscriber decides\nwhen their service starts, for example a SIM shipped ahead of time.\n\nCannot be combined with scheduleActivationAt.\n", "example": true }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "status": { "$ref": "#/components/schemas/OrderLineItemStatus", "readOnly": true, "description": "Server-resolved fulfillment status for this line item." } } }, "AddonLineItem": { "type": "object", "title": "Add-on", "description": "Line item for adding an add-on to a subscription.", "required": [ "type", "lineItemId", "productOfferingId" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "ADDON" ], "description": "Identifies this line item as adding an add-on to a subscription. Always ADDON." }, "lineItemId": { "type": "string", "description": "Unique identifier for this line item within the order.", "example": "line-item-3" }, "productOfferingId": { "type": "string", "description": "The add-on product offering to add.", "example": "addon-data-5gb" }, "subscriptionId": { "type": "string", "description": "An existing subscription to add the add-on to.\n\nEither this or `parentLineItemId` must be provided.\n", "example": "subscription-456" }, "parentLineItemId": { "type": "string", "description": "Reference to parent subscription line item in this same order.\n\nEither this or `subscriptionId` must be provided.\n", "example": "line-item-1" }, "scheduledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "When to activate the add-on.", "example": "2024-02-01" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "status": { "$ref": "#/components/schemas/OrderLineItemStatus", "readOnly": true, "description": "Server-resolved fulfillment status for this line item." } } }, "ExternalProductLineItem": { "type": "object", "title": "External Product", "description": "Line item for purchasing a catalog product that is fulfilled outside the platform. The order records the sale while fulfillment happens in your own systems.", "required": [ "type", "lineItemId", "productOfferingId" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "EXTERNAL_PRODUCT" ], "description": "Identifies this line item as a catalog product fulfilled outside the platform. Always EXTERNAL_PRODUCT." }, "lineItemId": { "type": "string", "description": "Unique identifier for this line item within the order.", "example": "line-item-5" }, "productOfferingId": { "type": "string", "description": "The external product offering from the catalog.", "example": "external-device-iphone15" }, "quantity": { "type": "integer", "minimum": 1, "description": "Quantity of the external product.", "example": 2 }, "parentLineItemId": { "type": "string", "description": "Reference to parent line item in this order.", "example": "line-item-1" }, "scheduleActivationAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Date when the external product must be activated. The order activates it on the day of fulfillment when you omit this date.", "example": "2024-02-01" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "status": { "$ref": "#/components/schemas/OrderLineItemStatus", "readOnly": true, "description": "Server-resolved fulfillment status for this line item." } } }, "ExternalLineItem": { "type": "object", "title": "External Item", "description": "Line item for selling an externally managed product or service that is not in the product catalog. You define the name, price, and taxation, and can optionally receive a webhook to fulfill the item yourself.", "required": [ "type", "lineItemId", "name", "price" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "EXTERNAL" ], "description": "Identifies this line item as an externally managed product or service that is not in the product catalog. Always EXTERNAL." }, "lineItemId": { "type": "string", "description": "Unique identifier for this line item within the order.", "example": "line-item-6" }, "name": { "type": "string", "description": "Name of the external item.", "example": "Custom Installation Service" }, "description": { "type": "string", "description": "Description of the external item.", "example": "Professional on-site installation and setup" }, "price": { "type": "object", "description": "Custom pricing for the external item.", "required": [ "amountMinor", "currency" ], "additionalProperties": false, "properties": { "amountMinor": { "type": "integer", "format": "int64", "description": "The price per unit, in minor units of the currency (e.g., 9999 = $99.99 when the currency is USD).", "example": 9999 }, "currency": { "type": "string", "description": "The ISO 4217 currency code the price is expressed in. Must match the order currency.", "example": "USD" } } }, "quantity": { "type": "integer", "minimum": 1, "description": "Quantity of the external item.", "example": 1 }, "taxationId": { "type": "string", "description": "US taxation ID for tax calculation.", "example": "TAX123456" }, "fulfillmentWebhook": { "type": "string", "format": "uri", "description": "Optional webhook URL for fulfillment notifications.", "example": "https://partner.com/webhooks/fulfillment" }, "parentLineItemId": { "type": "string", "description": "Reference to parent line item in this order.", "example": "line-item-1" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "status": { "$ref": "#/components/schemas/OrderLineItemStatus", "readOnly": true, "description": "Server-resolved fulfillment status for this line item." } } }, "SubscriptionPlanChange": { "type": "object", "title": "Subscription Plan Change", "description": "A change of the product of a subscription.\n", "additionalProperties": false, "required": [ "productOfferingId" ], "properties": { "productOfferingId": { "type": "string", "description": "The plan offering to change to. The platform refuses an offering in the SIM card category.\n", "example": "mobile-plan-premium" } } }, "SubscriptionSimChange": { "type": "object", "title": "Subscription SIM Change", "description": "A change of the SIM card of a subscription. The change carries a one-time price.\n", "additionalProperties": false, "required": [ "productOfferingId" ], "properties": { "productOfferingId": { "type": "string", "description": "The SIM card offering to change to. The offering must be in the SIM card category.\n", "example": "sim-card-replacement" }, "sim": { "$ref": "#/components/schemas/LineItemSim", "description": "The SIM card of the change.\n\nThe 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.\n\nThe 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.\n" } } }, "SubscriptionChangeLineItem": { "type": "object", "title": "Subscription Change", "description": "Line item that changes an existing subscription.\n\nThe changeType field says what the line item changes. Give the variant of that kind. Each variant carries the product offering of its own kind. The schedule date applies to every kind, so it stays on the line item.\n", "required": [ "type", "lineItemId", "subscriptionId", "changeType" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "SUBSCRIPTION_CHANGE" ], "description": "Identifies this line item as a change to an existing subscription. Always SUBSCRIPTION_CHANGE." }, "lineItemId": { "type": "string", "description": "Unique identifier for this line item within the order.", "example": "line-item-7" }, "subscriptionId": { "type": "string", "description": "The identifier of the existing subscription that this line item changes.", "example": "subscription-456" }, "changeType": { "type": "string", "enum": [ "PLAN_CHANGE", "SIM_CHANGE" ], "description": "What this line item changes.\n\nPLAN_CHANGE changes the product of the subscription. SIM_CHANGE changes the SIM card of the subscription.\n\nThe 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.\n", "example": "PLAN_CHANGE" }, "planChange": { "$ref": "#/components/schemas/SubscriptionPlanChange", "description": "The plan change. Give this value only for changeType PLAN_CHANGE.\n" }, "simChange": { "$ref": "#/components/schemas/SubscriptionSimChange", "description": "The SIM card change. Give this value only for changeType SIM_CHANGE.\n" }, "scheduleDate": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.\n", "example": "2024-02-01" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "status": { "$ref": "#/components/schemas/OrderLineItemStatus", "readOnly": true, "description": "Server-resolved fulfillment status for this line item." } } }, "AddonPlanChange": { "type": "object", "title": "Add-on Plan Change", "description": "A change of the product of an add-on.\n", "additionalProperties": false, "required": [ "productOfferingId" ], "properties": { "productOfferingId": { "type": "string", "description": "The add-on offering to change to.\n", "example": "addon-data-5gb" } } }, "AddonChangeLineItem": { "type": "object", "title": "Add-on Change", "description": "Line item that changes an add-on of a subscription.\n\nThe changeType field says what the line item changes. Give the variant of that kind. Each variant carries the product offering of its own kind. The schedule date applies to every kind, so it stays on the line item.\n", "required": [ "type", "lineItemId", "subscriptionId", "addonId", "changeType" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "ADDON_CHANGE" ], "description": "Identifies this line item as a change to an existing add-on. Always ADDON_CHANGE." }, "lineItemId": { "type": "string", "description": "Unique identifier for this line item within the order.", "example": "line-item-9" }, "subscriptionId": { "type": "string", "description": "The subscription containing the add-on to modify.", "example": "subscription-456" }, "addonId": { "type": "string", "description": "The identifier of the existing add-on on the subscription that this line item changes.", "example": "addon-123" }, "changeType": { "type": "string", "enum": [ "PLAN_CHANGE" ], "description": "What this line item changes.\n\nPLAN_CHANGE changes the product of the add-on.\n", "example": "PLAN_CHANGE" }, "planChange": { "$ref": "#/components/schemas/AddonPlanChange", "description": "The plan change. Give this value only for changeType PLAN_CHANGE.\n" }, "scheduleDate": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Earliest date to perform the change on. If the change schedule does not fit this date, the platform selects the earliest date after it.\n", "example": "2024-02-01" }, "reason": { "type": "string", "description": "Free-text note recording why the add-on is being changed, kept with the order for audit and support follow-up.", "example": "Customer upgrade request" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "status": { "$ref": "#/components/schemas/OrderLineItemStatus", "readOnly": true, "description": "Server-resolved fulfillment status for this line item." } } }, "OrderLineItem": { "description": "A line item in an order representing a billable action or service.", "oneOf": [ { "$ref": "#/components/schemas/SubscriptionLineItem" }, { "$ref": "#/components/schemas/AddonLineItem" }, { "$ref": "#/components/schemas/ExternalProductLineItem" }, { "$ref": "#/components/schemas/ExternalLineItem" }, { "$ref": "#/components/schemas/SubscriptionChangeLineItem" }, { "$ref": "#/components/schemas/AddonChangeLineItem" } ], "discriminator": { "propertyName": "type", "mapping": { "SUBSCRIPTION": "#/components/schemas/SubscriptionLineItem", "ADDON": "#/components/schemas/AddonLineItem", "EXTERNAL_PRODUCT": "#/components/schemas/ExternalProductLineItem", "EXTERNAL": "#/components/schemas/ExternalLineItem", "SUBSCRIPTION_CHANGE": "#/components/schemas/SubscriptionChangeLineItem", "ADDON_CHANGE": "#/components/schemas/AddonChangeLineItem" } } }, "Consents": { "type": "object", "description": "The consents and acknowledgments the customer gave when placing the order, such as accepting terms of service or opting in to marketing.\nKeys name the consent and values record what was agreed to, so the consent can be audited later.\n", "additionalProperties": { "type": "string" }, "example": { "termsOfService": "true", "marketing": "true" } }, "CreateOrderRequest": { "type": "object", "description": "Request to create a new order. Orders can be created with minimal information\nand progressively configured. User and customer information can be added later,\nincluding through mid-flow authentication.\n", "additionalProperties": false, "required": [ "customerType" ], "properties": { "customerType": { "$ref": "#/components/schemas/OrderCustomerType" }, "user": { "$ref": "#/components/schemas/OrderUserReference" }, "customer": { "$ref": "#/components/schemas/OrderCustomerReference" }, "billing": { "$ref": "#/components/schemas/OrderBillingInput" }, "shipping": { "$ref": "#/components/schemas/ShippingInput" }, "lineItems": { "type": "array", "description": "Initial line items for the order (can be empty).", "items": { "$ref": "#/components/schemas/OrderLineItem" } }, "consents": { "$ref": "#/components/schemas/Consents" }, "promoCode": { "type": "string", "description": "Promo code to apply to the order. Rejected with `internalCode` 4119 when no promotion has\nthat code, or when it is outside its validity period.\n", "example": "SUMMER2023" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "OrderUserResult": { "type": "object", "description": "The person who will log in and manage the services in this order.\n\nFor a new user, userId is absent until the user is actually created, which happens when\npayment is initiated or, for orders that collect no payment, at submission.\n", "properties": { "userId": { "type": "string", "description": "The user's identifier, once the user exists.", "example": "c47ac10b-58cc-4372-a567-0e02b2c3d479" }, "name": { "type": "string", "description": "The user's full name.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "The email the user logs in with.", "example": "john.doe@example.com" }, "newUser": { "type": "boolean", "description": "Whether this user is created as part of fulfilling the order.", "example": true } }, "required": [ "newUser" ] }, "OrderCustomerResult": { "type": "object", "description": "The customer associated with this order. Includes minimal details about the customer\nand creation details if the customer was created during order fulfillment.\n", "properties": { "customerId": { "type": "string", "description": "The unique identifier for the customer. For new customers, set once the customer has been created during fulfillment.", "example": "b47ac10b-58cc-4372-a567-0e02b2c3d479" }, "customerType": { "$ref": "#/components/schemas/CustomerType" }, "name": { "type": "string", "description": "Customer name.", "example": "John Doe" }, "newCustomer": { "type": "boolean", "description": "Indicates if the customer was/will be created as part of order fulfillment.", "example": true } }, "required": [ "customerType", "name", "newCustomer" ] }, "OrderBilling": { "type": "object", "description": "Billing information for an order.\n\nFor existing customers, we suggest you pre-fill this with the customer's billing information,\nhowever it is possible to override this at the order level.\n", "properties": { "name": { "type": "string", "description": "Billing contact name.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "Billing contact email.", "example": "billing@example.com" }, "address": { "$ref": "#/components/schemas/Address" } } }, "OrderPricingSummary": { "type": "object", "description": "The price of an order, recalculated whenever the order changes. In regions with complex tax\nrules (e.g., the US), tax is resolved per jurisdiction from the order's addresses. In other\nregions, tax depends on customer type but is typically included.\n\nAll amounts are in minor units of the currency (e.g., 13739 = $137.39 when the currency is USD).\n", "required": [ "totalMinor", "currency", "calculatedAt" ], "properties": { "subtotal": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `subtotalMinor` instead.\n\nSubtotal after discounts and before taxes and fees, in major currency units.\n" }, "subtotalMinor": { "type": "integer", "format": "int64", "description": "Subtotal after discounts and before taxes and fees, in minor currency units. Add the\n`totalDiscountsMinor` of each line item to it to get the amount before discounts.\n", "example": 12599 }, "taxAmount": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `taxAmountMinor` instead.\n\nTax amount for the order, in major currency units.\nSet to 0 for orders that will be invoiced separately.\n" }, "taxAmountMinor": { "type": "integer", "format": "int64", "description": "Tax amount for the order, in minor currency units.\nSet to 0 for orders that will be invoiced separately.\n", "example": 1008 }, "total": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `totalMinor` instead.\n\nTotal amount due for the order, in major currency units.\n" }, "totalMinor": { "type": "integer", "format": "int64", "description": "Total amount due for the order, in minor currency units.", "example": 13739 }, "amountDueNowMinor": { "type": "integer", "format": "int64", "description": "What the checkout collects when the order is placed, in minor currency units. Zero for an\norder that is invoiced instead, such as a postpaid subscription billed each month.\n\nThis is not `totalMinor`, which answers what the order costs however it is paid. Use this\none to decide whether to ask for a payment method.\n", "example": 13739 }, "taxIncluded": { "type": "boolean", "description": "Whether taxes are included in the total.", "example": true }, "currency": { "type": "string", "description": "The ISO 4217 currency code for all pricing amounts (e.g., \"USD\").", "example": "USD" }, "recurringCosts": { "type": "object", "description": "Expected recurring costs after the initial period.\nRepresents the typical monthly/billing cycle charges.\n\nA discount that ends with the periods paid for up front is not applied here.\n", "additionalProperties": false, "properties": { "subtotal": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `subtotalMinor` instead.\n\nRecurring subtotal after discounts and before taxes, in major currency units.\n" }, "subtotalMinor": { "type": "integer", "format": "int64", "description": "Recurring subtotal after discounts and before taxes, in minor currency units.", "example": 2999 }, "total": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `totalMinor` instead.\n\nTotal estimated recurring amount, in major currency units.\n" }, "totalMinor": { "type": "integer", "format": "int64", "description": "Total estimated recurring amount, in minor currency units.", "example": 3239 }, "taxAmount": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `taxAmountMinor` instead.\n\nEstimated tax on recurring charges, in major currency units.\n\nOnly calculated in certain regions. In the US, taxes are calculated at\nthe time of invoicing and are not estimated here.\n" }, "taxAmountMinor": { "type": "integer", "format": "int64", "description": "Estimated tax on recurring charges, in minor currency units.\n\nOnly calculated in certain regions. In the US, taxes are calculated at\nthe time of invoicing and are not estimated here.\n", "example": 240 }, "taxIncluded": { "type": "boolean", "description": "Whether taxes are included in the total.", "example": true }, "billingCycle": { "$ref": "#/components/schemas/BillingCycle" } } }, "initialInvoice": { "type": "object", "description": "Optional breakdown for the first invoice when different from recurring.\nUsed for prorated charges, first-month adjustments, etc.\n", "additionalProperties": false, "properties": { "subtotal": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `subtotalMinor` instead.\n\nFirst invoice subtotal (e.g., prorated amount, setup fees), in major currency units.\n" }, "subtotalMinor": { "type": "integer", "format": "int64", "description": "First invoice subtotal (e.g., prorated amount, setup fees), in minor currency units.", "example": 1450 }, "total": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `totalMinor` instead.\n\nTotal first invoice amount, in major currency units.\n" }, "totalMinor": { "type": "integer", "format": "int64", "description": "Total first invoice amount, in minor currency units.", "example": 1566 }, "taxAmount": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `taxAmountMinor` instead.\n\nEstimated tax on initial invoice charges, in major currency units.\n\nOnly calculated in certain regions. In the US, taxes are calculated at\nthe time of invoicing and are not estimated here.\n" }, "taxAmountMinor": { "type": "integer", "format": "int64", "description": "Estimated tax on initial invoice charges, in minor currency units.\n\nOnly calculated in certain regions. In the US, taxes are calculated at\nthe time of invoicing and are not estimated here.\n", "example": 116 }, "taxIncluded": { "type": "boolean", "description": "Whether taxes are included in the total.", "example": true }, "period": { "type": "object", "description": "Period covered by the initial invoice.", "additionalProperties": false, "properties": { "start": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "Start date of the initial billing period.", "example": "2024-01-15" }, "end": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "End date of the initial billing period.", "example": "2024-01-31" } } } } }, "calculatedAt": { "type": "string", "format": "date-time", "description": "When the pricing was last calculated.", "example": "2024-01-15T10:30:00Z" } } }, "TaxBreakdownItem": { "type": "object", "description": "A single tax or fee contributing to the total tax on a charge, such as state sales tax or a regulatory fee.", "required": [ "description", "amountMinor" ], "properties": { "description": { "type": "string", "description": "Human-readable name of the tax or fee, suitable for display on invoices and receipts.", "example": "Sales Tax" }, "amount": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `amountMinor` instead.\n\nThe amount charged for this tax component, in major units of the currency of the transaction.\n" }, "amountMinor": { "type": "integer", "format": "int64", "description": "The amount charged for this tax component, in minor units of the currency of the transaction.", "example": 240 }, "rate": { "type": "number", "format": "decimal", "description": "The tax rate applied, as a percentage (e.g., 8.25 for 8.25%). Omitted for flat fees that are not rate-based.", "example": 8.25 } } }, "OrderPricingDiscount": { "type": "object", "description": "One reduction applied to a line item, with where it came from and how long it lasts. Use `source`\nto tell a reduction the customer earned from one that every price carries, and `validTo` to tell\nthe customer when the price goes back up.\n", "required": [ "name", "amountMinor" ], "properties": { "name": { "type": "string", "description": "Discount name or description.", "example": "First month free" }, "amount": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `amountMinor` instead.\n\nDiscount amount (positive value), in major currency units.\n" }, "amountMinor": { "type": "integer", "format": "int64", "description": "Discount amount (positive value), in minor currency units.", "example": 2999 }, "source": { "type": "string", "description": "What gave the customer the discount:\n\n- `STANDARD` and `BINDING_CONTRACT` are part of the offering's own terms.\n- `PRICE_LIST` and `PRICE_LIST_DISCOUNT` come from the price list the customer is on.\n- `BINDING_PERIOD` comes from the contract the customer signed.\n- `UPFRONT_PAYMENT` is what the customer bought by paying for several periods at once.\n- `TAG` is a campaign the customer carries.\n- `PROMOTION_CODE` is the promotional code on the order.\n\nOmitted on an order priced before this field existed.\n", "enum": [ "STANDARD", "BINDING_CONTRACT", "PRICE_LIST", "PRICE_LIST_DISCOUNT", "BINDING_PERIOD", "UPFRONT_PAYMENT", "TAG", "PROMOTION_CODE" ], "example": "PROMOTION_CODE" }, "validFrom": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The first day the discount comes off the price." }, "validTo": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The last day the discount comes off the price. Omitted when the discount never stops.\n" } } }, "OrderLineItemPricing": { "type": "object", "description": "The calculated price of a single order line item, with its tax, fee, and discount breakdown.\nReturned by the order price calculation endpoint so you can show a per-item breakdown\nbefore the order is submitted. All amounts are in minor units of the order currency\n(e.g., 2999 = $29.99 when the currency is USD).\n", "required": [ "lineItemId", "subtotalMinor", "totalMinor" ], "properties": { "lineItemId": { "type": "string", "description": "The line item in the order that this pricing applies to.", "example": "line-item-1" }, "subtotal": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `subtotalMinor` instead.\n\nAmount for this line item after discounts and before taxes and fees, in major currency units.\n" }, "subtotalMinor": { "type": "integer", "format": "int64", "description": "Amount for this line item after discounts and before taxes and fees, in minor currency units.\nAdd `totalDiscountsMinor` to it to get the amount before discounts.\n", "example": 2999 }, "total": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `totalMinor` instead.\n\nAmount due for this line item after taxes, fees, and discounts, in major currency units.\n" }, "totalMinor": { "type": "integer", "format": "int64", "description": "Amount due for this line item after taxes, fees, and discounts, in minor currency units.", "example": 2747 }, "taxBreakdown": { "type": "array", "description": "The individual taxes and regulatory fees making up `taxAmountMinor`, as reported by the tax authority for this line item.", "items": { "$ref": "#/components/schemas/TaxBreakdownItem" } }, "taxAmount": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `taxAmountMinor` instead.\n\nTotal taxes for this line item, in major currency units.\n" }, "taxAmountMinor": { "type": "integer", "format": "int64", "description": "Total taxes for this line item, in minor currency units.", "example": 247 }, "taxIncluded": { "type": "boolean", "description": "Whether taxes are included in the total.", "example": true }, "discounts": { "type": "array", "description": "The individual discounts making up `totalDiscountsMinor`, such as a campaign, a promotion\ncode, a price list reduction or a binding period discount. The amounts cover everything this\norder charges for the line, which is more than one billing period when the order pays for\nseveral at once.\n", "items": { "$ref": "#/components/schemas/OrderPricingDiscount" } }, "recurringDiscounts": { "type": "array", "description": "The individual discounts inside `recurringAmountMinor`, for one billing period. Add back the\nones that carry a `validTo` to get what the line costs after they stop.\n", "items": { "$ref": "#/components/schemas/OrderPricingDiscount" } }, "totalDiscounts": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `totalDiscountsMinor` instead.\n\nTotal discounts for this line item, in major currency units.\n" }, "totalDiscountsMinor": { "type": "integer", "format": "int64", "description": "Total discounts for this line item, in minor currency units.", "example": 2999 }, "description": { "type": "string", "description": "Description of what this line item covers.", "example": "Premium Plan" }, "recurringAmount": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `recurringAmountMinor` instead.\n\nRecurring cost for this line item per billing cycle, in major currency units.\n" }, "recurringAmountMinor": { "type": "integer", "format": "int64", "description": "Recurring cost for this line item per billing cycle, in minor currency units.", "example": 2999 }, "chargedMonthAmountMinor": { "type": "integer", "format": "int64", "description": "What one month this order charges for costs, in minor currency units. Quote this next to\n`totalMinor` on an order that pays for several months at once, because `recurringAmountMinor`\nis what a month costs once the order renews, which is more. Do not divide `totalMinor` by\n`chargedMonths` instead: on a brand that bills calendar months, the order also charges a\nprorated part-month, and that part is in `totalMinor` but not in these two fields.\n", "example": 14458 }, "chargedMonths": { "type": "integer", "description": "How many consecutive months cost `chargedMonthAmountMinor`. A part-month first period is not\none of them. The count stops at the first month that costs something else, which is when a\ndiscount ends part way through the months the order pays for.\n", "example": 6 }, "initialInvoiceAmount": { "type": "number", "format": "decimal", "deprecated": true, "description": "Deprecated. Use `initialInvoiceAmountMinor` instead.\n\nAmount for this line item on the first invoice when different from recurring, in major currency units.\n" }, "initialInvoiceAmountMinor": { "type": "integer", "format": "int64", "description": "Amount for this line item on the first invoice when different from recurring, in minor currency units.", "example": 1450 } } }, "OrderPricing": { "description": "Detailed pricing information for an order including taxes and discounts.", "allOf": [ { "$ref": "#/components/schemas/OrderPricingSummary" }, { "properties": { "lineItems": { "description": "Pricing breakdown per line item.", "type": "array", "items": { "$ref": "#/components/schemas/OrderLineItemPricing" } } } } ] }, "InlineValidationError": { "type": "object", "description": "A single validation problem reported on an entity, explaining what must be corrected.\nFor example, orders return these for anything that blocks submission.\n", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Validation error message.", "example": "Subscriber name is required." }, "property": { "type": "string", "description": "Property related to the error, if applicable. May be nested using dot notation (e.g., \"customer.email\").", "example": "subscriber.name" } } }, "OrderRequirement": { "type": "string", "description": "Whether a submission step (payment, payment profile setup, or signing) must be completed\nbefore the order can be submitted. Determined by platform configuration and the contents\nof the order.\n\n- NOT_REQUIRED: The step does not apply; the order can be submitted without it.\n- OPTIONAL: The step may be completed, but the order can be submitted without it.\n- REQUIRED: The step must be completed and its session reference provided when submitting the order.\n", "enum": [ "NOT_REQUIRED", "OPTIONAL", "REQUIRED" ] }, "SubscriptionListItem": { "type": "object", "description": "Simplified subscription representation optimized for list operations. Use the detailed Subscription schema for individual subscription views.", "required": [ "subscriptionId", "status", "type", "display", "msisdn", "customerId", "productOfferingId", "subscriberId", "createdAt", "updatedAt" ], "properties": { "subscriptionId": { "type": "string", "description": "The unique identifier for the subscription.", "example": "d8174435-6378-4be5-a9f5-8b4aaadae5d4" }, "status": { "$ref": "#/components/schemas/SubscriptionStatus" }, "type": { "$ref": "#/components/schemas/SubscriptionType" }, "display": { "type": "string", "description": "Human-friendly name for the subscription, suitable for showing in UIs. Auto-generated as a pretty-printed version of the phone number unless a custom display name was set at creation.", "example": "(555) 123-4567" }, "msisdn": { "type": "string", "description": "The phone number currently active on this subscription, in E.164 format. MSISDN (Mobile Station International Subscriber Directory Number) is the telecom term for a subscriber's full international phone number.", "example": "+15551234567" }, "customerId": { "type": "string", "description": "The unique identifier for the customer who owns this subscription.", "example": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" }, "productOfferingId": { "type": "string", "description": "The unique identifier for the product offering associated with this subscription.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "subscriberId": { "type": "string", "description": "The unique identifier for the subscriber associated with this subscription.", "example": "b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e" }, "activatedAt": { "type": "string", "format": "date-time", "description": "The date and time when the subscription was activated. Absent until the subscription has been activated.", "example": "2024-01-15T10:30:00Z" }, "cancelledAt": { "type": "string", "format": "date-time", "description": "The date and time when the subscription was cancelled (if applicable).", "example": "2024-06-30T00:00:00Z" }, "createdAt": { "type": "string", "format": "date-time", "description": "The date and time when the subscription was created.", "example": "2024-01-10T08:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time when the subscription was last updated.", "example": "2024-01-15T10:30:00Z" } } }, "SubscriptionAddonListItem": { "type": "object", "description": "An add-on attached to a subscription, as returned inside subscription list responses. Carries the essentials for showing the add-on alongside its subscription; fetch the add-on individually for the full detail.", "required": [ "productOfferingId", "status" ], "properties": { "productOfferingId": { "type": "string", "description": "The unique identifier for the product offering.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "referenceId": { "type": "string", "description": "A reference identifier provided by API clients or upstream provider integrations\nto identify this subscription add-on in their own systems. Unique per tenant when\nset. Use this field to look up add-ons by your external identifier (for example a\nprovider-side package ID). Typically populated by a workflow once the add-on has\nbeen provisioned with the underlying network provider.\n", "example": "telna-package-12345", "maxLength": 255 }, "status": { "$ref": "#/components/schemas/SubscriptionAddonStatus" }, "productOfferingGroupId": { "type": "string", "description": "The unique identifier for the product offering group.", "example": "extra-data-packages" }, "licenseId": { "type": "string", "description": "The unique identifier of the license associated with this add-on (if applicable).", "example": "c9d0e1f2-a3b4-5678-9012-def012345678" }, "addedAt": { "type": "string", "format": "date-time", "description": "The date and time when the add-on was added to the subscription.", "example": "2024-01-15T10:30:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date and time when the add-on was last updated.", "example": "2024-01-20T09:00:00Z" }, "cancelledAt": { "type": "string", "format": "date-time", "description": "The date and time when the add-on was canceled (if applicable).", "example": "2024-06-30T00:00:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "LicenseListItem": { "type": "object", "description": "Simplified license representation optimized for list operations. The detailed License schema adds the customer and the product offering.", "required": [ "licenseId", "status", "type", "productOfferingId" ], "properties": { "licenseId": { "type": "string", "description": "The unique identifier for the license.", "example": "c9d0e1f2-a3b4-5678-9012-def012345678" }, "status": { "$ref": "#/components/schemas/LicenseStatus" }, "type": { "$ref": "#/components/schemas/LicenseType" }, "productOfferingId": { "type": "string", "description": "The unique identifier for the product offering that the license grants.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "subscriptionId": { "type": "string", "description": "The subscription that the license is assigned to. Absent for a license that stands alone.", "example": "d8174435-6378-4be5-a9f5-8b4aaadae5d4" }, "activatedAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the license was activated.", "example": "2024-01-15" }, "cancelledAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "The date when the license was canceled.", "example": "2024-06-30" } } }, "OrderModification": { "type": "object", "description": "A modification applied to an existing service during order fulfillment.", "required": [ "type", "targetId" ], "properties": { "type": { "type": "string", "enum": [ "SUBSCRIPTION_CHANGE", "ADDON_CHANGE" ], "description": "Type of modification applied." }, "targetId": { "type": "string", "description": "The subscription or add-on that was modified.", "example": "e8174435-6378-4be5-a9f5-8b4aaadae5d4" }, "newProductOfferingId": { "type": "string", "description": "The product offering the entity was changed to.", "example": "po_mobile_premium_plus" }, "appliedAt": { "type": "string", "format": "date-time", "description": "When the modification was applied.", "example": "2024-01-15T15:00:00Z" } } }, "Order": { "type": "object", "description": "A shopping cart for telecommunications services and products. Add line items to configure\nservices, get pricing, and submit for fulfillment. Orders track progress from creation through completion.\n", "required": [ "orderId", "state", "lineItems", "validation", "requirements", "createdAt", "expiresAt", "updatedAt" ], "properties": { "orderId": { "type": "string", "description": "Unique identifier for the order.", "example": "order-123" }, "state": { "$ref": "#/components/schemas/OrderState" }, "user": { "$ref": "#/components/schemas/OrderUserResult" }, "customer": { "$ref": "#/components/schemas/OrderCustomerResult" }, "billing": { "$ref": "#/components/schemas/OrderBilling" }, "shipping": { "$ref": "#/components/schemas/Shipping" }, "promoCode": { "type": "string", "description": "Promotional code applied to this order, if any.", "example": "STUDENT2024" }, "paymentSessionId": { "type": "string", "description": "The payment session that collected payment for this order, set when the order was submitted with one.", "example": "d2e3f4a5-b6c7-8901-2345-012345678901" }, "paymentProfileSessionId": { "type": "string", "description": "The payment profile session used to set up a payment method for this order, set when the order was submitted with one.", "example": "69321a62-f1fe-461f-8761-a19ae6587bb2" }, "signingSessionId": { "type": "string", "description": "The signing session that captured the customer's signature for this order, set when the order was submitted with one.", "example": "8f3b1c2d-4e5f-6789-abcd-1234567890ef" }, "consents": { "$ref": "#/components/schemas/Consents" }, "lineItems": { "type": "array", "description": "Line items in the order.", "items": { "$ref": "#/components/schemas/OrderLineItem" } }, "pricing": { "$ref": "#/components/schemas/OrderPricing" }, "validation": { "type": "object", "description": "Validation status of the order and its line items.", "additionalProperties": false, "required": [ "isValid" ], "properties": { "isValid": { "type": "boolean", "description": "Whether the order is valid and ready for submission.", "example": false }, "missingFields": { "type": "array", "description": "Required fields that are still missing.", "items": { "type": "string" }, "example": [ "customer", "billing.address" ] }, "errors": { "type": "array", "description": "Order-level validation errors.", "items": { "$ref": "#/components/schemas/InlineValidationError" } }, "lineItemValidation": { "type": "array", "description": "Validation status for each line item.", "items": { "type": "object", "additionalProperties": false, "properties": { "lineItemId": { "type": "string", "description": "Reference to the line item.", "example": "line-item-1" }, "isValid": { "type": "boolean", "description": "Whether this line item is valid.", "example": false }, "missingFields": { "type": "array", "description": "Required fields that are still missing.", "items": { "type": "string" }, "example": [ "subscriber.name", "sim.iccid" ] }, "errors": { "type": "array", "description": "Validation errors for this line item.", "items": { "$ref": "#/components/schemas/InlineValidationError" } } } } } } }, "requirements": { "type": "object", "description": "What this platform expects a checkout to collect before the order is submitted, so a client can build\nthe right flow up front. These are declared per platform, not derived from the contents of the order.\n\nSubmit enforces what the order itself demands rather than what is declared here: an order with an\namount left to collect is refused until that amount is paid, and an order that owes nothing submits\nwithout any payment reference.\n", "additionalProperties": false, "properties": { "requiresPayment": { "$ref": "#/components/schemas/OrderRequirement", "description": "Whether a checkout on this platform is expected to collect payment before submitting an order." }, "requiresPaymentProfile": { "$ref": "#/components/schemas/OrderRequirement", "description": "Whether a checkout on this platform is expected to save a payment profile for future billing, passing its paymentProfileSessionId when submitting an order." }, "requiresSigning": { "$ref": "#/components/schemas/OrderRequirement", "description": "Whether a checkout on this platform is expected to capture a digital signature, passing its signingSessionId when submitting an order." } } }, "externalPayment": { "type": "object", "description": "External payment details if the order was paid outside the system.", "additionalProperties": false, "properties": { "reference": { "type": "string", "description": "Reference from the external payment system.", "example": "ext-payment-ref-123" }, "receiptDescription": { "type": "string", "description": "Description of the external payment.", "example": "Payment via external billing system" }, "receiptUrl": { "type": "string", "format": "uri", "description": "URL to the external payment receipt.", "example": "https://external.example.com/receipts/123" }, "receivedAt": { "type": "string", "format": "date-time", "description": "When the external payment was recorded.", "example": "2024-01-15T14:30:00Z" } } }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the order expires if not submitted (automatically refreshed on each order update to maintain active session).", "example": "2024-01-22T10:30:00Z" }, "submittedAt": { "type": "string", "format": "date-time", "description": "When the order was submitted for fulfillment.", "example": "2024-01-15T14:30:00Z" }, "completedAt": { "type": "string", "format": "date-time", "description": "When the order was completed.", "example": "2024-01-15T15:00:00Z" }, "createdEntities": { "type": "object", "description": "Entities created as part of order fulfillment.", "additionalProperties": false, "properties": { "subscriptions": { "type": "array", "description": "Subscriptions created during order fulfillment.", "items": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionListItem" }, { "required": [ "createdByLineItem" ], "additionalProperties": false, "properties": { "createdByLineItem": { "type": "string", "description": "Line item ID that created this subscription.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" } } } ] } }, "addons": { "type": "array", "description": "Add-ons created during order fulfillment.", "items": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionAddonListItem" }, { "required": [ "createdByLineItem" ], "additionalProperties": false, "properties": { "createdByLineItem": { "type": "string", "description": "Line item ID that created this add-on.", "example": "h47ac10b-58cc-4372-a567-0e02b2c3d479" } } } ] } }, "licenses": { "type": "array", "description": "Standalone licenses created during order fulfillment. A license that belongs to an add-on is not listed here.", "items": { "allOf": [ { "$ref": "#/components/schemas/LicenseListItem" }, { "required": [ "createdByLineItem" ], "additionalProperties": false, "properties": { "createdByLineItem": { "type": "string", "description": "Line item ID that created this license.", "example": "j47ac10b-58cc-4372-a567-0e02b2c3d479" } } } ] } }, "modifications": { "type": "array", "description": "Modifications applied during order fulfillment.", "items": { "allOf": [ { "$ref": "#/components/schemas/OrderModification" }, { "required": [ "createdByLineItem" ], "additionalProperties": false, "properties": { "createdByLineItem": { "type": "string", "description": "Line item ID that created this modification.", "example": "i47ac10b-58cc-4372-a567-0e02b2c3d479" } } } ] } } } }, "createdAt": { "type": "string", "format": "date-time", "description": "When the order was created.", "example": "2024-01-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the order was last updated.", "example": "2024-01-15T10:30:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "UpdateOrderRequest": { "type": "object", "description": "Request to update order details (excludes line items).", "additionalProperties": false, "properties": { "user": { "$ref": "#/components/schemas/OrderUserReference" }, "customer": { "$ref": "#/components/schemas/OrderCustomerReference" }, "billing": { "$ref": "#/components/schemas/OrderBillingInput" }, "shipping": { "$ref": "#/components/schemas/ShippingInput" }, "consents": { "$ref": "#/components/schemas/Consents" }, "promoCode": { "type": "string", "description": "Promo code to apply to the order, or an empty string to remove the one it holds. Rejected with\n`internalCode` 4119 when no promotion has that code, or when it is outside its validity\nperiod.\n", "example": "STUDENT2024" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "AddLineItemRequest": { "type": "object", "description": "Request to add a line item to an order.", "required": [ "lineItem" ], "additionalProperties": false, "properties": { "lineItem": { "$ref": "#/components/schemas/OrderLineItem" } } }, "UpdateLineItemRequest": { "type": "object", "description": "Request to update a line item configuration.", "required": [ "lineItem" ], "additionalProperties": false, "properties": { "lineItem": { "$ref": "#/components/schemas/OrderLineItem" } } }, "SubmitOrderRequest": { "type": "object", "description": "Request to submit an order for fulfillment.\n\nDepending on the order's requirements, payment intent, saved payment profile, or signing reference may be required.\n\nIn a fully managed flow, the order may be auto-submitted on successfully fulfilling all requirements (e.g. successful payment or signing).\n", "additionalProperties": false, "properties": { "paymentSessionId": { "type": "string", "description": "Reference to completed payment session for orders requiring payment collection.", "example": "a1b2c3d4-e5f6-7890-1234-56789abcdef0" }, "paymentProfileSessionId": { "type": "string", "description": "Reference to completed payment profile session for zero-total orders requiring payment method setup.", "example": "b2c3d4e5-f6a7-8901-2345-6789abcdef01" }, "signingSessionId": { "type": "string", "description": "Reference to completed signing session.", "example": "c3d4e5f6-a7b8-9012-3456-789abcdef012" }, "externalPayment": { "type": "object", "description": "Details of an external payment made outside the system. When provided, the order\nis considered paid and will bypass internal payment requirements.\n\nCannot be used together with paymentSessionId.\n", "additionalProperties": false, "required": [ "reference" ], "properties": { "reference": { "type": "string", "minLength": 1, "description": "Reference or identifier from the external payment system.", "example": "ext-payment-ref-123" }, "receiptDescription": { "type": "string", "description": "Optional human-readable description of the payment.", "example": "Payment via external billing system" }, "receiptUrl": { "type": "string", "format": "uri", "description": "Optional URL to a receipt or confirmation page for the payment.", "example": "https://external.example.com/receipts/123" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "ApproveOrderRequest": { "type": "object", "description": "Approve an order that requires admin or manager approval before fulfillment can proceed.", "additionalProperties": false, "properties": { "comment": { "type": "string", "maxLength": 1000, "description": "Optional comment explaining the approval decision.", "example": "Approved after reviewing customer credit check" } } }, "OrderHandoffToken": { "type": "object", "description": "A short-lived token that lets a checkout pick up a draft order that was built\nelsewhere, for example by a support agent or a chat assistant. Anyone holding\nthe token can view and complete the order, so pass it only to the person the\norder is for.\n", "required": [ "handoffToken", "orderId", "expiresAt" ], "properties": { "handoffToken": { "type": "string", "description": "The raw handoff token. It is only returned here and cannot be retrieved again; mint a new one if it is lost.", "example": "oht_f47ac10b58cc4372a5670e02b2c3d479" }, "orderId": { "type": "string", "description": "The order this token hands off.", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When the token stops being claimable. The order itself also expires on its own schedule.", "example": "2024-01-15T11:00:00Z" } } }, "OrderHandoffClaim": { "type": "object", "description": "The order a handoff token resolves to.", "required": [ "orderId", "customerType" ], "properties": { "orderId": { "type": "string", "description": "The order the token hands off.", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, "customerType": { "$ref": "#/components/schemas/CustomerType" } } }, "InvoiceStatus": { "type": "string", "description": "Current stage of the invoice lifecycle.\n\n- DRAFT: Being prepared; not yet visible to the customer.\n- SENT: Delivered to the customer and awaiting payment.\n- PAID: Payment has been received.\n- VOID: Canceled and no longer collectible.\n- OVERDUE: Past its due date without payment.\n", "enum": [ "DRAFT", "SENT", "PAID", "VOID", "OVERDUE" ] }, "InvoiceListItem": { "type": "object", "description": "An invoice summary without its line items, optimized for list views. Fetch the individual invoice for the full line item breakdown.", "required": [ "invoiceId", "customerId", "status", "invoiceNumber", "dueDate", "createdAt", "updatedAt" ], "properties": { "invoiceId": { "type": "string", "description": "Unique identifier for the invoice.", "example": "094f10ca-616e-441c-b264-9a2305d6692d" }, "customerId": { "type": "string", "description": "The customer this invoice is for.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "invoiceNumber": { "type": "string", "description": "Human-readable invoice number.", "example": "INV-2024-001" }, "status": { "$ref": "#/components/schemas/InvoiceStatus", "description": "Current status of the invoice.", "example": "SENT" }, "dueDate": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "When payment is due.", "example": "2024-02-15" }, "subtotalAmountMinor": { "type": "integer", "format": "int64", "description": "Sum of all line items before taxes, fees, and discounts, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).", "example": 2999 }, "totalAmountMinor": { "type": "integer", "format": "int64", "description": "Total amount the customer owes for this invoice after taxes, fees, and discounts, in minor currency units.", "example": 2989 }, "currency": { "type": "string", "description": "The ISO 4217 currency code for all invoice amounts (e.g., \"USD\").", "example": "USD" }, "sentAt": { "type": "string", "format": "date-time", "description": "When the invoice was sent to the customer (if status is sent or later).", "example": "2024-01-15T10:00:00Z" }, "paidAt": { "type": "string", "format": "date-time", "description": "When the invoice was paid (if status is paid).", "example": "2024-02-10T14:30:00Z" }, "voidedAt": { "type": "string", "format": "date-time", "description": "When the invoice was voided (if status is void).", "example": "2024-02-05T09:00:00Z" }, "invoiceUrl": { "type": "string", "format": "uri", "description": "Hosted URL where customer can view the invoice.", "example": "https://invoices.yourapp.com/094f10ca-616e-441c-b264-9a2305d6692d" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the invoice was created.", "example": "2024-01-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the invoice was last updated.", "example": "2024-01-15T10:00:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "InvoiceLineItem": { "type": "object", "description": "Individual line item within an invoice, showing detailed pricing breakdown.", "required": [ "description", "subtotalMinor", "totalMinor" ], "properties": { "description": { "type": "string", "description": "Description of what this line item represents.", "example": "Mobile subscription - Premium Plan" }, "subscriptionId": { "type": "string", "description": "ID of the subscription this line item is associated with, if applicable.", "example": "b8174435-6378-4be5-a9f5-8b4aaadae5d4" }, "licenseId": { "type": "string", "description": "ID of the license this line item is associated with, if applicable.", "example": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77" }, "productOfferingId": { "type": "string", "description": "ID of the product offering this line item is associated with, if applicable.", "example": "mobile-plan-premium" }, "quantity": { "type": "integer", "description": "Quantity of items for this line item.", "minimum": 1, "example": 1 }, "unitPriceMinor": { "type": "integer", "format": "int64", "description": "Price per unit before taxes and fees, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).", "example": 2999 }, "subtotalMinor": { "type": "integer", "format": "int64", "description": "Line item subtotal (quantity x unitPriceMinor), in minor currency units.", "example": 2999 }, "totalMinor": { "type": "integer", "format": "int64", "description": "Line item total after taxes, fees, and discounts, in minor currency units.", "example": 3739 }, "taxBreakdown": { "type": "array", "description": "Tax breakdown for this line item.", "items": { "$ref": "#/components/schemas/TaxBreakdownItem" } }, "taxAmountMinor": { "type": "integer", "format": "int64", "description": "Total taxes for this line item, in minor currency units.", "example": 240 }, "taxIncluded": { "type": "boolean", "description": "Whether taxes are included in the total.", "example": false }, "fees": { "type": "array", "description": "Detailed fee breakdown for this line item.", "items": { "type": "object", "required": [ "name", "amountMinor" ], "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Fee name or description.", "example": "Late payment fee" }, "amountMinor": { "type": "integer", "format": "int64", "description": "Fee amount, in minor currency units.", "example": 1000 } } } }, "totalFeesMinor": { "type": "integer", "format": "int64", "description": "Total fees for this line item, in minor currency units.", "example": 1000 }, "discounts": { "type": "array", "description": "Detailed discount breakdown for this line item.", "items": { "type": "object", "required": [ "name", "amountMinor" ], "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Discount name or description.", "example": "Volume discount" }, "amountMinor": { "type": "integer", "format": "int64", "description": "Discount amount (positive value), in minor currency units.", "example": 500 } } } }, "totalDiscountsMinor": { "type": "integer", "format": "int64", "description": "Total discounts for this line item, in minor currency units.", "example": 500 } } }, "Invoice": { "type": "object", "description": "An invoice with detailed line item breakdown that can be sent to customers for payment.", "required": [ "invoiceId", "customerId", "status", "lineItems", "invoiceNumber", "dueDate", "createdAt", "updatedAt" ], "properties": { "invoiceId": { "type": "string", "description": "Unique identifier for the invoice.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "customerId": { "type": "string", "description": "The customer this invoice is for.", "example": "456789ab-cdef-0123-4567-89abcdef0123" }, "invoiceNumber": { "type": "string", "description": "Human-readable invoice number.", "example": "INV-2024-001" }, "status": { "$ref": "#/components/schemas/InvoiceStatus", "description": "Current status of the invoice.", "example": "SENT" }, "dueDate": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "When payment is due.", "example": "2024-02-15" }, "lineItems": { "type": "array", "description": "Detailed breakdown of items included in this invoice.", "items": { "$ref": "#/components/schemas/InvoiceLineItem" } }, "subtotalAmountMinor": { "type": "integer", "format": "int64", "description": "Sum of all line items before taxes, fees, and discounts, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).", "example": 2999 }, "taxAmountMinor": { "type": "integer", "format": "int64", "description": "Total tax amount for the invoice, in minor currency units.", "example": 240 }, "feeAmountMinor": { "type": "integer", "format": "int64", "description": "Total fee amount for the invoice, in minor currency units.", "example": 250 }, "discountAmountMinor": { "type": "integer", "format": "int64", "description": "Total amount deducted by discounts (positive value), in minor currency units.", "example": 500 }, "totalAmountMinor": { "type": "integer", "format": "int64", "description": "Total amount the customer owes for this invoice after taxes, fees, and discounts, in minor currency units.", "example": 2989 }, "currency": { "type": "string", "description": "The ISO 4217 currency code for all invoice amounts (e.g., \"USD\").", "example": "USD" }, "sentAt": { "type": "string", "format": "date-time", "description": "When the invoice was sent to the customer (if status is sent or later).", "example": "2024-01-15T10:00:00Z" }, "paidAt": { "type": "string", "format": "date-time", "description": "When the invoice was paid (if status is paid).", "example": "2024-02-10T14:30:00Z" }, "voidedAt": { "type": "string", "format": "date-time", "description": "When the invoice was voided (if status is void).", "example": "2024-02-05T09:00:00Z" }, "invoiceUrl": { "type": "string", "format": "uri", "description": "Hosted URL where customer can view the invoice.", "example": "https://invoices.yourapp.com/inv_123e4567" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the invoice was created.", "example": "2024-01-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the invoice was last updated.", "example": "2024-01-15T10:00:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "MarkInvoiceAsPaidRequest": { "type": "object", "description": "Request to mark an invoice as paid when you manage your own payment processing.", "additionalProperties": false, "properties": { "paidAt": { "type": "string", "format": "date-time", "description": "When the payment was received. If not provided, uses the current timestamp.", "example": "2024-02-10T14:30:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata", "description": "Metadata to attach to the invoice." } } }, "PaymentLinkStatus": { "type": "string", "description": "Current status of a payment link.\n\n- ACTIVE: The link is open and the customer can complete payment.\n- EXPIRED: The link expired before payment was completed.\n- COMPLETED: Payment through the link succeeded.\n- CANCELED: The link was canceled and can no longer be used.\n- FAILED: Payment through the link failed.\n", "enum": [ "ACTIVE", "EXPIRED", "COMPLETED", "CANCELED", "FAILED" ] }, "PaymentProvider": { "type": "string", "description": "Payment service provider that processes the transaction.", "enum": [ "STRIPE", "BILLOGRAM" ], "example": "STRIPE" }, "PaymentLink": { "type": "object", "description": "A shareable hosted payment page that collects payment for an order at the customer's\nconvenience. Create one when the customer is not in an active checkout flow — for example\nto send by email or SMS — and anyone with the URL can complete the payment.\n\nUse a payment session instead when the customer is present in your checkout and should be\nredirected to pay immediately. Both collect against the order's underlying payment intent,\nwhich records the resulting charges and refunds.\n", "required": [ "paymentLinkId", "hostedUrl", "status", "createdAt", "updatedAt" ], "properties": { "paymentLinkId": { "type": "string", "description": "Unique identifier for the payment link.", "example": "j47ac10b-58cc-4372-a567-0e02b2c3d479" }, "orderId": { "type": "string", "description": "The order this payment link collects payment for.", "example": "44567801-a504-4f09-8089-31ea78bc239b" }, "customerId": { "type": "string", "description": "The customer this payment link collects payment from.", "example": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" }, "paymentProvider": { "$ref": "#/components/schemas/PaymentProvider" }, "paymentProfileId": { "type": "string", "description": "The saved payment method pre-selected for the customer, if any.", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, "hostedUrl": { "type": "string", "format": "uri", "description": "The URL where customers can complete their payment.", "example": "https://checkout.yourapp.com/pay/j47ac10b-58cc-4372-a567-0e02b2c3d479" }, "status": { "$ref": "#/components/schemas/PaymentLinkStatus" }, "description": { "type": "string", "description": "Optional description displayed on the payment page.", "example": "Pay your monthly subscription" }, "paymentIntentId": { "type": "string", "description": "The payment intent that collected the payment, available once the link has been paid.", "example": "64870b5c-fb61-4c9a-955a-e148e0826c20" }, "completedAt": { "type": "string", "format": "date-time", "description": "When the payment was completed, if the link has been paid.", "example": "2024-01-15T14:30:00Z" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the payment link was created.", "example": "2024-01-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the payment link was last updated.", "example": "2024-01-15T10:00:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "CreatePaymentLinkRequest": { "type": "object", "description": "Request to create a new payment link for processing payment for an order or invoice. Either orderId or invoiceId must be provided, not both.", "additionalProperties": false, "properties": { "orderId": { "type": "string", "description": "The unique identifier of the order to create a payment link for. Either orderId or invoiceId must be provided, not both.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "invoiceId": { "type": "string", "description": "The unique identifier of the invoice to create a payment link for. Either orderId or invoiceId must be provided, not both. Invoice payment links are not yet available in all environments.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "paymentProfileId": { "type": "string", "description": "A previously saved payment method to prefill on the payment page, for returning customers.", "example": "6ba7b810-9dad-11d1-80b4-00c04fd430c8" }, "savePaymentProfile": { "type": "boolean", "description": "Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.", "example": true }, "setAsDefaultPaymentProfile": { "type": "boolean", "description": "Whether to set the payment method as the default for future payments. Only applicable if savePaymentProfile is true and the customer is authenticated or for the initial order. Defaults to false.\n", "example": false }, "description": { "type": "string", "description": "Optional description to display on the payment page.", "example": "Payment for Telness mobile subscription" }, "grantAutopayConsent": { "type": "boolean", "description": "Whether the customer consents to being charged automatically for future renewals. Only applicable if savePaymentProfile is true. Automatic charging also requires a usable default payment profile. Defaults to false.\n", "example": false }, "returnUrl": { "type": "string", "format": "uri", "description": "URL to redirect customers to after successful payment.", "example": "https://your-domain.com/success" }, "cancelUrl": { "type": "string", "format": "uri", "description": "URL to redirect customers to if they cancel the payment.", "example": "https://your-domain.com/cancel" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "PaymentIntentStatus": { "type": "string", "description": "Current stage of a payment intent as it is collected through the payment provider.\n\n- PENDING: Created, no charge attempted yet.\n- REQUIRES_ACTION: The customer must take action to continue (e.g., 3D Secure authentication).\n- PROCESSING: A charge is in flight with the payment provider.\n- SUCCEEDED: The full amount has been collected.\n- REQUIRES_PAYMENT_METHOD: The last charge attempt failed; a new or updated payment method is needed to retry.\n- CANCELED: Collection was canceled and no further charges will be attempted.\n", "enum": [ "PENDING", "REQUIRES_ACTION", "PROCESSING", "SUCCEEDED", "REQUIRES_PAYMENT_METHOD", "CANCELED" ], "example": "SUCCEEDED" }, "PaymentIntentListItem": { "type": "object", "description": "A payment intent without its nested attempts, refunds, and line items, optimized for list views.", "required": [ "paymentIntentId", "customerId", "status", "amountMinor", "currency", "createdAt", "updatedAt" ], "properties": { "paymentIntentId": { "type": "string", "description": "The unique identifier for this payment intent.", "example": "64870b5c-fb61-4c9a-955a-e148e0826c20" }, "customerId": { "type": "string", "description": "The customer this payment intent collects from.", "example": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" }, "status": { "$ref": "#/components/schemas/PaymentIntentStatus" }, "amountMinor": { "type": "integer", "format": "int64", "description": "The total amount to collect, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).", "example": 2900 }, "currency": { "type": "string", "description": "The ISO 4217 currency code the amount is collected in (e.g., \"USD\").", "example": "USD" }, "description": { "type": "string", "description": "A human-readable description of what is being collected.", "example": "Mobile subscription renewal" }, "dueAt": { "type": "string", "format": "date-time", "description": "When the amount is due.", "example": "2024-01-15T10:00:00Z" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the payment intent was created.", "example": "2024-01-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the payment intent was last updated.", "example": "2024-01-15T10:00:00Z" } } }, "PaymentIntentLineItem": { "type": "object", "description": "A single billed item contributing to a payment intent's amount.", "required": [ "description", "amountMinor" ], "properties": { "description": { "type": "string", "description": "What this line item represents.", "example": "Mobile subscription - Premium Plan" }, "amountMinor": { "type": "integer", "format": "int64", "description": "The base cost of the line item before discounts and taxes, in minor units of the payment intent's currency (e.g., 2900 = $29.00 when the currency is USD).", "example": 2900 }, "subscriptionId": { "type": "string", "description": "The subscription this line item is associated with, if any.", "example": "a8174435-6378-4be5-a9f5-8b4aaadae5d4" }, "licenseId": { "type": "string", "description": "The license this line item is associated with, if any.", "example": "ffb19d4f-b3b6-4f2b-9365-dd80bdcf0a77" }, "discounts": { "type": "array", "description": "Discounts applied to this line item.", "items": { "type": "object", "required": [ "description", "amountMinor" ], "additionalProperties": false, "properties": { "description": { "type": "string", "description": "What the discount is for.", "example": "Loyalty discount" }, "amountMinor": { "type": "integer", "format": "int64", "description": "The discounted amount (positive value), in minor units of the payment intent's currency.", "example": 500 } } } }, "taxes": { "type": "array", "description": "Taxes applied to this line item.", "items": { "type": "object", "required": [ "description", "amountMinor" ], "additionalProperties": false, "properties": { "description": { "type": "string", "description": "The tax component applied (e.g., a named tax and its rate).", "example": "VAT 25%" }, "amountMinor": { "type": "integer", "format": "int64", "description": "The tax amount, in minor units of the payment intent's currency.", "example": 725 } } } } } }, "PaymentAttempt": { "type": "object", "description": "A single charge attempt against a payment intent.", "required": [ "paymentAttemptId", "amountMinor", "currency", "result", "createdAt" ], "properties": { "paymentAttemptId": { "type": "string", "description": "The unique identifier for this charge attempt.", "example": "a4da2b04-aa79-4b40-8987-048d6caf118f" }, "amountMinor": { "type": "integer", "format": "int64", "description": "The amount charged in this attempt, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).", "example": 2900 }, "currency": { "type": "string", "description": "The ISO 4217 currency code the attempt was charged in (e.g., \"USD\").", "example": "USD" }, "result": { "type": "string", "description": "Whether the charge attempt succeeded or failed.", "enum": [ "SUCCEEDED", "FAILED" ], "example": "SUCCEEDED" }, "reason": { "type": "string", "description": "Failure reason when the attempt did not succeed.", "example": "card_declined" }, "chargedAt": { "type": "string", "format": "date-time", "description": "When the charge was made.", "example": "2024-01-15T10:00:00Z" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the attempt was created.", "example": "2024-01-15T10:00:00Z" } } }, "PaymentRefund": { "type": "object", "description": "A refund issued against a payment intent.", "required": [ "refundId", "amountMinor", "currency", "status", "createdAt" ], "properties": { "refundId": { "type": "string", "description": "The unique identifier for this refund.", "example": "c014b666-22e4-430e-bb18-9257a383dfe2" }, "amountMinor": { "type": "integer", "format": "int64", "description": "The refunded amount, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).", "example": 2900 }, "currency": { "type": "string", "description": "The ISO 4217 currency code the refund is issued in (e.g., \"USD\").", "example": "USD" }, "reason": { "type": "string", "description": "Why the refund was issued.", "enum": [ "UNKNOWN", "DUPLICATE", "FRAUDULENT", "REQUESTED_BY_CUSTOMER" ], "example": "REQUESTED_BY_CUSTOMER" }, "status": { "type": "string", "description": "Current stage of the refund.", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "CANCELED", "REQUIRES_ACTION" ], "example": "SUCCEEDED" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the refund was created.", "example": "2024-01-15T10:00:00Z" } } }, "PaymentIntent": { "type": "object", "description": "The record of an amount being collected from a customer over card rails, with the charge\nattempts, refunds, and billed line items that show how collection went.\n\nA payment intent is created automatically when payment collection starts for an order,\nwhether through a payment session or a payment link; you do not create one directly.\nRead it to see what was charged, retried, or refunded. To start collecting payment,\ncreate a payment session (customer present in your checkout) or a payment link\n(shareable hosted page) instead.\n", "required": [ "paymentIntentId", "customerId", "status", "amountMinor", "currency", "lineItems", "attempts", "refunds", "createdAt", "updatedAt" ], "properties": { "paymentIntentId": { "type": "string", "description": "The unique identifier for this payment intent.", "example": "64870b5c-fb61-4c9a-955a-e148e0826c20" }, "customerId": { "type": "string", "description": "The customer this payment intent collects from.", "example": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" }, "status": { "$ref": "#/components/schemas/PaymentIntentStatus" }, "amountMinor": { "type": "integer", "format": "int64", "description": "The total amount to collect, in minor units of the currency (e.g., 2900 = $29.00 when the currency is USD).", "example": 2900 }, "currency": { "type": "string", "description": "The ISO 4217 currency code the amount is collected in (e.g., \"USD\").", "example": "USD" }, "description": { "type": "string", "description": "A human-readable description of what is being collected.", "example": "Mobile subscription renewal" }, "dueAt": { "type": "string", "format": "date-time", "description": "When the amount is due.", "example": "2024-01-15T10:00:00Z" }, "lineItems": { "type": "array", "description": "The items that make up the collected amount.", "items": { "$ref": "#/components/schemas/PaymentIntentLineItem" } }, "attempts": { "type": "array", "description": "Charge attempts made against this payment intent, most recent first.", "items": { "$ref": "#/components/schemas/PaymentAttempt" } }, "refunds": { "type": "array", "description": "Refunds issued against this payment intent.", "items": { "$ref": "#/components/schemas/PaymentRefund" } }, "createdAt": { "type": "string", "format": "date-time", "description": "When the payment intent was created.", "example": "2024-01-15T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the payment intent was last updated.", "example": "2024-01-15T10:00:00Z" } } }, "PaymentSessionBranding": { "type": "object", "description": "The colors and the name that the payment form shows. Every property is optional. A property you\nleave out keeps the default of the payment provider. Branding does not change the layout or the\nspacing of the form.\n", "additionalProperties": false, "properties": { "backgroundColor": { "type": "string", "description": "The background color of the payment form, as a hex value with a leading number sign.", "pattern": "^#[0-9a-fA-F]{6}$", "example": "#ffffff" }, "buttonColor": { "type": "string", "description": "The color of the payment button, as a hex value with a leading number sign.", "pattern": "^#[0-9a-fA-F]{6}$", "example": "#0cf68c" }, "borderStyle": { "type": "string", "description": "The shape of the buttons and the input fields of the payment form.", "enum": [ "PILL", "RECTANGULAR", "ROUNDED" ], "example": "PILL" }, "displayName": { "type": "string", "description": "The name that the payment form shows at the top. Your legal business name stays on the\nreceipt and in the terms.\n", "maxLength": 100, "example": "Seamless" } } }, "CreatePaymentSessionRequest": { "type": "object", "description": "Request to create a new payment session for processing payment for an order.", "required": [ "orderId", "paymentProvider", "returnUrl" ], "additionalProperties": false, "properties": { "orderId": { "type": "string", "description": "The unique identifier of the order to create a payment session for.", "example": "d4e5f6a7-b8c9-0123-4567-89abcdef0123" }, "paymentProvider": { "$ref": "#/components/schemas/PaymentProvider" }, "paymentProfileId": { "type": "string", "description": "A previously saved payment method to prefill on the payment page, for returning customers.", "example": "e5f6a7b8-c9d0-1234-5678-9abcdef01234" }, "savePaymentProfile": { "type": "boolean", "description": "Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.", "example": true }, "setAsDefaultPaymentProfile": { "type": "boolean", "description": "Whether to set the payment method as the default for future payments. Only applicable if savePaymentProfile is true and the customer is authenticated or for the initial order. Defaults to false.\n", "example": false }, "grantAutopayConsent": { "type": "boolean", "description": "Whether the customer consents to being charged automatically for future renewals. Only applicable if savePaymentProfile is true. Automatic charging also requires a usable default payment profile. Defaults to false.\n", "example": false }, "hosted": { "type": "boolean", "description": "Whether to collect the payment on a hosted page. A hosted session returns hostedUrl, and you\nsend the customer to it. An embedded session (false) returns providerContext, and you show the\npayment form inside your own checkout page. Defaults to true.\n", "example": true }, "returnUrl": { "type": "string", "description": "The URL the customer comes back to after they pay. A hosted page redirects to it. An embedded\nform redirects to it only for a payment method that leaves the page, such as 3D Secure. Must\nbe provided to create a session.\n", "example": "https://example.com/order/confirmation" }, "cancelUrl": { "type": "string", "description": "The URL the customer is redirected to if they cancel the payment on the hosted page. A hosted session only.", "example": "https://example.com/order/checkout" }, "branding": { "$ref": "#/components/schemas/PaymentSessionBranding" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "StripeCheckoutContext": { "type": "object", "description": "The Stripe values that mount an embedded Stripe Checkout in your own page. Load Stripe.js with\nthe publishable key and the connected account, then mount the checkout with the client secret.\nThe client secret authorizes this one payment session. Do not store it and do not send it to\nanybody but the payer's browser.\n", "required": [ "clientSecret", "publishableKey", "connectedAccountId" ], "properties": { "clientSecret": { "type": "string", "description": "The client secret of the Stripe Checkout Session. Give it to Stripe.js to mount the checkout.", "example": "cs_test_a1b2c3d4e5f6g7h8i9j0_secret_k1l2m3n4o5" }, "publishableKey": { "type": "string", "description": "The Stripe publishable key to load Stripe.js with. The key is public.", "example": "pk_test_51H8x2vLkdIwHu7ixaZ0m8Kj9" }, "connectedAccountId": { "type": "string", "description": "The Stripe connected account that holds this payment. Load Stripe.js with it as the Stripe account.", "example": "acct_1H8x2vLkdIwHu7ix" } } }, "PaymentSessionProviderContext": { "type": "object", "description": "What the payment provider needs to render its payment form inside your own checkout page. It is\nreturned only when you create the payment session with hosted set to false, and only by the\ncreate call. A hosted session gives you hostedUrl instead.\n\nThis object is the one place where the API is specific to a payment provider. Read the child\nobject that agrees with paymentProvider, and add a new child when you add a provider. Every other\npayment field stays independent of the provider.\n", "required": [ "paymentProvider" ], "properties": { "paymentProvider": { "$ref": "#/components/schemas/PaymentProvider" }, "stripe": { "$ref": "#/components/schemas/StripeCheckoutContext" } } }, "PaymentSessionStatus": { "type": "string", "description": "Current status of a payment session lifecycle.", "enum": [ "PENDING", "REQUIRES_ACTION", "COMPLETED", "FAILED", "CANCELED", "EXPIRED" ], "example": "PENDING" }, "PaymentSession": { "type": "object", "description": "A single checkout attempt that collects payment for an order while the customer is present.\nCreate one during your checkout flow, let the customer pay, then pass its paymentSessionId when\nyou submit the order.\n\nThere are two ways to collect the payment. A hosted session gives you hostedUrl, and you send the\ncustomer to that page. An embedded session (create it with hosted set to false) gives you\nproviderContext, and you show the payment form inside your own checkout page.\n\nUse a payment link instead when the customer is not in an active checkout (e.g., to send a\npayment page by email), and read the order's payment intent to see the resulting charges\nand refunds.\n", "required": [ "paymentSessionId", "orderId", "paymentProvider", "savePaymentProfile", "status", "metadata", "createdAt", "updatedAt" ], "properties": { "paymentSessionId": { "type": "string", "description": "The unique identifier for this payment session.", "example": "d2e3f4a5-b6c7-8901-2345-012345678901" }, "orderId": { "type": "string", "description": "The unique identifier of the order this payment session is for.", "example": "e3f4a5b6-c7d8-9012-3456-123456789012" }, "paymentProvider": { "$ref": "#/components/schemas/PaymentProvider" }, "paymentProfileId": { "type": "string", "description": "The saved payment method to use for this payment (for returning customers).", "example": "f4a5b6c7-d8e9-0123-4567-234567890123" }, "savePaymentProfile": { "type": "boolean", "description": "Whether to save the payment profile for future use. Only applicable if the customer is authenticated or for the initial order. Defaults to false.", "example": true }, "hostedUrl": { "type": "string", "format": "uri", "description": "The hosted checkout page to redirect the customer to in order to complete payment. A hosted session only.", "example": "https://payments.example.com/checkout/d2e3f4a5-b6c7-8901-2345-012345678901" }, "providerContext": { "$ref": "#/components/schemas/PaymentSessionProviderContext" }, "returnUrl": { "type": "string", "description": "The URL the customer is redirected to after payment completion.", "example": "https://example.com/order/confirmation" }, "cancelUrl": { "type": "string", "description": "The URL the customer is redirected to if they cancel the payment.", "example": "https://example.com/order/checkout" }, "status": { "$ref": "#/components/schemas/PaymentSessionStatus" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs for additional payment session information.", "example": { "source": "mobile_app", "campaign": "summer_2024" } }, "createdAt": { "type": "string", "format": "date-time", "description": "When this payment session was created.", "example": "2024-09-29T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this payment session was last updated.", "example": "2024-09-29T10:30:00Z" } } }, "CancelPaymentSessionRequest": { "type": "object", "description": "Request to cancel an active payment session.", "additionalProperties": false, "properties": { "reason": { "type": "string", "description": "Optional reason for cancelling the payment session.", "example": "Customer changed their mind" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs for additional cancellation information.", "example": { "cancelled_by": "customer_service", "ticket_id": "SUPP-12345" } } } }, "PaymentMethodType": { "type": "string", "description": "The kind of payment method, as reported by the payment provider. This is an\nopen set of provider-defined values (for example \"CARD\", \"SEPA_DEBIT\", \"SWISH\",\n\"VIPPS\", \"KLARNA\", \"PAYPAL\") rather than a fixed enumeration, so new method\ntypes can appear without an API change.\n", "example": "CARD" }, "PaymentProfileStatus": { "type": "string", "description": "Whether a saved payment profile can currently be charged.\n\n- ACTIVE: The payment method is valid and can be used for payments.\n- INACTIVE: The payment method has been deactivated and cannot be charged.\n- EXPIRED: The payment method has expired (e.g., an expired card) and must be replaced.\n- REQUIRES_ACTION: The customer must take action (e.g., re-authentication) before the payment method can be used again.\n", "enum": [ "ACTIVE", "INACTIVE", "EXPIRED", "REQUIRES_ACTION" ] }, "EmbeddedPaymentProfile": { "type": "object", "description": "A saved payment method with only the details needed to display it in a list, without billing information.", "required": [ "paymentProfileId", "type", "status", "createdAt" ], "properties": { "paymentProfileId": { "type": "string", "description": "Unique identifier for this payment profile.", "example": "f6a7b8c9-d0e1-2345-6789-abcdef012345" }, "paymentProvider": { "$ref": "#/components/schemas/PaymentProvider" }, "type": { "$ref": "#/components/schemas/PaymentMethodType", "description": "Type of payment method.", "example": "CARD" }, "status": { "$ref": "#/components/schemas/PaymentProfileStatus", "description": "Current status of the payment profile.", "example": "ACTIVE" }, "displayName": { "type": "string", "description": "Human-readable name for the payment method, safe to show to the customer:\n- Card: \"Visa ending in 4242\"\n- SEPA: \"Bank account ending in 3000\"\n- Swish: \"Swish +46701234567\"\n", "example": "Visa ending in 4242" }, "isDefault": { "type": "boolean", "description": "Whether this is the customer's default payment profile.", "example": true }, "expiresAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "When this payment profile expires (for cards).", "example": "2025-12-31" }, "createdAt": { "type": "string", "format": "date-time", "description": "When this payment profile was created.", "example": "2024-01-15T10:00:00Z" } } }, "PaymentProfile": { "type": "object", "description": "A saved payment method or mandate for future use.", "required": [ "paymentProfileId", "type", "status", "customerId", "createdAt" ], "properties": { "paymentProfileId": { "type": "string", "description": "Unique identifier for this payment profile.", "example": "d9f0b83a-8b0d-44a6-af7c-54b6b91b6040" }, "paymentProvider": { "$ref": "#/components/schemas/PaymentProvider", "description": "The payment provider for this payment profile.", "example": "STRIPE" }, "type": { "$ref": "#/components/schemas/PaymentMethodType", "description": "Type of payment method.", "example": "CARD" }, "status": { "$ref": "#/components/schemas/PaymentProfileStatus", "description": "Current status of the payment profile.", "example": "ACTIVE" }, "customerId": { "type": "string", "description": "Customer who owns this payment profile.", "example": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d" }, "displayName": { "type": "string", "description": "Human-readable name for this payment method.", "example": "My credit card" }, "expiresAt": { "type": "string", "format": "date", "x-ogen-type": "telnesstech.com/apiv2/apiv2types.Date", "description": "When this payment profile expires (for cards).", "example": "2025-12-31" }, "billingDetails": { "type": "object", "description": "Billing details associated with this payment method.", "additionalProperties": false, "properties": { "name": { "type": "string", "description": "Billing name.", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "Billing email.", "example": "john.doe@example.com" }, "address": { "$ref": "#/components/schemas/Address" } } }, "createdAt": { "type": "string", "format": "date-time", "description": "When this payment profile was created.", "example": "2024-01-15T10:00:00Z" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "CreatePaymentProfileSessionRequest": { "type": "object", "description": "Request to create a new payment profile session for setting up a saved payment method.", "required": [ "orderId", "paymentProvider", "returnUrl" ], "additionalProperties": false, "properties": { "orderId": { "type": "string", "description": "The unique identifier of the order this payment profile session is associated with.", "example": "9f8e7d6c-5b4a-3210-9876-543210987654" }, "paymentProvider": { "$ref": "#/components/schemas/PaymentProvider" }, "returnUrl": { "type": "string", "description": "The URL the customer is redirected to after the payment method is saved.", "example": "https://example.com/order/confirmation" }, "cancelUrl": { "type": "string", "description": "The URL the customer is redirected to if they cancel before saving a payment method.", "example": "https://example.com/order/checkout" }, "setAsDefaultPaymentProfile": { "type": "boolean", "description": "Whether to set the saved payment method as the customer's default for future payments. Defaults to false.", "example": false }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "PaymentProfileSessionStatus": { "type": "string", "description": "Current status of a payment profile session lifecycle.", "enum": [ "PENDING", "REQUIRES_ACTION", "COMPLETED", "FAILED", "CANCELED" ], "example": "PENDING" }, "PaymentProfileSession": { "type": "object", "description": "A session that walks the customer through setting up and saving a payment method for\nfuture billing, without charging them. Create one when an order requires a payment\nprofile but no upfront payment (e.g., a zero-total order), redirect the customer to\nhostedUrl, and pass the completed session's paymentProfileSessionId when submitting\nthe order. To collect an actual payment, create a payment session instead.\n", "required": [ "paymentProfileSessionId", "orderId", "paymentProvider", "status", "hostedUrl", "metadata", "createdAt", "updatedAt" ], "properties": { "paymentProfileSessionId": { "type": "string", "description": "The unique identifier for this payment profile session.", "example": "69321a62-f1fe-461f-8761-a19ae6587bb2" }, "orderId": { "type": "string", "description": "The unique identifier of the order this payment profile session is associated with.", "example": "44567801-a504-4f09-8089-31ea78bc239b" }, "paymentProvider": { "$ref": "#/components/schemas/PaymentProvider" }, "status": { "$ref": "#/components/schemas/PaymentProfileSessionStatus" }, "hostedUrl": { "type": "string", "format": "uri", "description": "The hosted page to redirect the customer to in order to save their payment method.", "example": "https://payments.example.com/setup/69321a62-f1fe-461f-8761-a19ae6587bb2" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs for additional payment profile session information.", "example": { "source": "mobile_app", "campaign": "summer_2024" } }, "createdAt": { "type": "string", "format": "date-time", "description": "When this payment profile session was created.", "example": "2024-09-29T10:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When this payment profile session was last updated.", "example": "2024-09-29T10:30:00Z" } } }, "CancelPaymentProfileSessionRequest": { "type": "object", "description": "Request to cancel an active payment profile session.", "additionalProperties": false, "properties": { "reason": { "type": "string", "description": "Optional reason for cancelling the payment profile session.", "example": "Customer decided not to save payment method" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom key-value pairs for additional cancellation information.", "example": { "cancelled_by": "customer_service", "ticket_id": "SUPP-12345" } } } }, "SigningStatus": { "type": "string", "description": "The current status of a signing session.", "enum": [ "PENDING", "IN_PROGRESS", "COMPLETED", "FAILED", "EXPIRED", "CANCELLED" ] }, "SigningSession": { "type": "object", "description": "A contract signing session for an order requiring legal signature.", "required": [ "signingSessionId", "orderId", "status", "signerDetails", "createdAt" ], "properties": { "signingSessionId": { "type": "string", "description": "The unique identifier for this signing session.", "example": "f7d2295f-0dd4-4ebe-8ec5-de2d0f41be7e" }, "orderId": { "type": "string", "description": "The order that requires signing.", "example": "44567801-a504-4f09-8089-31ea78bc239b" }, "status": { "$ref": "#/components/schemas/SigningStatus" }, "signerDetails": { "type": "object", "description": "Information about the person signing the contract.\n\nThe specific fields required depend on the signing provider. Use GET /signing/providers to discover which fields are required for each provider.\n", "additionalProperties": { "type": "string" }, "example": { "name": "John Doe", "email": "john.doe@example.com", "identity": "199001011234" } }, "provider": { "type": "string", "description": "The signing provider used for this session.", "example": "bankid" }, "language": { "type": "string", "description": "The language used for the signing interface.", "example": "en", "default": "en" }, "redirectUrl": { "type": "string", "format": "uri", "description": "The URL where the user should be redirected to complete signing.", "example": "https://sign.provider.com/session/abc123" }, "returnUrl": { "type": "string", "format": "uri", "description": "The URL where the user will be redirected after signing completion.", "example": "https://yourapp.com/orders/123/complete" }, "documentUrl": { "type": "string", "format": "uri", "description": "Download URL for the signed contract. Only available when status is COMPLETED.", "example": "https://api.yourapp.com/documents/signed-contract-123.pdf" }, "completedAt": { "type": "string", "format": "date-time", "description": "When the signing was completed. Only present when status is COMPLETED.", "example": "2024-01-15T14:30:00Z" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When this signing session expires.", "example": "2024-01-15T23:59:59Z" }, "failureReason": { "type": "string", "description": "The reason for signing failure. Only present when status is FAILED.", "example": "User canceled signing process" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the signing session was created.", "example": "2024-01-15T10:00:00Z" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional metadata for the signing session.", "example": { "contract_type": "postpaid_subscription", "customer_segment": "b2b" } } } }, "CreateSigningSessionRequest": { "type": "object", "description": "Request to create a contract signing session for an order.", "required": [ "orderId", "signerDetails", "returnUrl" ], "additionalProperties": false, "properties": { "orderId": { "type": "string", "description": "The order that requires contract signing.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "signerDetails": { "type": "object", "description": "Information about the person who will sign the contract.\n\nThe specific fields required depend on the signing provider. Use GET /signing/providers to discover which fields are required for each provider.\n", "additionalProperties": { "type": "string" }, "example": { "name": "John Doe", "email": "john.doe@example.com", "identity": "199001011234" } }, "returnUrl": { "type": "string", "format": "uri", "description": "The URL where the user will be redirected after signing completion or failure.", "example": "https://yourapp.com/orders/123/complete" }, "provider": { "type": "string", "description": "The preferred signing provider. If not specified, the default provider will be used.", "example": "bankid" }, "language": { "type": "string", "description": "The language for the signing interface.", "default": "en", "example": "sv" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional metadata for the signing session.", "example": { "contract_type": "postpaid_subscription", "customer_segment": "b2b" } } } }, "SigningRequirement": { "type": "string", "enum": [ "OPTIONAL", "REQUIRED" ], "description": "Whether a signer detail field is optional or required for a signing provider.\n\n- 'OPTIONAL': The field is optional and may be omitted.\n- 'REQUIRED': The field is required and must be provided.\n" }, "SigningProvider": { "type": "object", "description": "A signing provider and its requirements for signer details.", "required": [ "provider", "name", "requirements" ], "properties": { "provider": { "type": "string", "description": "The unique identifier for the signing provider.", "example": "bankid" }, "name": { "type": "string", "description": "The display name of the signing provider.", "example": "BankID" }, "description": { "type": "string", "description": "A brief description of the signing provider and its use cases.", "example": "Swedish digital identity verification and signing service" }, "supportedCountries": { "type": "array", "items": { "type": "string" }, "description": "List of country codes where this provider is available.", "example": [ "SE" ] }, "supportedLanguages": { "type": "array", "items": { "type": "string" }, "description": "List of language codes supported by this provider.", "example": [ "sv", "en" ] }, "requirements": { "type": "object", "description": "Information that may or must be collected from the signer before initiating the signing process.\n\nEach key represents a field name in the signerDetails object, and the value indicates whether it's optional or required.\n", "additionalProperties": { "$ref": "#/components/schemas/SigningRequirement" }, "example": { "name": "REQUIRED", "email": "REQUIRED", "identity": "REQUIRED" } }, "capabilities": { "type": "object", "description": "Additional capabilities and features supported by this provider.", "additionalProperties": false, "properties": { "multipleSigners": { "type": "boolean", "description": "Whether the provider supports multiple signers on the same document.", "example": false }, "documentTemplates": { "type": "boolean", "description": "Whether the provider supports custom document templates.", "example": true }, "biometricSigning": { "type": "boolean", "description": "Whether the provider supports biometric signing methods.", "example": true } } } } }, "ValidateAddressRequest": { "type": "object", "description": "Request to validate an address.", "required": [ "address" ], "additionalProperties": false, "properties": { "address": { "$ref": "#/components/schemas/Address" } } }, "AddressValidationResult": { "type": "object", "description": "Result of address validation with optional suggestions.\n\nDepending on setup, address validation is either shape based (e.g. this looks like an address),\nor verified against an address registry.\n", "required": [ "valid" ], "properties": { "valid": { "type": "boolean", "description": "Whether the provided address is valid.", "example": false }, "suggestedAddress": { "$ref": "#/components/schemas/Address", "description": "If provided, a suggestion for a corrected address by the underlying address validation service.\n\nDo note that this may be returned for seemingly valid addresses, where the network has a more precise or standardized version of the address.\nA typical example of this is the address is found in the networks' registry but under a different name because it contains aliases or minor formatting issues, mistyped zip codes, etc.\n" }, "validationDetails": { "type": "object", "description": "Additional validation details.", "additionalProperties": false, "properties": { "issues": { "type": "array", "description": "Specific issues found with the address.", "items": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Description of the issue found.", "example": "Missing city" }, "property": { "type": "string", "description": "The property or field related to the issue (e.g., \"street\", \"zipCode\").", "example": "city" } } } } }, "example": { "issues": [ { "message": "Missing city", "property": "city" }, { "message": "Invalid zip format", "property": "zip" } ] } } } }, "CheckPortingEligibilityRequest": { "type": "object", "description": "Request to check if a phone number is eligible for porting.", "required": [ "msisdn" ], "additionalProperties": false, "properties": { "msisdn": { "type": "string", "format": "phone", "description": "The phone number to check for porting eligibility.", "example": "+15551234567" } } }, "PortingEligibilityResult": { "type": "object", "description": "Result of number porting eligibility check.", "required": [ "eligible", "msisdn" ], "properties": { "msisdn": { "type": "string", "format": "phone", "description": "The phone number that was checked.", "example": "+15551234567" }, "eligible": { "type": "boolean", "description": "Whether the number is eligible for porting.", "example": true }, "networkProviderId": { "type": "string", "description": "The identifier for the current network provider, if detectable", "example": "tmobile-us" }, "ineligibilityReason": { "type": "string", "description": "Reason why number is not eligible (only present if eligible is false).", "example": "Number not found or not portable" } } }, "GetDeviceInfoRequest": { "type": "object", "description": "Request to get device information by IMEI.", "required": [ "imei" ], "additionalProperties": false, "properties": { "imei": { "type": "string", "description": "The International Mobile Equipment Identity of the device.", "example": "356938035643809" } } }, "DeviceInfo": { "type": "object", "description": "Information about a device based on its IMEI.", "required": [ "imei", "esim" ], "properties": { "imei": { "type": "string", "description": "The device IMEI that was checked.", "example": "356938035643809" }, "tac": { "type": "string", "description": "The device TAC (Type Allocation Code), which is the first 8 digits of the IMEI identifying the device model and manufacturer.\n", "example": "35693803" }, "esim": { "type": "boolean", "description": "Whether the device supports eSIM.", "example": true }, "manufacturer": { "type": "string", "description": "Device manufacturer.", "example": "Apple" }, "model": { "type": "string", "description": "Device model.", "example": "A2653" }, "marketingName": { "type": "string", "description": "Device marketing name.", "example": "iPhone 15 Pro" } } }, "SearchDevicesRequest": { "type": "object", "description": "Request to find devices by name.\n\nUse this when the customer knows their device by its everyday name and not by its IMEI, for\nexample to find out whether it supports eSIM before they order.\n", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "string", "minLength": 2, "description": "Part of the device name to match, such as the brand, the model, or both.", "example": "iPhone 15" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20, "description": "The largest number of devices to return.", "example": 20 } } }, "DeviceMatch": { "type": "object", "description": "A device the network knows by name. It carries no IMEI, because a name matches a model rather than one handset.", "required": [ "esim" ], "properties": { "tac": { "type": "string", "description": "The device TAC (Type Allocation Code), which is the first 8 digits of an IMEI identifying the device model and manufacturer.\n", "example": "35693803" }, "esim": { "type": "boolean", "description": "Whether the device supports eSIM.", "example": true }, "manufacturer": { "type": "string", "description": "Device manufacturer.", "example": "Apple" }, "model": { "type": "string", "description": "Device model.", "example": "A2653" }, "marketingName": { "type": "string", "description": "Device marketing name.", "example": "iPhone 15 Pro" } } }, "DeviceSearchResult": { "type": "object", "description": "The devices whose name matches the query.", "required": [ "items" ], "properties": { "items": { "type": "array", "description": "One entry per matching device. An empty list means the network knows no device by that name.", "items": { "$ref": "#/components/schemas/DeviceMatch" } } } }, "CoverageAddress": { "type": "object", "description": "A location to check network coverage at.\n\nOnly the ZIP code and the country are required. Some networks qualify a whole postal area and\nread nothing else. Send the full address when you have it. A network that grades a point needs\nthe street and the city to place it.\n", "required": [ "zip", "country" ], "properties": { "street": { "type": "string", "description": "The first line of the address, typically street and house number.", "example": "500 S Main St" }, "street1": { "type": "string", "deprecated": true, "description": "Deprecated. Use `street` instead.\n\nThe first line of the address, typically street and house number.\n" }, "street2": { "type": "string", "description": "The second line of the address, typically apartment, suite, unit, building, floor, etc.", "example": "Apt 1" }, "city": { "type": "string", "description": "The city or municipality of the address.", "example": "Natick" }, "zip": { "type": "string", "description": "The zip code of the address.\n\nDepending on the country, this may be referred to as a postal code or postcode.\n\nSpecifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121').\n", "example": "01701" }, "country": { "type": "string", "description": "The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden).", "pattern": "^[A-Z]{2}$", "example": "US" }, "state": { "type": "string", "description": "For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States).", "example": "CA" } } }, "CheckNetworkCoverageRequest": { "type": "object", "description": "Request to check network coverage at a location.", "required": [ "address" ], "additionalProperties": false, "properties": { "address": { "$ref": "#/components/schemas/CoverageAddress" } } }, "Coordinates": { "type": "object", "description": "A geographic location in WGS84 coordinates, the standard used by GPS.", "required": [ "latitude", "longitude" ], "properties": { "latitude": { "type": "number", "format": "float", "description": "Latitude in decimal degrees. Positive values are north of the equator.", "example": 40.7128 }, "longitude": { "type": "number", "format": "float", "description": "Longitude in decimal degrees. Negative values are west of the prime meridian.", "example": -74.006 } } }, "TechnologyCoverage": { "type": "object", "description": "Coverage details for a single network technology (such as 4G or 5G) at a checked location.", "required": [ "available" ], "properties": { "available": { "type": "boolean", "description": "Whether this technology is available at the checked location.", "example": true } } }, "NetworkCoverage": { "type": "object", "description": "Network coverage information for a location.\n\nNetworks answer two different questions. One resolves the address to a point and grades the\nsignal there. Another qualifies a whole postal area for activation and grades nothing. Read\n`scope` to know which answer you got, and read `serviceable` for the verdict itself.\n\nWhat data is returned depends on the underlying network provider, so only the required\nfields are guaranteed to be present.\n", "required": [ "address", "serviceable", "scope" ], "properties": { "address": { "$ref": "#/components/schemas/CoverageAddress", "description": "The address that was checked." }, "serviceable": { "type": "boolean", "description": "Whether the network serves this location. Every network answers this.\n\nA network that grades signal reports `true` when at least one technology reaches the\nlocation. A network that qualifies a postal area reports `true` when it can activate a\nsubscription there.\n", "example": true }, "scope": { "type": "string", "enum": [ "ADDRESS", "POSTAL_AREA" ], "description": "What the verdict applies to.\n\n`ADDRESS` means the network placed the exact address and answered about that point.\n`POSTAL_AREA` means the network read the zip code alone, so the same answer applies to\nevery address in it.\n", "example": "ADDRESS" }, "coverageLevel": { "type": "string", "enum": [ "EXCELLENT", "GOOD", "FAIR", "POOR", "NO_COVERAGE" ], "description": "Overall network coverage quality at this location.\n\nAbsent when the network grades no signal. Do not read an absent grade as poor coverage:\nread `serviceable` instead.\n", "example": "GOOD" }, "coordinates": { "$ref": "#/components/schemas/Coordinates", "description": "Resolved coordinates for the address, if available." }, "networkProviderId": { "type": "string", "description": "Which network this coverage data applies to.", "example": "tmobile-us" }, "coverage": { "type": "object", "description": "Coverage information per technology, if available.", "required": [ "3g", "4g", "5g" ], "properties": { "3g": { "$ref": "#/components/schemas/TechnologyCoverage" }, "4g": { "$ref": "#/components/schemas/TechnologyCoverage" }, "5g": { "$ref": "#/components/schemas/TechnologyCoverage" } }, "additionalProperties": { "$ref": "#/components/schemas/TechnologyCoverage" } }, "roamingStatus": { "type": "string", "description": "The roaming status at this location, if reported by the network provider (e.g., whether the location is served by the home network or a roaming partner).", "example": "HOME" } } }, "NumberType": { "type": "string", "enum": [ "CELL", "FIXED", "DATA", "M2M" ], "description": "The service class of a phone number, determining what kind of subscription it can be used for.\n\n- CELL: Mobile number for voice, SMS, and data subscriptions\n- FIXED: Fixed-line (landline) number\n- DATA: Number for data-only subscriptions\n- M2M: Number for machine-to-machine/IoT subscriptions\n", "example": "CELL" }, "LeaseNumbersRequest": { "type": "object", "description": "Request to lease phone numbers for use in orders.", "required": [ "types", "count" ], "additionalProperties": false, "properties": { "types": { "type": "array", "description": "Types of numbers to lease.", "items": { "$ref": "#/components/schemas/NumberType" }, "example": [ "CELL" ] }, "count": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Number of phone numbers to lease.", "example": 2 } } }, "LeasedNumber": { "type": "object", "description": "A phone number that has been leased for use in orders.", "required": [ "msisdn", "type", "grade", "expiresAt" ], "properties": { "msisdn": { "type": "string", "format": "phone", "description": "The leased phone number.", "example": "+15551234567" }, "type": { "$ref": "#/components/schemas/NumberType" }, "grade": { "type": "integer", "minimum": 1, "maximum": 10, "description": "Quality grade of the number (1=premium, 10=standard).", "example": 5 }, "availableAt": { "type": "string", "format": "date-time", "description": "When this number became available for leasing.", "example": "2024-01-15T10:00:00Z" }, "leasedAt": { "type": "string", "format": "date-time", "description": "When this number was leased.", "example": "2024-01-15T10:30:00Z" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When this lease expires if not used in an order.", "example": "2024-01-15T11:30:00Z" }, "metadata": { "type": "object", "description": "Additional number metadata.", "additionalProperties": { "type": "string" }, "example": { "region": "New York", "areaCode": "555" } } } }, "NumberLeaseResult": { "type": "object", "description": "Result of a number leasing request.", "required": [ "numbers", "leaseToken", "expiresAt" ], "properties": { "numbers": { "type": "array", "description": "The leased phone numbers.", "items": { "$ref": "#/components/schemas/LeasedNumber" } }, "leaseToken": { "type": "string", "description": "Token to use when creating subscription line items with these numbers.\n\nProvide this token in the `leaseToken` field when ordering or creating a subscription\nalong with the chosen `msisdn` from the leased numbers.\n", "example": "lease_abc123def456" }, "expiresAt": { "type": "string", "format": "date-time", "description": "When this lease expires if not used in an order.", "example": "2024-01-15T11:30:00Z" } } }, "SimType": { "type": "string", "description": "The technology type of the SIM card.\n\n- PHYSICAL: A plastic SIM card that is shipped and inserted into the device\n- ESIM: An embedded SIM profile that is downloaded digitally to the device, typically via QR code\n", "enum": [ "PHYSICAL", "ESIM" ] }, "SimStatus": { "type": "string", "description": "Current lifecycle status of the SIM card in inventory.\n\n- AVAILABLE: In stock and free to be assigned to a subscription\n- IN_USE: Currently assigned to an active subscription\n- RESERVED: Held for a pending order or activation\n- CONSUMED: Used up and no longer assignable (for example a single-use eSIM profile)\n- BRAND_RESERVED: Set aside for a specific brand and not generally assignable\n", "enum": [ "AVAILABLE", "IN_USE", "RESERVED", "CONSUMED", "BRAND_RESERVED" ] }, "EsimInstallationStatus": { "type": "string", "description": "The installation state of an eSIM profile on the network.\nReflects the current eUICC profile lifecycle stage as reported by the network operator.\n", "enum": [ "AVAILABLE", "ALLOCATED", "LINKED", "CONFIRMED", "RELEASED", "DOWNLOADED", "INSTALLED", "ENABLED", "DISABLED", "ERROR", "UNAVAILABLE", "DELETED" ] }, "EsimProfile": { "type": "object", "description": "Live eSIM profile status from the network operator.\nShows whether the eSIM has been downloaded, installed, or enabled on a device.\n", "required": [ "status" ], "properties": { "status": { "$ref": "#/components/schemas/EsimInstallationStatus" }, "eid": { "type": "string", "description": "The EID (eSIM Identifier) assigned to the device. Empty until the eSIM is activated.", "example": "89049032004008882600009B40002780" }, "lastOperationAt": { "type": "string", "format": "date-time", "description": "When the last eUICC operation occurred for this profile.", "example": "2024-06-15T14:30:00Z" }, "installedCount": { "type": "integer", "description": "The number of times a device installed this profile. Absent when the network operator sets no limit.", "example": 3 }, "maxCount": { "type": "integer", "description": "The maximum number of times a device can install this profile. Absent when the network operator sets no limit.", "example": 5 } } }, "InventorySim": { "type": "object", "description": "A SIM card from inventory. For eSIM cards, the response may include live installation\nstatus from the network operator when the SIM is linked to a subscription.\n", "required": [ "iccid", "type", "status" ], "properties": { "iccid": { "type": "string", "description": "The ICCID (Integrated Circuit Card Identifier) of the SIM card.", "example": "8946200508271016579" }, "imsi": { "type": "string", "description": "The IMSI (International Mobile Subscriber Identity) of the SIM.", "example": "310150000000001" }, "type": { "$ref": "#/components/schemas/SimType" }, "status": { "$ref": "#/components/schemas/SimStatus" }, "lpa": { "type": "string", "description": "Local Profile Assistant address for eSIM activation.", "example": "1$rsp.example.com$ABCD1234" }, "esimProfile": { "$ref": "#/components/schemas/EsimProfile" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the SIM was added to inventory.", "example": "2024-01-10T08:00:00Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "When the SIM was last updated in inventory.", "example": "2024-06-15T14:30:00Z" } } }, "EmbeddedWorkflowTask": { "type": "object", "description": "Essential workflow task information for tracking webhook-triggered workflow executions.", "required": [ "workflowTaskId", "name", "createdAt" ], "properties": { "workflowTaskId": { "type": "string", "description": "The unique identifier for the workflow task.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "name": { "type": "string", "description": "The name of the workflow that was triggered.", "example": "Process Customer Order" }, "description": { "type": "string", "description": "A description of what the workflow task does.", "example": "Processes new customer orders and initiates fulfillment" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the workflow task was created.", "example": "2024-01-15T10:30:00Z" } } }, "ReportRunStatus": { "type": "string", "description": "The current stage of a report run in its lifecycle.", "enum": [ "QUEUED", "RUNNING", "SUCCEEDED", "FAILED" ] }, "ReportRun": { "type": "object", "description": "A generated report and its current state. When the report has finished generating, a time-limited download link is provided so the file can be fetched directly.", "required": [ "reportRunId", "reportKey", "status", "downloadUrl", "createdAt", "completedAt" ], "properties": { "reportRunId": { "type": "string", "format": "uuid", "description": "The unique identifier for this report run.", "example": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }, "reportKey": { "type": "string", "description": "Identifies which report was generated.", "example": "subscriber_base_and_revenue" }, "status": { "$ref": "#/components/schemas/ReportRunStatus" }, "downloadUrl": { "type": [ "string", "null" ], "format": "uri", "description": "A time-limited link to download the generated file. Present only once the report has succeeded; null while it is still generating or if it failed.", "example": "https://example-bucket.s3.amazonaws.com/reports/f47ac10b.csv?X-Amz-Signature=..." }, "createdAt": { "type": "string", "format": "date-time", "description": "When the report run was requested." }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the report run finished generating. Null while it is still in progress." } } }, "EventEnvelope": { "type": "object", "description": "The common wrapper around every webhook delivery. Each webhook POST body contains this envelope:\na stable event identifier for deduplication, the event type to dispatch on, when the change\nhappened, and the event-specific payload in `data`.\n", "required": [ "eventId", "type", "occurredAt", "apiRevision", "data" ], "properties": { "eventId": { "type": "string", "format": "uuid", "description": "Unique identifier for this event (stable for the logical event; multiple delivery attempts reuse the same id). Use for idempotency.", "example": "b3a2d5c4-1f2e-4a6b-9c7d-1234567890ab" }, "type": { "type": "string", "description": "Event type identifier (dot namespaced, e.g. subscription.created).", "example": "subscription.created" }, "occurredAt": { "type": "string", "format": "date-time", "description": "RFC 3339 timestamp when the underlying change occurred.", "example": "2024-01-15T10:30:00Z" }, "apiRevision": { "type": "string", "description": "The API revision that this payload is in. A delivery carries no API key, so the revision comes from the webhook setting of your account and not from a request. Admin \u003e Advanced \u003e Webhooks in the portal shows it and moves it.", "example": "2026-08-21.auk" }, "data": { "description": "Event-specific payload; structure depends on event type." } } } }, "responses": { "BadRequest": { "description": "The request was malformed or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "The request body is invalid.", "code": "bad_request", "details": [ { "message": "Email format is invalid.", "code": "invalid_email", "property": "contact.email" } ], "hint": "Check the request payload and correct the highlighted fields." } } } }, "TooManyRequests": { "description": "Too many requests have been sent in a given amount of time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Too many requests. Please slow down.", "code": "too_many_requests", "hint": "Retry after the number of seconds indicated in the Retry-After header." } } } }, "InternalServerError": { "description": "An unexpected error occurred on the server.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "An unexpected error occurred on the server.", "code": "internal_server_error", "hint": "Retry the request later. If the problem persists, contact support." } } } }, "Unauthorized": { "description": "Authentication is required to access this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Authentication is required to access this resource.", "code": "unauthorized", "hint": "Provide a valid API key in the X-Api-Key header." } } } }, "Forbidden": { "description": "Access to this resource is forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "You do not have permission to perform this action.", "code": "forbidden", "hint": "Ensure your API key or user has the required permissions." } } } }, "NotFound": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "The requested customer could not be found.", "code": "not_found", "hint": "Verify the customerId and try again." } } } }, "Conflict": { "description": "The request conflicts with the current state of the resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "The request conflicts with the current state of the resource.", "code": "conflict", "hint": "Reload the resource to get its latest state before retrying." } } } }, "PreconditionFailed": { "description": "A precondition for this request was not met.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "A precondition given in the request headers was not met.", "code": "precondition_failed", "hint": "Fetch the current resource and retry with an up-to-date precondition." } } } }, "ServiceUnavailable": { "description": "The network this endpoint asks could not answer. The request was correct and\nthe endpoint is available for this brand, so the same request can succeed\nlater. Retry after a short delay.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "The service is temporarily unavailable. Please try again.", "code": "unavailable", "hint": "The network behind this brand did not answer. Try again in a moment." } } } }, "NotImplemented": { "description": "This endpoint is not available for this brand. The network it asks cannot\nanswer the question, so no request will succeed until the brand is configured\nwith a network that can.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "This endpoint is not available in this environment.", "code": "not_implemented", "hint": "The network behind this brand cannot answer this request." } } } } }, "parameters": { "Limit": { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "description": "The maximum number of items to return." }, "Cursor": { "in": "query", "name": "cursor", "schema": { "type": "string" }, "description": "Opaque pagination token from a previous response's nextCursor." }, "IdempotencyKey": { "in": "header", "name": "X-Idempotency-Key", "required": false, "description": "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.\nThe key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request.\n\nModified requests with the same idempotency keys are rejected with a `409 Conflict` status code.\n", "schema": { "type": "string", "maxLength": 256 } } } } }