Reseller API Documentation

The reseller API is exposed under /api/v1 and uses header-based token authentication. The main commercial flow is login → list bundles → complete sale or top up (v2) → monitor consumption and order history. The API is fully described by an OpenAPI 3.0 (Swagger) specification — every endpoint, request body, and response shown here matches the published Swagger schema.

Scope: this document includes only the main reseller-facing endpoints shown in the integration flow. Internal/admin endpoints (reseller setup, roles, branches, pricing customization) are intentionally not covered here.

Note: if your deployment exposes a different host or prefix, keep the same endpoint paths and replace only the base URL.

Login request

{
  "username": "your_reseller_username",
  "password": "YourStrongPassword1!"
}

The login response returns an access_token, refresh_token, token type, expiry values, role information, reseller_id, and feature flags such as show_global_esim_bundles.

Sample request headers

Content-Type: application/json
Access-Token: <access_token>

1. Authenticate with POST /Agent/login and store both access_token and refresh_token.
2. List available bundles with GET /Bundles using filters such as country_code, bundle_category, region_code, and profile_type.
3. Assign a bundle in a single call using POST /Bundle with the selected bundle_code and your order_reference. Checks the reseller wallet balance, verifies the bundle is available, and assigns it to the end user.
4. Use GET /Orders or GET /Profile/Consumption to track status and usage.

Step 1 — Get bundles

GET /Bundles?country_code=FRA&bundle_category=country&page_size=25
Access-Token: <access_token>

Relevant bundle response fields include bundle_code, bundle_name, bundle_marketing_name, country_name, region_name, validity, bundle_price_final, subscriber_price, reseller_retail_price, support_topup, supports_calls_sms, and profile_type.

Step 2 — Assign the bundle

Call POST /Bundle with the selected bundle_code and the end user's details. Optional query parameters: reseller_id, branch_id (super admin only), and currency_code to preview the wallet balance in another currency.

{
  "bundle_code": "USA3GB_3102938429",
  "email": "client@hotmail.com",
  "name": "John Wick",
  "order_reference": "ORDER-10001",
  "whatsapp_number": "+33600000000"
}

{
  "title": "Success",
  "message": "Bundle Assigned Successfully",
  "developer_message": "Operation Succcessful",
  "response_code": "1",
  "order_id": "507f191e810c19729de860ea",
  "iccid": "iccid",
  "reseller_id": "507f191e810c19729de860ea",
  "remaining_wallet_balance": 30,
  "remaining_wallet_balance_in_additional_currency": 30,
  "additional_currency_code": "SAR"
}

Global eSIM allows multiple coverage areas to coexist on a single eSIM profile. End-users can add new regions or countries on the same QR/eSIM profile without installing a new profile. Additional bundles are applied as top-ups on the same ICCID, and active bundles can coexist simultaneously.

Reseller configuration

• show_global_esim_bundles: false (default): fully backward compatible. Bundle, country, and region endpoints return Standard eSIM products only. Queries with profile_type=GLOBAL_ESIM return HTTP 400.
• show_global_esim_bundles: true: enables querying and purchasing Global eSIM bundles and allows filtering with profile_type=GLOBAL_ESIM.

Adoption options

• No changes: existing API calls continue to work and return Standard eSIM products by default.
• Gradual adoption: read profile_type and global_esim in responses, migrate consumption to /Profile/Consumption, then enable Global eSIM.
• Full integration: enable Global eSIM, update bundle listing filters, switch to /Profile/Consumption, optionally filter order history with global_esim=true.

Recommended migration examples

GET /Bundles?profile_type=GLOBAL_ESIM
GET /Bundles?profile_type=STANDARD
GET /Profile/Consumption?iccid={iccid}
GET /Orders?global_esim=true

Deprecation notice

Common enums

Error catalog

• Authentication failures or permission issues are commonly returned as 401 or 403 depending on the flow.
• Several endpoints also define 204 No Content and 400 Bad Request responses.
• For production integration, always send and store your own order_reference so you can reconcile reservation, completion, top-up, cancelation, and reporting flows.
• The OpenAPI specification also exposes internal/admin endpoints (reseller setup, roles, branches, pricing customization) that are intentionally not the focus of this reseller-facing document.