--- title: Customers description: Manage customers. --- # Customers Manage customers. ## [GET /customers](/api-reference/customers#tag/customers/GET/customers) List customers List all customers. Will return all customers the requester has access to. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Query parameters - `filter` (`string`, optional) — A free text search string to filter customers. - `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return. - `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor. ### Responses #### 200 A list of customers. Type: `object` - `items` (`array of Customer`, required) - `customerId` (`string`, required, example a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d) — Unique identifier for the customer. - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `name` (`string`, required, example John Doe) — The customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API. - `identity` (`string`, optional, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `preferredLocale` (`string`, optional, default en-US, example en-US) — The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE"). - `humanReadableId` (`string`, optional, example 29A-BY3Z-X78) — A human-readable identifier for the customer that customers can state in support requests. - `referenceId` (`string`, optional, max length 255, example crm-customer-12345) — A reference identifier provided by API clients to identify this customer in their own systems. Must be unique per tenant. Use this field to look up customers or to create/retrieve customers during order creation. - `contact` (`object`, required) — Contact details for the customer. - `email` (`string`, optional, email, example john.doe@example.com) — The primary contact email for the customer. - `msisdn` (`string`, optional, phone, example +15551234567) — The primary contact phone number for the customer. - `billing` (`object`, optional) — Billing configuration and payment preferences for the customer. - `method` (`enum`, required, one of E_INVOICE, EMAIL_INVOICE, PAPER_INVOICE) — How invoices should be delivered to the customer. — How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address. - `email` (`string`, optional, email, example billing@company.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `address` (`object`, optional) — The billing address for the customer. Required if billing method is PAPER_INVOICE. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `currency` (`string`, required, example USD) — The currency for customer billing and payments. — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `defaultPaymentProfileId` (`string`, optional, example c1d2e3f4-a5b6-7890-1234-901234567890) — Default payment profile to use for automatic payments and new orders. If specified, enables automatic payment collection for invoices and bills. - `autoPay` (`boolean`, optional, default false, example true) — Whether the customer authorized automatic charges to their default payment profile. An automatic charge also needs an active default payment profile that works off-session. - `users` (`array of EmbeddedCustomerUser`, optional) — The users associated with this customer, each with the role that governs what they can manage on the customer's account. - `userId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — Unique identifier for the user. Use it with the user endpoints to fetch full details. - `name` (`string`, required, example John Doe) — The user's full name. - `role` (`enum`, optional, one of MEMBER, MANAGER, ADMIN) — The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access. - `contactPerson` (`object`, optional) — The primary contact person for the customer. — A user associated with a customer, including the role that governs what they can manage on the customer's account. Contains essential details only — use the user endpoints for the full profile. - `userId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — Unique identifier for the user. Use it with the user endpoints to fetch full details. - `name` (`string`, required, example John Doe) — The user's full name. - `role` (`enum`, optional, one of MEMBER, MANAGER, ADMIN) — The user's level of access when managing the customer's account. ADMIN grants full administrative control, MANAGER grants day-to-day management access, and MEMBER grants limited access. - `shipping` (`object`, optional) — The shipping address for the customer. This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods. — Shipping information for order fulfillment. Only required if the order contains shippable items. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `msisdn` (`string`, optional, phone, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `instructions` (`string`, optional, example Leave at front door) — Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) - `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page. - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results. #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/customers \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [POST /customers](/api-reference/customers#tag/customers/POST/customers) Create customer Create a new customer. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `object` - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `name` (`string`, required, example John Doe) — The customer's display name — the company name for business customers or the person's full name for consumers. Shown on invoices and throughout the API. - `identity` (`string`, optional, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `referenceId` (`string`, optional, max length 255, example crm-customer-12345) — Optional reference ID to assign to the customer. Must be unique per tenant. - `preferredLocale` (`string`, optional, default en-US, example en-US) — The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE"). - `contact` (`object`, required) — Contact details for the customer. - `email` (`string`, required, email, example john.doe@example.com) — The primary contact email for the customer. - `msisdn` (`string`, optional, phone, example +15551234567) — The primary contact phone number for the customer. - `billing` (`object`, required) — Billing configuration and payment preferences for the customer. - `method` (`enum`, required, one of E_INVOICE, EMAIL_INVOICE, PAPER_INVOICE) — How invoices should be delivered to the customer. — How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address. - `email` (`string`, optional, email, example billing@company.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `address` (`object`, optional) — The billing address for the customer. Used for invoicing and tax calculation. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `currency` (`string`, required, example USD) — The currency for customer billing and payments. — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `defaultPaymentProfileId` (`string`, optional, example l47ac10b-58cc-4372-a567-0e02b2c3d479) — Default payment profile to use for automatic payments and new orders. Must be a payment profile that will be accessible to this customer. - `autoPay` (`boolean`, optional, default false, example true) — Whether to automatically charge the default payment profile for invoices and bills. Requires defaultPaymentProfileId to be set. - `userIds` (`array of string`, required) — List of user IDs to associate with this customer. Depending on the user's role they will either be a member of the customer or given access to manage it. - `contactPersonUserId` (`string`, required, example b2c3d4e5-f6a7-5b6c-9d0e-1f2a3b4c5d6e) — The user ID of the contact person for this customer. This user will be set as the primary contact for the customer and will receive important notifications. - `shipping` (`object`, optional) — The default shipping address for the customer. This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods. — Shipping information for order fulfillment. Only required if the order contains shippable items. - `name` (`string`, required, example John Doe) — Full name of the person or department receiving the delivery, printed on the shipping label. - `msisdn` (`string`, optional, phone, example +15551234567) — Phone number the carrier can use to reach the recipient about the delivery. - `address` (`object`, required) — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `instructions` (`string`, optional, example Leave at front door) — Free-text delivery instructions passed along with the shipment, such as a gate code or drop-off preference. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ### Responses #### 201 Customer created successfully. Type: [Customer](/api-reference/models.md#models/Customer) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/customers \ --request POST \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "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" } } }' ``` ## [GET /customers/{customerId}](/api-reference/customers#tag/customers/GET/customers/{customerId}) Get customer Get a customer by ID or referenceId. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `customerId` (`string`, required) — The unique identifier of the customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ### Responses #### 200 Customer details. Type: [Customer](/api-reference/models.md#models/Customer) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/customers/CUSTOMER_ID \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [PUT /customers/{customerId}](/api-reference/customers#tag/customers/PUT/customers/{customerId}) Update customer Update an existing customer. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `customerId` (`string`, required) — The unique identifier of the customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Request body (required) Type: `object` - `name` (`string`, optional, example John Doe) — 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. - `identity` (`string`, optional, example 12-3456789) — A government or company registration identifier for the entity, such as a personal identification number for consumers or an organization number for businesses. The expected format depends on the country and customer type; for example, Swedish customers use a 12-digit personal number or a 10-digit organization number. - `preferredLocale` (`string`, optional, example en-US) — The preferred locale for the customer, in IETF BCP 47 format (e.g., "en-US", "sv-SE"). - `contact` (`object`, optional) — Contact details for the customer. - `email` (`string`, optional, email, example john.doe@example.com) — The primary contact email for the customer. - `msisdn` (`string`, optional, phone, example +15551234567) — The primary contact phone number for the customer. - `billing` (`object`, optional) — Billing details for the customer. - `method` (`enum`, optional, one of E_INVOICE, EMAIL_INVOICE, PAPER_INVOICE) — How invoices are delivered to the customer: electronically (E_INVOICE), by email (EMAIL_INVOICE), or by postal mail (PAPER_INVOICE). EMAIL_INVOICE requires a billing email and PAPER_INVOICE requires a billing address. - `email` (`string`, optional, email, example billing@example.com) — The email address to send invoices to. Required if billing method is EMAIL_INVOICE. - `address` (`object`, optional) — The billing address for the customer. Required if billing method is PAPER_INVOICE. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `currency` (`string`, optional, example USD) — The currency for the customer billing. — The three-letter ISO 4217 code of the currency used for prices, billing, and payments. - `defaultPaymentProfileId` (`string`, optional, example m47ac10b-58cc-4372-a567-0e02b2c3d479) — Default payment profile to use for automatic payments and new orders. Must be a valid payment profile owned by this customer. Set to null to disable automatic payments. - `autoPay` (`boolean`, optional, example false) — Whether to automatically pay invoices for this customer if a valid payment method is available. - `userIds` (`array of string`, optional) — User IDs to associate with this customer, in addition to those already associated. Depending on the user's role they will either be a member of the customer or given access to manage it. To remove a user, use the remove-user endpoint instead. - `shippingAddress` (`object`, optional) — The shipping address for the customer. This address is used for shipping physical goods to the customer, such as SIM cards or devices. It is also used to pre-fill the address when ordering physical goods. — A postal address. Used wherever the API needs a physical location, such as billing addresses, shipping destinations, and coverage checks. - `street` (`string`, optional, example 500 S Main St) — The first line of the address, typically street and house number. - `street1` (`string`, required, deprecated) — Deprecated. Use `street` instead. The first line of the address, typically street and house number. - `street2` (`string`, optional, example Apt 1) — The second line of the address, typically apartment, suite, unit, building, floor, etc. - `city` (`string`, required, example Natick) — The city or municipality of the address. - `zip` (`string`, required, example 01701) — The zip code of the address. Depending on the country, this may be referred to as a postal code or postcode. Specifically for US addresses, the zip can include the optional four-digit extension (e.g., '27604-5121'). - `country` (`string`, required, pattern ^[A-Z]{2}$, example US) — The two-letter country abbreviation (e.g., 'US' for United States, 'SE' for Sweden). - `state` (`string`, optional, example CA) — For countries that use states or regions, the state or administrative area code (e.g., 'CA' for California in the United States). - `region` (`string`, optional, example Ontario) — A province, region, or territory name, applicable in certain countries (e.g., 'Ontario' in Canada, 'Sindh' in Pakistan). - `attention` (`string`, optional, example John Doe) — An optional line for specifying a person, department, or attention to a specific entity within an address. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) ### Responses #### 200 Customer updated successfully. Type: [Customer](/api-reference/models.md#models/Customer) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 409 The request conflicts with the current state of the resource. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/customers/CUSTOMER_ID \ --request PUT \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "contact": { "email": "newemail@example.com", "msisdn": "+15559876543" } }' ``` ## [DELETE /customers/{customerId}/users](/api-reference/customers#tag/customers/DELETE/customers/{customerId}/users) Remove user from customer Remove a user from a customer. The user keeps their account, so they can still be added to another customer later, but loses the roles and permissions this customer granted them. A customer's contact person cannot be removed — assign another contact person first. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `customerId` (`string`, required) — The unique identifier of the customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ### Query parameters - `userId` (`string`, required) — The unique identifier of the user to remove from the customer. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_hr-employee-98765`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ### Header parameters - `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code. ### Responses #### 200 User removed from customer successfully. Type: [Customer](/api-reference/models.md#models/Customer) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 412 A precondition for this request was not met. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl 'https://apiv2.example.com/api/v2/customers/CUSTOMER_ID/users?userId=USER_ID' \ --request DELETE \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ``` ## [GET /customers/{customerId}/product-catalog](/api-reference/customers#tag/customers/GET/customers/{customerId}/product-catalog) Get customer product catalog Get the customer's product catalog, this is a combination of the default product catalog configured in the system and other product catalogs assigned to the customer. Authentication: X-Api-Key, or Bearer JWT + X-Api-Key ### Path parameters - `customerId` (`string`, required) — The unique identifier of the customer to fetch the product catalog for. May be the entity's internal UUID or an external reference identifier. Reference identifiers MUST be prefixed with `rid_` (e.g., `rid_crm-customer-12345`) so the API can distinguish them from internal UUIDs. The prefix is stripped before lookup. ### Responses #### 200 Customer product catalog. Type: `object` - `productOfferingGroups` (`array of ProductOfferingGroup`, optional) — The product groups in this catalog. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of 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) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `productOfferings` (`array of ProductOffering`, optional) — The product offerings available in this catalog. - `productOfferingId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — Unique identifier for the product offering. - `status` (`enum`, required, one of AVAILABLE, ARCHIVED, example AVAILABLE) — The status of the product offering. Archived offerings are not allowed to be created/ordered by customers, but can still be used for existing subscriptions. - `name` (`string`, required, example Seamless 10GB) — Name of the product offering. - `description` (`string`, optional, example Basic mobile plan with 5GB data and unlimited calls) — Description of the product offering. - `richContent` (`string`, optional, example

Features

  • 5GB monthly data
  • Unlimited calls & texts
  • No setup fees
) — Rich HTML content with detailed information about the product offering. - `uspList` (`array of string`, optional, example ["5GB of data every month","Unlimited calls and texts","No setup fee"]) — Short plain-text selling points, in the order the brand put them. A storefront shows them as a checklist. - `product` (`object`, required) — Embedded representation of a product. - `productId` (`string`, required, example d4e5f6a7-b8c9-0123-4567-890123456789) — The unique identifier for the product. - `internalName` (`string`, required, example us-mobile-unlimited-5gb) — The name used to identify the product internally in the catalog. Not intended for customer display — use the product offering name instead. - `type` (`enum`, required, one of SUBSCRIPTION, SUBSCRIPTION_ADDON, LICENSE, EXTERNAL_PRODUCT, SIM_CARD, example SUBSCRIPTION) — The type of product offering determines how it can be used and what kind of resource it creates. **SUBSCRIPTION** Creates a standalone subscription resource (e.g., mobile plan, broadband, travel eSIM). - Includes categories like `SUBSCRIPTION_CELL`, `TRAVEL_ESIM` - Can be created via order or directly depending on configuration - Has its own lifecycle (activation, suspension, termination) **SUBSCRIPTION_ADDON** Adds features or resources to an existing subscription. - Includes categories like `TRAVEL_ESIM_PACKAGE` - Must be attached to a parent subscription **LICENSE** Creates a license for business/PBX features. - Typically used for enterprise telephony features **EXTERNAL_PRODUCT** Represents purchasable items outside the core telecom platform. - Can only be ordered via orders, not created directly **SIM_CARD** Replaces the SIM card for an existing subscription through a subscription change order. - `category` (`enum`, required, one of 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) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `networkProviderId` (`string`, optional, example tmobile-us) — The unique identifier for the network provider. - `features` (`object`, optional) — The features included with the product, if any. Typically used for telecom products. - `dataMb` (`number`, optional, example 2048) — Megabytes of data included with the product. Present for cellular, data, and travel eSIM products. - `includedCallSeconds` (`integer`, optional, example 1000) — Outbound call seconds included with the product. Present for cellular subscription categories. - `includedSms` (`integer`, optional, example 500) — Number of SMS messages included with the product. Present for cellular subscription categories. - `validityDays` (`integer`, optional, example 30) — Number of days the product is valid for. Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`). - `countries` (`array of string`, optional, example ["USA","CAN","MEX"]) — ISO 3166-1 alpha-3 country codes where the product provides coverage. Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`). Use the `countries` query parameter on list endpoints to filter by coverage. - `regions` (`array of string`, optional, example ["NORTH_AMERICA"]) — Named regions covered by the product. Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`). Use the `regions` query parameter on list endpoints to filter by coverage. - `activationType` (`enum`, optional, one of INSTANT, FIRST_USE, example INSTANT) — How the travel eSIM package activates. Present for travel eSIM packages (`TRAVEL_ESIM_PACKAGE`). - `simCardType` (`enum`, optional, one of PSIM, ESIM, example PSIM) — The SIM format for a SIM card product. - `price` (`object`, required) — The cost of a product offering, as configured in the catalog. A price is either one-time or recurring, and the priceType field tells you which. Amounts are integers in the minor units of the currency. For example, 2999 is $29.99 when the currency is USD. - `netPriceMinor` (`integer`, optional, int64, example 2999) — The configured price of the offering, in minor currency units. - `currency` (`string`, required, example USD) — The ISO 4217 currency code the price is expressed in (e.g., "USD"). - `priceType` (`enum`, required, one of ONE_TIME, RECURRING) — How the price is charged. - ONE_TIME: Charged once (e.g., a setup fee or hardware purchase). - RECURRING: Charged every billing cycle (e.g., a monthly subscription fee). - `bindingContract` (`object`, optional) — A commitment to keep the subscription for a fixed term, usually in exchange for a discount that runs for the length of the commitment. - `duration` (`object`, required) — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `standardDiscount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `customUpfrontPayment` (`object`, optional) — Billing cycles the customer pays for in advance when ordering, usually at a discount. Billing returns to the normal cycle once the prepaid cycles run out. - `billingCycles` (`integer`, required, example 3) — How many billing cycles are paid for upfront. This counts cycles, not months: three cycles of a price that bills quarterly covers nine months. - `discount` (`object`, optional) — A recurring amount that comes off the price when you price the order. The amount applies to one billing period, the same as the price, and it is not a total. For example, a discount of 500 for 3 periods takes 500 off each of the first three periods, and 1500 in all. - `amountMinor` (`integer`, required, int64, example 500) — The amount that comes off each billing period, in minor currency units. - `duration` (`object`, optional) — How long the discount lasts. An `UPFRONT_PAYMENT` discount always gives a duration, and it covers the billing cycles that the customer pays for in advance. The other two sources omit the duration when the discount never stops. The discount then comes off every charge for as long as the price is in effect. For a one-time price that is the single charge. — A length of time, expressed as a count of some unit. - `unit` (`enum`, required, one of MONTHS) — The unit of time being counted. Currently only months are supported. - `value` (`integer`, required, example 3) — How many of the unit the duration lasts. - `source` (`enum`, optional, one of STANDARD, BINDING_CONTRACT, UPFRONT_PAYMENT, example STANDARD) — What the customer must do to get the discount: - `STANDARD` is given to every customer who orders the offering. - `BINDING_CONTRACT` needs the customer to commit for the contract's length. - `UPFRONT_PAYMENT` needs the customer to pay for several billing periods at once. - `invoicingDescription` (`string`, optional, example Campaign discount) — What the brand calls this discount on an invoice. Omitted when the brand gave the discount no name of its own. - `billingCycle` (`object`, optional) — How often a recurring price is charged. - `period` (`enum`, required, one of MONTHLY) — The unit of time between charges. Currently only monthly billing is supported. - `interval` (`integer`, required, example 1) — The quantity of periods between charges. For example, a MONTHLY period with an interval of 1 bills each month, and an interval of 3 bills each three months. - `currencyOptionsMinor` (`object with string keys`, optional) — 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. - `*` (`integer`, optional, int64) - `group` (`object`, optional) — A product group organizes related product offerings. - `productOfferingGroupId` (`string`, required, example mobile-plans) — Unique identifier for the product group. - `name` (`string`, required, example Mobile Plans) — Name of the product group in the requested locale. - `description` (`string`, optional, example Bundled cell subscriptions with unlimited calls and SMS with ILD enabled.) — Description of the product group in the requested locale. - `category` (`enum`, required, one of 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) — A product category is a sub-type for grouping offerings of the same type. Typically, product offerings of the same type with the same category allow for switching between them. For upgrading and downgrading subscriptions and licenses, we recommend using their corresponding endpoints though. Categories are grouped by their product type: **SUBSCRIPTION categories:** - `PRODUCT_CATEGORY_SUBSCRIPTION_CELL` - Mobile cellular subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_DATA_SIM` - Data-only SIM subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_BROADBAND` - Broadband internet subscription - `PRODUCT_CATEGORY_SUBSCRIPTION_M2M` - Machine-to-machine IoT subscription - `PRODUCT_CATEGORY_TRAVEL_ESIM` - Travel eSIM subscription for international roaming **SUBSCRIPTION_ADDON categories:** - `PRODUCT_CATEGORY_EXTRA_DATA` - Additional data package addon - `PRODUCT_CATEGORY_TRAVEL_ESIM_PACKAGE` - Travel eSIM data package with country/region coverage - `PRODUCT_CATEGORY_ABROAD` - International roaming addon **EXTERNAL_PRODUCT categories:** - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT` - External purchasable product - `PRODUCT_CATEGORY_EXTERNAL_PRODUCT_ADDON` - Addon for external product **SIM_CARD categories:** - `PRODUCT_CATEGORY_SIM_CARD` - Physical SIM or eSIM replacement for an existing subscription - `internalDescription` (`string`, optional, example Core mobile offerings targeting consumer and business segments) — Internal description of the product group for operational use only. - `customerType` (`enum`, required, one of CONSUMER, BUSINESS) — Whether the customer is a private individual (CONSUMER) or a company (BUSINESS). Determines the expected identity format and which billing rules apply. - `addonCategories` (`array of ProductCategory`, optional) — List of product categories this addon is applicable for. Only populated when type is `SUBSCRIPTION_ADDON`. For example, a `TRAVEL_ESIM_PACKAGE` addon might be applicable to `TRAVEL_ESIM` subscriptions. - `internalDescription` (`string`, optional, example seamless_cell_10gb_us) — Internal description of the product offering for operational use only. - `imageUrl` (`string`, optional, uri, example https://cdn.example.com/images/mobile-basic.png) — URL to the image representing the product offering. - `metadata` (`object with string keys`, optional) — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values. - `*` (`string`, optional) #### 400 The request was malformed or invalid. Type: [Error](/api-reference/models.md#models/Error) #### 401 Authentication is required to access this resource. Type: [Error](/api-reference/models.md#models/Error) #### 403 Access to this resource is forbidden. Type: [Error](/api-reference/models.md#models/Error) #### 404 The requested resource was not found. Type: [Error](/api-reference/models.md#models/Error) #### 429 Too many requests have been sent in a given amount of time. Type: [Error](/api-reference/models.md#models/Error) #### 500 An unexpected error occurred on the server. Type: [Error](/api-reference/models.md#models/Error) ### Example request ```bash curl https://apiv2.example.com/api/v2/customers/CUSTOMER_ID/product-catalog \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-Api-Key: YOUR_API_KEY' ```