The HOI eServices API provides a unified interface for digital services including gift cards, eSIM provisioning, mobile top-ups, vouchers, bill payments, and travel insurance. Each service is organized as a separate folder within this collection.
\nAll endpoint paths are relative to the base URL for your target environment, e.g. https://eservicespre.hoicom.net/api/v0/gifts/locations.
The API is structured around RESTful principles, utilizing standard HTTP methods and status codes. It communicates using JSON-formatted requests and responses, ensuring compatibility with a wide range of clients and platforms.
\nContent Type: All requests and responses use application/json
Base URL: Environment-specific — see the Base URLs section above. Paths follow the form .../api/{version}/{service}
Versioning: API versions are specified in the URL path (e.g., v0, v1)
All API endpoints require proper authentication to ensure secure access. Authentication is handled via Basic Authentication, where clients provide their credentials with each request.
\nCombine your username and password with a colon: username:password
Encode the combined string using Base64 encoding
\nInclude the encoded string in the Authorization header:
Authorization: Basic xxxxxxxxx\n\nAuthorization header (HTTP Basic Authentication).eservicespre.hoicom.net) and Production (eservices.hoicom.net) are fully segregated environments, with separate credentials and separate data.All responses follow a standard JSON structure:
\n{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": { }\n}\n\nReturns the geographic regions eSIM plans are grouped into. Use a region code with Get Plans by Region to list its plans.
Requires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.
\nOn success code is 1000 and data is a list of regions, each with name, code, and countries.
Language for text fields: \"en\" or \"ar\".
\n","type":"text/plain"},"key":"lang","value":"en"},{"description":{"content":"Field to sort by.
\n","type":"text/plain"},"key":"sortBy","value":"name"},{"description":{"content":"Sort descending.
\n","type":"text/plain"},"key":"sortDescending","value":"false"}],"variable":[]}},"response":[{"id":"ff3e153b-cb7f-4232-9ea1-72c4326f874a","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/esim/regions?lang=en&sortBy=name&sortDescending=false","host":["https://eservicespre.hoicom.net"],"path":["api","v0","esim","regions"],"query":[{"key":"lang","value":"en","description":"Language for text fields: \"en\" or \"ar\"."},{"key":"sortBy","value":"name","description":"Field to sort by."},{"key":"sortDescending","value":"false","description":"Sort descending."}]},"description":"Returns the geographic **regions** eSIM plans are grouped into. Use a region `code` with **Get Plans by Region** to list its plans.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `lang` | `string` | No | `en` | Language for text fields: `en` or `ar`. |\n| `sortBy` | `string` | No | `name` | Field to sort by. |\n| `sortDescending` | `bool` | No | `false` | Sort descending. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a list of regions, each with `name`, `code`, and `countries`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": [\n {\n \"name\": \"Europe\",\n \"code\": \"EU\",\n \"countries\": [\n \"FRA\",\n \"DEU\",\n \"ESP\"\n ]\n },\n {\n \"name\": \"Asia Pacific\",\n \"code\": \"AP\",\n \"countries\": [\n \"JPN\",\n \"SGP\",\n \"AUS\"\n ]\n }\n ]\n}"}],"_postman_id":"d6082f91-3a8f-4120-ba62-de5128bb4a28"},{"name":"Get Countries","id":"5fd9197e-1d04-4805-aa9b-c7250896b37e","request":{"method":"GET","header":[],"url":"https://eservicespre.hoicom.net/api/v0/esim/countries?name=&isoCode=&continentName=&lang=en&sortBy=name&sortDescending=false&page=1&pageSize=300","description":"Returns the countries eSIM plans are available for, with currency, calling codes, and dialing rules.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.
\nOn success code is 1000 and data is a paginated list of countries.
Filter by country name.
\n","type":"text/plain"},"key":"name","value":""},{"description":{"content":"Filter by ISO code.
\n","type":"text/plain"},"key":"isoCode","value":""},{"description":{"content":"Filter by continent.
\n","type":"text/plain"},"key":"continentName","value":""},{"description":{"content":"Language: \"en\" or \"ar\".
\n","type":"text/plain"},"key":"lang","value":"en"},{"key":"sortBy","value":"name"},{"key":"sortDescending","value":"false"},{"key":"page","value":"1"},{"key":"pageSize","value":"300"}],"variable":[]}},"response":[{"id":"7cc47c73-06b9-47c2-9783-09d55c2fb94c","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/esim/countries?name=&isoCode=&continentName=&lang=en&sortBy=name&sortDescending=false&page=1&pageSize=300","host":["https://eservicespre.hoicom.net"],"path":["api","v0","esim","countries"],"query":[{"key":"name","value":"","description":"Filter by country name."},{"key":"isoCode","value":"","description":"Filter by ISO code."},{"key":"continentName","value":"","description":"Filter by continent."},{"key":"lang","value":"en","description":"Language: \"en\" or \"ar\"."},{"key":"sortBy","value":"name"},{"key":"sortDescending","value":"false"},{"key":"page","value":"1"},{"key":"pageSize","value":"300"}]},"description":"Returns the **countries** eSIM plans are available for, with currency, calling codes, and dialing rules.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `name` | `string` | No | — | Filter by country name. |\n| `isoCode` | `string` | No | — | Filter by ISO code. |\n| `continentName` | `string` | No | — | Filter by continent. |\n| `lang` | `string` | No | `en` | Language: `en` or `ar`. |\n| `sortBy` | `string` | No | `name` | Field to sort by. |\n| `sortDescending` | `bool` | No | `false` | Sort descending. |\n| `page` | `int` | No | `1` | Page number. |\n| `pageSize` | `int` | No | `300` | Items per page. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a paginated list of countries."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"name\": \"Saudi Arabia\",\n \"isoCode\": \"SAU\",\n \"continentName\": \"Asia\",\n \"currency\": {\n \"code\": \"SAR\",\n \"name\": \"Saudi Riyal\",\n \"symbol\": \"ر.س\"\n },\n \"flagUrl\": \"https://cdn.example.com/flags/sa.svg\",\n \"callingCodes\": [\n \"+966\"\n ],\n \"regions\": [\n {\n \"name\": \"Middle East\",\n \"code\": \"ME\"\n }\n ],\n \"dialingRules\": [\n {\n \"prefix\": \"5\",\n \"minimumLength\": 9,\n \"maximumLength\": 9\n }\n ]\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"}],"_postman_id":"5fd9197e-1d04-4805-aa9b-c7250896b37e"},{"name":"Get Plans","id":"804e2310-d31b-4ef4-8e48-eb02dbec261f","request":{"method":"GET","header":[],"url":"https://eservicespre.hoicom.net/api/v0/esim/plans?coverageType=REGIONAL&supportsTopup=true&sortBy=minprice&sortDescending=false&page=1&pageSize=50&lang=en","description":"Returns available eSIM plans with rich filtering. Each plan carries its details, pricing (see Pricing type in the folder overview), and validities.
Requires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.
\nOn success code is 1000 and data is a paginated list of plans. details.coverageType uses the Coverage type enum and pricing.type the Pricing type enum (see folder overview).
LOCAL, REGIONAL, or GLOBAL.
\n","type":"text/plain"},"key":"coverageType","value":"REGIONAL"},{"key":"supportsTopup","value":"true"},{"key":"sortBy","value":"minprice"},{"key":"sortDescending","value":"false"},{"key":"page","value":"1"},{"key":"pageSize","value":"50"},{"description":{"content":"Language for text fields: en or ar.
\n","type":"text/plain"},"key":"lang","value":"en"}],"variable":[]}},"response":[{"id":"268a6c83-cf3a-4360-9469-442e5149f682","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/esim/plans?coverageType=REGIONAL&supportsTopup=true&sortBy=minprice&sortDescending=false&page=1&pageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","esim","plans"],"query":[{"key":"coverageType","value":"REGIONAL","description":"LOCAL, REGIONAL, or GLOBAL."},{"key":"supportsTopup","value":"true"},{"key":"sortBy","value":"minprice"},{"key":"sortDescending","value":"false"},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}]},"description":"Returns available **eSIM plans** with rich filtering. Each plan carries its `details`, `pricing` (see **Pricing type** in the folder overview), and `validities`.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `id` | `string` | No | — | Filter by plan id. |\n| `unlimited` | `bool` | No | — | Only unlimited-data plans. |\n| `supportsTopup` | `bool` | No | — | Only plans that support top-ups. |\n| `coverageType` | `string` | No | — | `LOCAL`, `REGIONAL`, or `GLOBAL`. |\n| `countryIsoCodes` | `string[]` | No | — | Filter by country ISO codes. |\n| `operators` | `string[]` | No | — | Filter by network operators. |\n| `sortBy` | `string` | No | `minprice` | Field to sort by. |\n| `sortDescending` | `bool` | No | `false` | Sort descending. |\n| `page` | `int` | No | `1` | Page number. |\n| `pageSize` | `int` | No | `50` | Items per page (max 50). |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a paginated list of plans. `details.coverageType` uses the **Coverage type** enum and `pricing.type` the **Pricing type** enum (see folder overview)."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"id\": \"plan_eu_5gb_30d\",\n \"details\": {\n \"name\": \"Europe 5GB - 30 Days\",\n \"description\": \"5GB of data across Europe, valid for 30 days.\",\n \"coverageType\": \"REGIONAL\",\n \"termsAndConditions\": \"Standard eSIM terms apply.\",\n \"usageInstructions\": \"Scan the QR code and enable data roaming.\",\n \"unlimited\": false,\n \"supportsTopup\": true,\n \"autoRenew\": false,\n \"maxDownloadSpeed\": null,\n \"maxUploadSpeed\": null,\n \"validCountries\": [\n {\n \"name\": \"France\",\n \"isoCode3\": \"FRA\"\n },\n {\n \"name\": \"Germany\",\n \"isoCode3\": \"DEU\"\n }\n ],\n \"supportedOperators\": [\n \"Orange\",\n \"Vodafone\"\n ]\n },\n \"pricing\": {\n \"type\": \"FIXED\",\n \"currency\": \"SAR\",\n \"minAmount\": 75,\n \"maxAmount\": 75,\n \"fees\": 0,\n \"tax\": {\n \"taxRate\": 15,\n \"taxType\": \"VAT\",\n \"taxAmount\": 11.25\n }\n },\n \"validities\": [\n {\n \"type\": \"DATA\",\n \"unit\": \"GB\",\n \"quantity\": 5\n },\n {\n \"type\": \"DURATION\",\n \"unit\": \"DAYS\",\n \"quantity\": 30\n }\n ]\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"}],"_postman_id":"804e2310-d31b-4ef4-8e48-eb02dbec261f"},{"name":"Get Plans by Country","id":"909568f4-3c0a-40e2-89a2-c36708a270ce","request":{"method":"GET","header":[],"url":"https://eservicespre.hoicom.net/api/v0/esim/plans/country/:countryIsoCode?page=1&pageSize=50&lang=en","description":"Returns eSIM plans available for a specific country.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.
\nOn success code is 1000 and data is a paginated list of plans.
Language for text fields: en or ar.
\n","type":"text/plain"},"key":"lang","value":"en"}],"variable":[{"type":"any","value":"","key":"countryIsoCode"}]}},"response":[{"id":"539802c7-05bf-49a1-b422-431f20e4da5c","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/esim/plans/country/:countryIsoCode?page=1&pageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","esim","plans","country",":countryIsoCode"],"query":[{"key":"page","value":"1"},{"key":"pageSize","value":"50"}],"variable":[{"key":"countryIsoCode","value":""}]},"description":"Returns eSIM plans available for a specific country.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.\n\n---\n\n## Path Parameters\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `countryIsoCode` | `string` | Yes | Country ISO code (2 or 3 letters). |\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `page` | `int` | No | `1` | Page number. |\n| `pageSize` | `int` | No | `50` | Items per page. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a paginated list of plans."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"id\": \"plan_eu_5gb_30d\",\n \"details\": {\n \"name\": \"Europe 5GB - 30 Days\",\n \"description\": \"5GB of data across Europe, valid for 30 days.\",\n \"coverageType\": \"REGIONAL\",\n \"termsAndConditions\": \"Standard eSIM terms apply.\",\n \"usageInstructions\": \"Scan the QR code and enable data roaming.\",\n \"unlimited\": false,\n \"supportsTopup\": true,\n \"autoRenew\": false,\n \"maxDownloadSpeed\": null,\n \"maxUploadSpeed\": null,\n \"validCountries\": [\n {\n \"name\": \"France\",\n \"isoCode3\": \"FRA\"\n },\n {\n \"name\": \"Germany\",\n \"isoCode3\": \"DEU\"\n }\n ],\n \"supportedOperators\": [\n \"Orange\",\n \"Vodafone\"\n ]\n },\n \"pricing\": {\n \"type\": \"FIXED\",\n \"currency\": \"SAR\",\n \"minAmount\": 75,\n \"maxAmount\": 75,\n \"fees\": 0,\n \"tax\": {\n \"taxRate\": 15,\n \"taxType\": \"VAT\",\n \"taxAmount\": 11.25\n }\n },\n \"validities\": [\n {\n \"type\": \"DATA\",\n \"unit\": \"GB\",\n \"quantity\": 5\n },\n {\n \"type\": \"DURATION\",\n \"unit\": \"DAYS\",\n \"quantity\": 30\n }\n ]\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"}],"_postman_id":"909568f4-3c0a-40e2-89a2-c36708a270ce"},{"name":"Get Plans by Region","id":"2cfc28ec-b663-4d73-a753-3f1589af2e2e","request":{"method":"GET","header":[],"url":"https://eservicespre.hoicom.net/api/v0/esim/plans/region/:regionCode?page=1&pageSize=50&lang=en","description":"Returns eSIM plans available for a specific region (region code from Get Regions).
Requires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.
\nOn success code is 1000 and data is a paginated list of plans.
Language for text fields: en or ar.
\n","type":"text/plain"},"key":"lang","value":"en"}],"variable":[{"type":"any","value":"","key":"regionCode"}]}},"response":[{"id":"48d29976-52a2-4135-9b0d-48598a7bc5ae","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/esim/plans/region/:regionCode?page=1&pageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","esim","plans","region",":regionCode"],"query":[{"key":"page","value":"1"},{"key":"pageSize","value":"50"}],"variable":[{"key":"regionCode","value":""}]},"description":"Returns eSIM plans available for a specific region (region `code` from **Get Regions**).\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.\n\n---\n\n## Path Parameters\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `regionCode` | `string` | Yes | Region code, e.g. `EU`. |\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `page` | `int` | No | `1` | Page number. |\n| `pageSize` | `int` | No | `50` | Items per page. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a paginated list of plans."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"id\": \"plan_eu_5gb_30d\",\n \"details\": {\n \"name\": \"Europe 5GB - 30 Days\",\n \"description\": \"5GB of data across Europe, valid for 30 days.\",\n \"coverageType\": \"REGIONAL\",\n \"termsAndConditions\": \"Standard eSIM terms apply.\",\n \"usageInstructions\": \"Scan the QR code and enable data roaming.\",\n \"unlimited\": false,\n \"supportsTopup\": true,\n \"autoRenew\": false,\n \"maxDownloadSpeed\": null,\n \"maxUploadSpeed\": null,\n \"validCountries\": [\n {\n \"name\": \"France\",\n \"isoCode3\": \"FRA\"\n },\n {\n \"name\": \"Germany\",\n \"isoCode3\": \"DEU\"\n }\n ],\n \"supportedOperators\": [\n \"Orange\",\n \"Vodafone\"\n ]\n },\n \"pricing\": {\n \"type\": \"FIXED\",\n \"currency\": \"SAR\",\n \"minAmount\": 75,\n \"maxAmount\": 75,\n \"fees\": 0,\n \"tax\": {\n \"taxRate\": 15,\n \"taxType\": \"VAT\",\n \"taxAmount\": 11.25\n }\n },\n \"validities\": [\n {\n \"type\": \"DATA\",\n \"unit\": \"GB\",\n \"quantity\": 5\n },\n {\n \"type\": \"DURATION\",\n \"unit\": \"DAYS\",\n \"quantity\": 30\n }\n ]\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"}],"_postman_id":"2cfc28ec-b663-4d73-a753-3f1589af2e2e"},{"name":"Get Plan Networks","id":"95efda1a-ebfc-4550-aa5a-3af94ef57f6f","request":{"method":"GET","header":[],"url":"https://eservicespre.hoicom.net/api/v0/esim/plans/:id/networks","description":"Returns the network operators reachable on a plan, grouped by country.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.
\nOn success code is 1000 and data is a list of { countryIsoCode, operators[] }.
Returns the top-up add-ons available for a plan. To buy one, call Create Transaction with mainTransactionId set to the original transaction.
Requires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.
\nOn success code is 1000 and data is a paginated list of top-up plans.
Language for text fields: en or ar.
\n","type":"text/plain"},"key":"lang","value":"en"}],"variable":[{"type":"any","value":"","key":"id"}]}},"response":[{"id":"86d11a22-62f8-4b93-b138-8970be35e63f","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/esim/plans/:id/topups?page=1&pageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","esim","plans",":id","topups"],"query":[{"key":"page","value":"1"},{"key":"pageSize","value":"50"}],"variable":[{"key":"id","value":""}]},"description":"Returns the top-up add-ons available for a plan. To buy one, call **Create Transaction** with `mainTransactionId` set to the original transaction.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.\n\n---\n\n## Path Parameters\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `id` | `string` | Yes | Plan identifier. |\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `page` | `int` | No | `1` | Page number. |\n| `pageSize` | `int` | No | `50` | Items per page. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a paginated list of top-up plans."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"id\": \"topup_eu_2gb\",\n \"details\": {\n \"name\": \"Europe 2GB Add-on\",\n \"description\": \"Add 2GB to an active Europe plan.\",\n \"coverageType\": \"REGIONAL\",\n \"termsAndConditions\": \"Standard eSIM terms apply.\",\n \"usageInstructions\": \"Applied automatically to your active eSIM.\",\n \"unlimited\": false,\n \"autoRenew\": false,\n \"maxDownloadSpeed\": null,\n \"maxUploadSpeed\": null,\n \"validCountries\": [\n {\n \"name\": \"France\",\n \"isoCode3\": \"FRA\"\n }\n ],\n \"supportedOperators\": [\n \"Orange\"\n ]\n },\n \"pricing\": {\n \"type\": \"FIXED\",\n \"currency\": \"SAR\",\n \"minAmount\": 30,\n \"maxAmount\": 30,\n \"fees\": 0,\n \"tax\": {\n \"taxRate\": 15,\n \"taxType\": \"VAT\",\n \"taxAmount\": 4.5\n }\n },\n \"validities\": [\n {\n \"type\": \"DATA\",\n \"unit\": \"GB\",\n \"quantity\": 2\n }\n ]\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"}],"_postman_id":"49c1eb38-bda9-4530-a944-ca005603a386"},{"name":"Create Transaction","id":"edd3d7aa-e43f-4195-9d80-ef5df533571b","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"externalReference\": \"client-ref-2001\",\n \"planId\": \"plan_eu_5gb_30d\",\n \"mainTransactionId\": null,\n \"amount\": 75,\n \"currency\": \"SAR\"\n}","options":{"raw":{"language":"json"}}},"url":"https://eservicespre.hoicom.net/api/v0/esim/transactions/async","description":"Buys an eSIM plan asynchronously. Returns immediately with a transactionId; poll Get Transaction by ID until status is Completed to retrieve the eSIM details (ICCID, activation code, QR).
To buy a top-up for an existing eSIM, set mainTransactionId to the original transaction id. Orders are idempotent on externalReference.
Requires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.
\nOn acceptance code is 1000 and data contains the transactionId.
Returns a single eSIM transaction, including its status and — once Completed — the eSIM product (ICCID, activation code, SM-DP+ address, matching id, and a base64 qrCode).
Requires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.
\nOn success code is 1000. status uses the Transaction status enum and product.planType / product.coverageType the Product type / Coverage type enums (see folder overview).
Returns a paginated, filterable list of your eSIM transactions.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.
\nOn success code is 1000 and data is a paginated list of transactions. Valid status values: Submitted, Pending, Completed, Failed, Cancelled.
Enum name, e.g. Completed.
\n","type":"text/plain"},"key":"status","value":"Completed"},{"key":"fromDate","value":""},{"key":"toDate","value":""},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}],"variable":[]}},"response":[{"id":"bde2f812-5cad-4a7e-8d95-00c341667d14","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/esim/Transactions?transactionId=&externalReference=&status=Completed&fromDate=&toDate=&page=1&pageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","esim","Transactions"],"query":[{"key":"transactionId","value":""},{"key":"externalReference","value":""},{"key":"status","value":"Completed","description":"Enum name, e.g. Completed."},{"key":"fromDate","value":""},{"key":"toDate","value":""},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}]},"description":"Returns a paginated, filterable list of your eSIM transactions.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `transactionId` | `string` | No | — | Filter by transaction id. |\n| `externalReference` | `string` | No | — | Filter by your external reference. |\n| `status` | `string` | No | — | Filter by status (enum name, e.g. `Completed`). |\n| `fromDate` | `datetime` | No | — | Start of creation-date range. |\n| `toDate` | `datetime` | No | — | End of creation-date range. |\n| `page` | `int` | No | `1` | Page number. |\n| `pageSize` | `int` | No | `50` | Items per page. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a paginated list of transactions. Valid `status` values: `Submitted`, `Pending`, `Completed`, `Failed`, `Cancelled`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"transactionId\": \"esim_txn_5a1b2c3d\",\n \"externalReference\": \"client-ref-2001\",\n \"status\": \"Completed\",\n \"timestamp\": {\n \"requestedAt\": \"2026-07-01T09:30:00Z\",\n \"completedAt\": \"2026-07-01T09:31:12Z\"\n },\n \"product\": {\n \"id\": \"plan_eu_5gb_30d\",\n \"name\": \"Europe 5GB - 30 Days\",\n \"planType\": \"Plan\",\n \"coverageType\": \"REGIONAL\",\n \"iccid\": \"8944000000000000000\",\n \"activationCode\": \"LPA:1$smdp.example.com$ABC123\",\n \"smdpAddress\": \"smdp.example.com\",\n \"matchingId\": \"ABC123\",\n \"otp\": \"\",\n \"qrCode\": \"iVBORw0KGgoAAAANSUhEUgAA...(base64-encoded PNG)\"\n },\n \"amounts\": {\n \"requestedAmount\": {\n \"amount\": 75,\n \"currency\": \"SAR\"\n },\n \"deliveredAmount\": {\n \"amount\": 75,\n \"currency\": \"SAR\"\n },\n \"fees\": {\n \"totalFee\": 0,\n \"currency\": \"SAR\"\n }\n },\n \"pinDetails\": {\n \"code\": \"\",\n \"serial\": \"\",\n \"validity\": \"\",\n \"additionalInfo\": []\n },\n \"receipt\": \"https://cdn.example.com/receipts/esim_txn_5a1b2c3d.pdf\"\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"}],"_postman_id":"9b03fe91-e462-43e3-9e2e-733f1b943983"},{"name":"Get Plan Usage by Transaction","id":"11f4d60a-0381-439f-95d0-0951693a6d4f","request":{"method":"GET","header":[],"url":"https://eservicespre.hoicom.net/api/v0/esim/transactions/:id/plans/usage","description":"Returns live data-usage details for the plan attached to a transaction.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.
\nOn success code is 1000. planStatus uses the Plan status enum and esimStatus the eSIM status enum (see folder overview).
Same as Get Plan Usage by Transaction, but looked up by your externalReference instead of the transaction id.
Requires Basic Authentication with your client credentials. Your account must be enabled for the eSIM service.
\nOn success code is 1000 and data is the usage object (see Get Plan Usage by Transaction).
The eSIM service lets you browse and provision data eSIM plans for travellers — discover coverage by country or region, buy a plan, receive the eSIM (QR / activation details), track the order, monitor data usage, and top up an active plan.
\nGET /regions, GET /countries, GET /plans (or GET /plans/country/{iso} / GET /plans/region/{code}).GET /plans/{id}/networks (operators) and GET /plans/{id}/topups (add-ons).POST /transactions/async; returns a transactionId, provisioning happens in the background.GET /transactions/{id} until status is Completed; the response then carries the eSIM product (ICCID, activation code, QR code).GET /transactions/{id}/plans/usage (or .../reference/{externalReference}/plans/usage).POST /transactions/async again with mainTransactionId set to the original transaction id.Orders are idempotent on externalReference.
status)coverageType)pricing.type)product.planType)planStatus — usage)esimStatus — usage)Returns the countries top-ups are supported for, with currency, calling codes, and dialing rules.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Topup service.
\nOn success code is 1000 and data is a paginated list of countries.
Returns mobile operators (carriers), optionally filtered by country. Use an operator id to list its products.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Topup service.
\nOn success code is 1000 and data is a paginated list of operators (with logoUrls).
Filter operators by country ISO code.
\n","type":"text/plain"},"key":"CountryIsoCode","value":"SA"},{"key":"Id","value":""},{"key":"Name","value":""},{"key":"Page","value":"1"},{"key":"PageSize","value":"50"}],"variable":[]}},"response":[{"id":"74dac85b-d842-4507-96fd-91359948f18a","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/Topup/operators?CountryIsoCode=SA&Id=&Name=&Page=1&PageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","Topup","operators"],"query":[{"key":"CountryIsoCode","value":"SA","description":"Filter operators by country ISO code."},{"key":"Id","value":""},{"key":"Name","value":""},{"key":"Page","value":"1"},{"key":"PageSize","value":"50"}]},"description":"Returns mobile **operators** (carriers), optionally filtered by country. Use an operator `id` to list its products.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Topup service.\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `CountryIsoCode` | `string` | No | — | Filter by country ISO code. |\n| `Id` | `string` | No | — | Filter by operator id. |\n| `Name` | `string` | No | — | Filter by operator name. |\n| `Page` | `int` | No | `1` | Page number. |\n| `PageSize` | `int` | No | `50` | Items per page. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a paginated list of operators (with `logoUrls`)."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"id\": \"341\",\n \"name\": \"STC\",\n \"country\": {\n \"name\": \"Saudi Arabia\",\n \"isoCode\": \"SA\",\n \"regions\": [\n {\n \"name\": \"Middle East\",\n \"code\": \"ME\"\n }\n ]\n },\n \"logoUrls\": [\n \"https://cdn.example.com/operators/stc.png\"\n ]\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"}],"_postman_id":"2d5dd362-98cb-4538-9e60-a2513020d5cc"},{"name":"Get Products","id":"f162dd52-a368-4c09-8798-520d2d2a8982","request":{"method":"GET","header":[],"url":"https://eservicespre.hoicom.net/api/v0/Topup/products?Id=&OperatorId=341&CountryIso=&Type=&Page=1&PageSize=50","description":"Returns top-up products (denominations/bundles), filterable by operator, country, or type. Each product carries pricing, validities, and classification.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Topup service.
\nOn success code is 1000 and data is a paginated list of products. type, validities[].type/unit, and classification.categories use the enums in the folder overview.
Filter by operator id.
\n","type":"text/plain"},"key":"OperatorId","value":"341"},{"key":"CountryIso","value":""},{"description":{"content":"Filter by product type (see folder overview).
\n","type":"text/plain"},"key":"Type","value":""},{"key":"Page","value":"1"},{"key":"PageSize","value":"50"}],"variable":[]}},"response":[{"id":"b4c7b0e8-2254-40b9-8322-4a235548f0f2","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/Topup/products?Id=&OperatorId=341&CountryIso=&Type=&Page=1&PageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","Topup","products"],"query":[{"key":"Id","value":""},{"key":"OperatorId","value":"341","description":"Filter by operator id."},{"key":"CountryIso","value":""},{"key":"Type","value":"","description":"Filter by product type (see folder overview)."},{"key":"Page","value":"1"},{"key":"PageSize","value":"50"}]},"description":"Returns top-up **products** (denominations/bundles), filterable by operator, country, or type. Each product carries `pricing`, `validities`, and `classification`.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Topup service.\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `Id` | `string` | No | — | Filter by product id. |\n| `OperatorId` | `string` | No | — | Filter by operator id. |\n| `CountryIso` | `string` | No | — | Filter by country ISO code. |\n| `Type` | `string` | No | — | Filter by product type: `INSTANT_FIXED`, `INSTANT_VARIABLE`, `PIN_BASED`. |\n| `Page` | `int` | No | `1` | Page number. |\n| `PageSize` | `int` | No | `50` | Items per page. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a paginated list of products. `type`, `validities[].type`/`unit`, and `classification.categories` use the enums in the folder overview."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"id\": \"6601\",\n \"type\": \"INSTANT_FIXED\",\n \"details\": {\n \"name\": \"STC 50 SAR\",\n \"description\": \"SAR 50 airtime top-up.\",\n \"termsAndConditions\": \"Standard top-up terms apply.\",\n \"usageInstructions\": \"Credited instantly to the mobile number.\"\n },\n \"pricing\": {\n \"currency\": \"SAR\",\n \"minAmount\": 50,\n \"maxAmount\": 50,\n \"destinationCurrency\": \"SAR\",\n \"minDestinationAmount\": 50,\n \"maxDestinationAmount\": 50,\n \"tax\": {\n \"taxRate\": 15,\n \"taxType\": \"VAT\",\n \"taxAmount\": 7.5\n }\n },\n \"validities\": [\n {\n \"type\": \"TIME_BASED\",\n \"unit\": \"DAYS\",\n \"quantity\": 30\n }\n ],\n \"classification\": {\n \"isPromotional\": false,\n \"categories\": [\n \"AIRTIME\"\n ]\n },\n \"availableRegions\": [\n {\n \"name\": \"Middle East\",\n \"code\": \"ME\"\n }\n ],\n \"operator\": {\n \"id\": \"341\",\n \"name\": \"STC\",\n \"country\": {\n \"name\": \"Saudi Arabia\",\n \"isoCode\": \"SA\",\n \"regions\": [\n {\n \"name\": \"Middle East\",\n \"code\": \"ME\"\n }\n ]\n },\n \"logoUrls\": [\n \"https://cdn.example.com/operators/stc.png\"\n ]\n }\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"}],"_postman_id":"f162dd52-a368-4c09-8798-520d2d2a8982"},{"name":"Look Up Products by Number","id":"4d41a86c-b500-4bbc-9963-d1c3ddcada5c","request":{"method":"GET","header":[],"url":"https://eservicespre.hoicom.net/api/v0/Topup/products/lookup/:number?page=1&pageSize=300","description":"Auto-detects the country and operator from a destination phone number and returns the matching top-up products — a shortcut for the countries → operators → products browse flow.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Topup service.
\nOn success code is 1000 and data contains the detected phoneNumber, country, operator, and a paginated products list.
Submits a top-up asynchronously. Returns immediately with a transaction id; poll Get Transaction by ID until status is Completed. Orders are idempotent on externalReference.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Topup service.
\nOn acceptance code is 1000 and data contains the transaction id.
Returns a single top-up transaction, including its status, the product/operator, amounts, and — for PIN-based products — pinDetails.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Topup service.
\nOn success code is 1000. status uses the Transaction status enum (see folder overview).
Returns a paginated, filterable list of your top-up transactions.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Topup service.
\nOn success code is 1000 and data is a paginated list of transactions. Valid status values: Submitted, Pending, Completed, Failed, Cancelled.
Enum name, e.g. Completed.
\n","type":"text/plain"},"key":"status","value":"Completed"},{"key":"fromDate","value":""},{"key":"toDate","value":""},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}],"variable":[]}},"response":[{"id":"afa00f5b-42ce-4e06-8068-cff17942c2f1","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/Topup/Transactions?transactionId=&externalReference=&status=Completed&fromDate=&toDate=&page=1&pageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","Topup","Transactions"],"query":[{"key":"transactionId","value":""},{"key":"externalReference","value":""},{"key":"status","value":"Completed","description":"Enum name, e.g. Completed."},{"key":"fromDate","value":""},{"key":"toDate","value":""},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}]},"description":"Returns a paginated, filterable list of your top-up transactions.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Topup service.\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `transactionId` | `string` | No | — | Filter by transaction id. |\n| `externalReference` | `string` | No | — | Filter by your external reference. |\n| `status` | `string` | No | — | Filter by status (enum name, e.g. `Completed`). |\n| `fromDate` | `datetime` | No | — | Start of creation-date range. |\n| `toDate` | `datetime` | No | — | End of creation-date range. |\n| `page` | `int` | No | `1` | Page number. |\n| `pageSize` | `int` | No | `50` | Items per page. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a paginated list of transactions. Valid `status` values: `Submitted`, `Pending`, `Completed`, `Failed`, `Cancelled`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"transactionId\": \"topup_txn_9f8e7d6c\",\n \"externalReference\": \"client-ref-3001\",\n \"status\": \"Completed\",\n \"timestamp\": {\n \"requestedAt\": \"2026-07-01T10:00:00Z\",\n \"completedAt\": \"2026-07-01T10:00:05Z\"\n },\n \"product\": {\n \"id\": \"6601\",\n \"name\": \"STC 50 SAR\",\n \"operator\": {\n \"id\": \"341\",\n \"name\": \"STC\",\n \"country\": {\n \"name\": \"Saudi Arabia\",\n \"isoCode\": \"SA\"\n }\n }\n },\n \"amounts\": {\n \"requestedAmount\": {\n \"amount\": 50,\n \"currency\": \"SAR\"\n },\n \"deliveredAmount\": {\n \"amount\": 50,\n \"currency\": \"SAR\"\n },\n \"fees\": {\n \"totalFee\": 0,\n \"currency\": \"SAR\"\n }\n },\n \"pinDetails\": null,\n \"receipt\": \"https://cdn.example.com/receipts/topup_txn_9f8e7d6c.pdf\"\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"}],"_postman_id":"9f134ed8-ef66-48ee-88c3-bdf3c1eee500"}],"id":"0139080f-d0bc-4620-a76d-ee2781a0a704","description":"The Topup service delivers mobile airtime and data top-ups to a destination phone number — browse supported countries, operators, and products, then submit a top-up and track it.
\nGET /countries.GET /operators?CountryIsoCode={iso}.GET /products?OperatorId={id} — or skip straight to GET /products/lookup/{number} to auto-detect country and operator from a phone number.POST /async; returns a transaction id, delivery happens in the background.GET /transactions/{id} (or GET /Transactions with filters) until status is Completed.Orders are idempotent on externalReference.
status)type)classification.categories)validities[].type)validities[].unit when type = TIME_BASED)validities[].unit when type = VOLUME_BASED)Returns the countries bill payments are supported for, with currency, calling codes, and dialing rules.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Utilities service.
\nOn success code is 1000 and data is a paginated list of countries.
Returns billers/operators, optionally filtered by country, id, or name. Use an operator id to list its bills/products.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Utilities service.
\nOn success code is 1000 and data is a paginated list of operators.
Returns the billers/operators available in a specific country.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Utilities service.
\nOn success code is 1000 and data is a paginated list of operators.
Returns the bills/products offered by a specific operator. Each product carries its pricing, paymentOptions, and the input fields required to pay.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Utilities service.
\nOn success code is 1000 and data is a paginated list of products. type uses the Payment type enum and pricing.paymentCurrencyType / paymentOptions.allowedPaymentOptions the Payment currency / Payment option enums (see folder overview).
Returns bills/products across operators, filterable by country, operator, or type.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Utilities service.
\nOn success code is 1000 and data is a paginated list of products.
Filter by payment type (see folder overview).
\n","type":"text/plain"},"key":"types","value":""},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}],"variable":[]}},"response":[{"id":"affedbc4-26f5-4b36-a208-808b6e5b42bd","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/Utilities?countryIsoCodes=SA&operatorsIds=&types=&page=1&pageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","Utilities"],"query":[{"key":"countryIsoCodes","value":"SA"},{"key":"operatorsIds","value":""},{"key":"types","value":"","description":"Filter by payment type (see folder overview)."},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}]},"description":"Returns bills/**products** across operators, filterable by country, operator, or type.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Utilities service.\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `countryIsoCodes` | `string[]` | No | — | Filter by country ISO code(s). |\n| `operatorsIds` | `string[]` | No | — | Filter by operator id(s). |\n| `types` | `string[]` | No | — | Filter by payment type: `RangedPayment`, `FixedRecharge`, `PINPurchase`. |\n| `page` | `int` | No | `1` | Page number. |\n| `pageSize` | `int` | No | `50` | Items per page. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a paginated list of products."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"id\": \"V1:12345\",\n \"type\": \"RangedPayment\",\n \"details\": {\n \"name\": \"STC Postpaid Bill\",\n \"serviceType\": \"Telecom\",\n \"description\": \"Pay your STC postpaid mobile bill.\",\n \"termsAndConditions\": \"Standard terms apply.\",\n \"usageInstructions\": \"Enter your account number to pay.\"\n },\n \"pricing\": {\n \"paymentCurrencyType\": \"ClientCurrency\",\n \"currency\": \"SAR\",\n \"minAmount\": 10,\n \"maxAmount\": 5000,\n \"destinationCurrency\": \"SAR\",\n \"minDestinationAmount\": 10,\n \"maxDestinationAmount\": 5000,\n \"fees\": 0,\n \"tax\": {\n \"taxRate\": 15,\n \"taxType\": \"VAT\",\n \"taxAmount\": 0\n }\n },\n \"paymentOptions\": {\n \"supportsAccountInquiry\": true,\n \"allowedPaymentOptions\": [\n \"ExactAmount\",\n \"AllowsPartialPayments\"\n ]\n },\n \"validities\": [\n {\n \"type\": \"PostingTime\",\n \"unit\": \"Day\",\n \"quantity\": 1\n }\n ],\n \"transactionRequiredFields\": [\n \"accountNumber\"\n ],\n \"receiverRequiredFields\": [],\n \"operator\": {\n \"id\": \"op_stc\",\n \"name\": \"STC\",\n \"country\": {\n \"name\": \"Saudi Arabia\",\n \"isoCode\": \"SA\",\n \"regions\": []\n },\n \"logoUrls\": [\n \"https://cdn.example.com/operators/stc.png\"\n ]\n }\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"}],"_postman_id":"59b8a0a8-ec85-4bf2-bd99-aeec2b2f120b"},{"name":"Account Inquiry","id":"69f93392-32af-46d3-8155-ca955d1f0383","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"productId\": \"V1:12345\",\n \"transactionRequiredFields\": {\n \"accountNumber\": \"123456789\"\n }\n}","options":{"raw":{"language":"json"}}},"url":"https://eservicespre.hoicom.net/api/v0/Utilities/accounts/inquiry","description":"For products where paymentOptions.supportsAccountInquiry is true, looks up the outstanding bill(s) for an account before payment — returns the amount due, issue/due dates, and a customer reference.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Utilities service.
\nOn success code is 1000 and data is a list of bills, each with amountDue, issueDate, dueDate, and customerReference.
Pays a bill asynchronously. Returns immediately with a transactionId; poll Get Transaction by ID until status is Completed. Idempotent on externalReference.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Utilities service.
\nOn acceptance code is 1000 and data contains the transactionId.
Returns a single bill-payment transaction, including its status, product/operator, and amounts.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Utilities service.
\nOn success code is 1000. status uses the Transaction status enum (see folder overview).
Returns a paginated, filterable list of your bill-payment transactions.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Utilities service.
\nOn success code is 1000 and data is a paginated list of transactions. Valid status values: Submitted, Pending, Completed, Failed, Cancelled.
Enum name, e.g. Completed.
\n","type":"text/plain"},"key":"status","value":"Completed"},{"key":"fromDate","value":""},{"key":"toDate","value":""},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}],"variable":[]}},"response":[{"id":"fe67b853-b7a1-412d-a430-dea2317ce0de","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/Utilities/Transactions?transactionId=&externalReference=&status=Completed&fromDate=&toDate=&page=1&pageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","Utilities","Transactions"],"query":[{"key":"transactionId","value":""},{"key":"externalReference","value":""},{"key":"status","value":"Completed","description":"Enum name, e.g. Completed."},{"key":"fromDate","value":""},{"key":"toDate","value":""},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}]},"description":"Returns a paginated, filterable list of your bill-payment transactions.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Utilities service.\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `transactionId` | `string` | No | — | Filter by transaction id. |\n| `externalReference` | `string` | No | — | Filter by your external reference. |\n| `status` | `string` | No | — | Filter by status (enum name, e.g. `Completed`). |\n| `fromDate` | `datetime` | No | — | Start of creation-date range. |\n| `toDate` | `datetime` | No | — | End of creation-date range. |\n| `page` | `int` | No | `1` | Page number. |\n| `pageSize` | `int` | No | `50` | Items per page. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a paginated list of transactions. Valid `status` values: `Submitted`, `Pending`, `Completed`, `Failed`, `Cancelled`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"transactionId\": \"util_txn_7c2d\",\n \"externalReference\": \"client-ref-4001\",\n \"status\": \"Completed\",\n \"timestamp\": {\n \"requestedAt\": \"2026-07-01T11:00:00Z\",\n \"completedAt\": \"2026-07-01T11:01:30Z\"\n },\n \"product\": {\n \"id\": \"V1:12345\",\n \"name\": \"STC Postpaid Bill\",\n \"operator\": {\n \"id\": \"op_stc\",\n \"name\": \"STC\",\n \"country\": {\n \"name\": \"Saudi Arabia\",\n \"isoCode\": \"SA\"\n }\n }\n },\n \"amounts\": {\n \"requestedAmount\": {\n \"amount\": 245.5,\n \"currency\": \"SAR\"\n },\n \"deliveredAmount\": {\n \"amount\": 245.5,\n \"currency\": \"SAR\"\n },\n \"fees\": {\n \"totalFee\": 0,\n \"currency\": \"SAR\"\n }\n },\n \"pinDetails\": null,\n \"receipt\": \"Bill payment of SAR 245.50 to STC (account ACC-778812) — completed.\"\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"}],"_postman_id":"cfaf038f-7568-4387-926c-9879b793d1de"}],"id":"b7122c82-6166-4320-adb9-a2a4b58b51c0","description":"The Utilities service pays bills and utility accounts (telecom, electricity, water, and more) via supported billers — browse countries, operators, and products, look up an outstanding bill, then pay it and track the payment.
\nGET /countries.GET /operators?countryIsoCodes={iso} or GET /countries/{iso}/operators.GET /operators/{operatorId}/products (or GET / with filters).paymentOptions.supportsAccountInquiry = true, call POST /accounts/inquiry to fetch the amount due.POST /transactions/async; returns a transactionId, payment happens in the background.GET /transactions/{id} (or GET /Transactions with filters) until status is Completed.Payments are idempotent on externalReference. Use the product's transactionRequiredFields list to know which key/value fields to send.
status)type)pricing.paymentCurrencyType)paymentOptions.allowedPaymentOptions)Lists the gift-card brands available to your account (e.g. iTunes, Amazon), filterable by category, country, or search term.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Gift Cards service.
\nOn success code is 1000 and data is a paginated list of brands. category uses the Category enum (see folder overview).
Filter by category (see folder overview).
\n","type":"text/plain"},"key":"categories","value":"ENTERTAINMENT"},{"key":"countryIso3Codes","value":"USA"},{"key":"searchTerms","value":""},{"description":{"content":"English or Arabic.
\n","type":"text/plain"},"key":"lang","value":"English"},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}],"variable":[]}},"response":[{"id":"ac22a29c-a285-4988-affa-decbe9fd03bb","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/giftcards/brands?ids=&categories=ENTERTAINMENT&countryIso3Codes=USA&searchTerms=&lang=English&page=1&pageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","giftcards","brands"],"query":[{"key":"ids","value":""},{"key":"categories","value":"ENTERTAINMENT","description":"Filter by category (see folder overview)."},{"key":"countryIso3Codes","value":"USA"},{"key":"searchTerms","value":""},{"key":"lang","value":"English","description":"English or Arabic."},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}]},"description":"Lists the gift-card **brands** available to your account (e.g. iTunes, Amazon), filterable by category, country, or search term.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Gift Cards service.\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `ids` | `int[]` | No | — | Filter by brand id(s). |\n| `categories` | `string[]` | No | — | Filter by category (see folder overview). |\n| `countryIso3Codes` | `string[]` | No | — | Filter by ISO 3166-1 alpha-3 country code(s). |\n| `searchTerms` | `string[]` | No | — | Match brand code or name. |\n| `lang` | `string` | No | `English` | Display language: `English` or `Arabic`. |\n| `page` | `int` | No | `1` | Page number. |\n| `pageSize` | `int` | No | `50` | Items per page (max 100). |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a paginated list of brands. `category` uses the **Category** enum (see folder overview)."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"id\": 123,\n \"code\": \"GC-ENT-US-001\",\n \"category\": \"ENTERTAINMENT\",\n \"countryIso3\": \"USA\",\n \"name\": \"iTunes (US)\",\n \"description\": \"Apple iTunes US gift cards.\"\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"}],"_postman_id":"9f2e2cf7-fe42-4603-9026-10008a90b008"},{"name":"Get Products","id":"7baf8bdc-6e7f-42a7-8a57-4f299532a91f","request":{"method":"GET","header":[],"url":"https://eservicespre.hoicom.net/api/v0/giftcards/products?ids=&brandIds=123&categories=&countryIso3Codes=&denominationTypes=FIXED&searchTerms=&includeContent=true&includeInputFields=true&lang=English&page=1&pageSize=50","description":"Lists the priced gift-card products (specific denominations of a brand). Each product carries its denomination, pricing (in SAR), deliveryFormat, and — when requested — descriptive content and required transactionInputFields.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Gift Cards service.
\nOn success code is 1000 and data is a paginated list of products. denomination.type, deliveryFormat, pricing.mode, and transactionInputFields[].type use the enums in the folder overview. pricing.wholesale is what you are billed (SAR); pricing.retail is the suggested customer price.
FIXED, RANGE, or OPEN.
\n","type":"text/plain"},"key":"denominationTypes","value":"FIXED"},{"key":"searchTerms","value":""},{"description":{"content":"Include the localized content block.
\n","type":"text/plain"},"key":"includeContent","value":"true"},{"description":{"content":"Include required transaction input fields.
\n","type":"text/plain"},"key":"includeInputFields","value":"true"},{"key":"lang","value":"English"},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}],"variable":[]}},"response":[{"id":"af23e1f3-d1ae-4e7d-9231-a0f14dfafc60","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/giftcards/products?ids=&brandIds=123&categories=&countryIso3Codes=&denominationTypes=FIXED&searchTerms=&includeContent=true&includeInputFields=true&lang=English&page=1&pageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","giftcards","products"],"query":[{"key":"ids","value":""},{"key":"brandIds","value":"123"},{"key":"categories","value":""},{"key":"countryIso3Codes","value":""},{"key":"denominationTypes","value":"FIXED","description":"FIXED, RANGE, or OPEN."},{"key":"searchTerms","value":""},{"key":"includeContent","value":"true","description":"Include the localized content block."},{"key":"includeInputFields","value":"true","description":"Include required transaction input fields."},{"key":"lang","value":"English"},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}]},"description":"Lists the priced gift-card **products** (specific denominations of a brand). Each product carries its `denomination`, `pricing` (in SAR), `deliveryFormat`, and — when requested — descriptive `content` and required `transactionInputFields`.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Gift Cards service.\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `ids` | `int[]` | No | — | Filter by product id(s). Fetch a single product this way. |\n| `brandIds` | `int[]` | No | — | Filter by brand id(s). |\n| `categories` | `string[]` | No | — | Filter by category. |\n| `countryIso3Codes` | `string[]` | No | — | Filter by ISO alpha-3 country code(s). |\n| `denominationTypes` | `string[]` | No | — | Filter by denomination type: `FIXED`, `RANGE`, `OPEN`. |\n| `searchTerms` | `string[]` | No | — | Match product code or name. |\n| `includeContent` | `bool` | No | `false` | Include localized descriptions / T&C / images. |\n| `includeInputFields` | `bool` | No | `false` | Include the required transaction input fields. |\n| `lang` | `string` | No | `English` | Display language: `English` or `Arabic`. |\n| `page` | `int` | No | `1` | Page number. |\n| `pageSize` | `int` | No | `50` | Items per page (max 100). |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a paginated list of products. `denomination.type`, `deliveryFormat`, `pricing.mode`, and `transactionInputFields[].type` use the enums in the folder overview. `pricing.wholesale` is what you are billed (SAR); `pricing.retail` is the suggested customer price."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"id\": 456,\n \"code\": \"GC-ENT-US-001-10USD\",\n \"info\": {\n \"brandId\": 123,\n \"brandCode\": \"GC-ENT-US-001\",\n \"category\": \"ENTERTAINMENT\",\n \"countryIso3\": \"USA\",\n \"name\": \"iTunes US $10\"\n },\n \"amountCurrency\": null,\n \"deliveryFormat\": \"PIN\",\n \"transactionInputFields\": [\n {\n \"key\": \"email\",\n \"label\": \"Recipient Email\",\n \"type\": \"EMAIL\",\n \"required\": true,\n \"validation\": {\n \"regex\": \"^[^@]+@[^@]+$\",\n \"minLength\": null,\n \"maxLength\": 255,\n \"min\": null,\n \"max\": null,\n \"allowedValues\": []\n }\n }\n ],\n \"denomination\": {\n \"type\": \"FIXED\",\n \"currency\": \"USD\",\n \"value\": 10,\n \"min\": null,\n \"max\": null,\n \"increment\": null\n },\n \"pricing\": {\n \"currency\": \"SAR\",\n \"mode\": \"WHOLESALE\",\n \"wholesale\": {\n \"value\": 37.5,\n \"rate\": null,\n \"min\": null,\n \"max\": null,\n \"increment\": null\n },\n \"retail\": {\n \"value\": 45,\n \"rate\": null,\n \"min\": null,\n \"max\": null,\n \"increment\": null\n },\n \"discount\": null\n },\n \"content\": {\n \"description\": \"Redeem for apps, games, music and more on the US App Store / iTunes.\",\n \"shortDescription\": \"iTunes US gift card\",\n \"termsAndConditions\": \"Valid for 12 months from purchase. US accounts only.\",\n \"redemptionInstructions\": \"Redeem at itunes.com/redeem.\",\n \"disclaimer\": \"Non-refundable.\",\n \"validityText\": \"12 Months\",\n \"images\": [\n {\n \"type\": \"LOGO\",\n \"url\": \"https://cdn.example.com/giftcards/itunes-logo.png\"\n },\n {\n \"type\": \"CARD\",\n \"url\": \"https://cdn.example.com/giftcards/itunes-card.png\"\n }\n ]\n }\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"}],"_postman_id":"7baf8bdc-6e7f-42a7-8a57-4f299532a91f"},{"name":"Create Transaction","id":"66a6858e-a616-4636-9cfb-fdf81ec91322","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"externalReference\": \"client-ref-5001\",\n \"productId\": 456,\n \"amount\": null,\n \"amountCurrency\": null,\n \"transactionInputs\": [\n {\n \"key\": \"email\",\n \"value\": \"recipient@example.com\"\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://eservicespre.hoicom.net/api/v0/giftcards/transactions/async","description":"Orders a gift card asynchronously. Returns immediately with a transactionId; poll Get Transaction by ID until status is Completed to retrieve the delivered card (PIN / redemption URL / QR). Idempotent on externalReference.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Gift Cards service.
\nOn acceptance code is 1000 and data contains the transactionId.
Returns a single gift-card transaction — its status, ordered denomination, billed price, and (once Completed) the delivered card artifact in delivery.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Gift Cards service.
\nOn success code is 1000. status uses the Transaction status enum; delivery.format the Delivery format enum (see folder overview). delivery is populated only when status is Completed; errorDetails only when Failed. spReference is the fulfilling partner's order id (for support).
Returns a paginated, filterable list of your gift-card transactions.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Gift Cards service.
\nOn success code is 1000 and data is a paginated list of transactions. Valid status values: Submitted, Pending, Completed, Failed, Cancelled.
Enum name, e.g. Completed.
\n","type":"text/plain"},"key":"statuses","value":"Completed"},{"key":"fromDate","value":""},{"key":"toDate","value":""},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}],"variable":[]}},"response":[{"id":"3c0c300b-a573-4550-beaf-bf7359956d6b","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/giftcards/transactions?transactionIds=&externalReferences=&productIds=&statuses=Completed&fromDate=&toDate=&page=1&pageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","giftcards","transactions"],"query":[{"key":"transactionIds","value":""},{"key":"externalReferences","value":""},{"key":"productIds","value":""},{"key":"statuses","value":"Completed","description":"Enum name, e.g. Completed."},{"key":"fromDate","value":""},{"key":"toDate","value":""},{"key":"page","value":"1"},{"key":"pageSize","value":"50"}]},"description":"Returns a paginated, filterable list of your gift-card transactions.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Gift Cards service.\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `transactionIds` | `string[]` | No | — | Filter by transaction id(s). |\n| `externalReferences` | `string[]` | No | — | Filter by your external reference(s). |\n| `productIds` | `int[]` | No | — | Filter by product id(s). |\n| `statuses` | `string[]` | No | — | Filter by status (enum names, e.g. `Completed`). |\n| `fromDate` | `datetime` | No | — | Created on/after. |\n| `toDate` | `datetime` | No | — | Created on/before. |\n| `page` | `int` | No | `1` | Page number. |\n| `pageSize` | `int` | No | `50` | Items per page (max 100). |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` is a paginated list of transactions. Valid `status` values: `Submitted`, `Pending`, `Completed`, `Failed`, `Cancelled`."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"transactionId\": \"gc_txn_20260701_00123\",\n \"externalReference\": \"client-ref-5001\",\n \"productId\": 456,\n \"productCode\": \"GC-ENT-US-001-10USD\",\n \"status\": \"Completed\",\n \"denomination\": {\n \"type\": \"FIXED\",\n \"currency\": \"USD\",\n \"value\": 10,\n \"min\": null,\n \"max\": null,\n \"increment\": null\n },\n \"amountCurrency\": null,\n \"price\": {\n \"currency\": \"SAR\",\n \"wholesale\": 37.5,\n \"retail\": 45,\n \"discount\": null\n },\n \"delivery\": {\n \"format\": \"PIN\",\n \"code\": \"X7Y2-9931-ABCD\",\n \"pin\": \"5678\",\n \"cardNumber\": null,\n \"serial\": \"ITUNES-USA-001122\",\n \"redemptionUrl\": null,\n \"qrCode\": null,\n \"instructions\": \"Redeem at itunes.com/redeem.\"\n },\n \"spReference\": \"SP-ORD-9876543\",\n \"createdAt\": \"2026-07-01T14:30:00Z\",\n \"completedAt\": \"2026-07-01T14:31:20Z\",\n \"errorDetails\": null\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"}],"_postman_id":"41279ef4-9e17-4d14-b1ff-a128b121af62"}],"id":"b9f2673c-e2df-4de6-a35d-7c3c87d62f8a","description":"\n\n🚧 Coming soon — the Gift Cards service is under active development. The Brands and Products catalogue is available; the transaction endpoints are being finalized and their contract may still change.
\n
The Gift Cards service sells digital gift cards (retail, gaming, entertainment, and more) — browse brands and their priced products, order a card, and retrieve the delivered redemption artifact (PIN, redemption URL, or QR code).
\nGET /brands (filter by category / country / search).GET /products?brandIds={id}&includeContent=true&includeInputFields=true. Check denomination (FIXED vs RANGE/OPEN), pricing.wholesale (what you're billed) / pricing.retail (suggested price), and the required transactionInputFields.POST /transactions/async with the product id and required inputs; returns a transactionId.GET /transactions/{id} until status is Completed; the delivery block then carries the PIN / redemption URL / QR.GET /transactions (filter by reference, product, status, date).Orders are idempotent on externalReference. Prices are always in SAR.
status)category)denomination.type)deliveryFormat / delivery.format)amountCurrency)pricing.mode)transactionInputFields[].type)content.images[].type)lang request parameter)Returns the locations available for gift delivery, each with its associated fulfillment centers. A fulfillment center is the hub that prepares and dispatches orders for a delivery area — you use its fulfillmentCenterId to filter products and to check delivery time slots.
This is typically the first call in the gift ordering journey.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Gifts service.
\nOn success code is 1000 and data holds a paginated list of countries, their cities, and each city's fulfillment centers. See the example below.
Page number for pagination (default: 1).
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"Number of items per page (default: 50).
\n","type":"text/plain"},"key":"pageSize","value":"50"}],"variable":[]}},"response":[{"id":"ea570931-8d92-4c16-8155-5fa4e44e6d9e","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/locations?page=1&pageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","locations"],"query":[{"key":"page","value":"1","description":"Page number for pagination (default: 1)."},{"key":"pageSize","value":"50","description":"Number of items per page (default: 50)."}]},"description":"Returns the locations available for gift delivery, each with its associated **fulfillment centers**. A fulfillment center is the hub that prepares and dispatches orders for a delivery area — you use its `fulfillmentCenterId` to filter products and to check delivery time slots.\n\nThis is typically the **first call** in the gift ordering journey.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Gifts service.\n\n---\n\n## Query Parameters\n\n| Parameter | Type | Required | Default | Description |\n| --- | --- | --- | --- | --- |\n| `page` | `int` | No | `1` | Page number for pagination. |\n| `pageSize` | `int` | No | `50` | Number of items per page. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` holds a paginated list of countries, their cities, and each city's fulfillment centers. See the example below."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"name\": \"Saudi Arabia\",\n \"isoCode\": \"SA\",\n \"cities\": [\n {\n \"name\": \"Riyadh\",\n \"fulfillmentCenters\": [\n {\n \"id\": \"fc_riyadh_01\",\n \"name\": \"Riyadh Central\"\n },\n {\n \"id\": \"fc_riyadh_02\",\n \"name\": \"Riyadh North\"\n }\n ]\n }\n ]\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"},{"id":"36671adf-cac2-4856-b2a0-f1a680631fc8","name":"Internal Server Error","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/locations?page=1&pageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","locations"],"query":[{"description":"Page number for pagination (default: 1).","key":"page","value":"1"},{"description":"Number of items per page (default: 50).","key":"pageSize","value":"50"}]}},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""},{"id":"e00ba23b-6147-4667-8efb-9265a8555317","name":"Service Unavailable","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/locations?page=1&pageSize=50","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","locations"],"query":[{"description":"Page number for pagination (default: 1).","key":"page","value":"1"},{"description":"Number of items per page (default: 50).","key":"pageSize","value":"50"}]}},"status":"Service Unavailable","code":503,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"c86834cb-b8ba-4ab0-8f2f-8f81fe5552f7"},{"name":"Get Products by Fulfillment Center","id":"d5bc9587-115b-4385-8e77-75c4c166f1fa","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"text/plain"}],"url":"https://eservicespre.hoicom.net/api/v0/gifts/products/fc/:fulfillmentCenterId?searchTerm=string&sku=string&productId=string&minPrice=6039.208844241599&maxPrice=6039.208844241599&minQty=6997&maxQty=6997&sortBy=Details.ProductName&sortDescending=false&page=1&pageSize=50&lang=ar","description":"Returns the gift products (flowers, chocolates, gift baskets, etc.) available for delivery by a specific fulfillment center, with full search, filtering, and sorting support. Prices and quantities reflect what that fulfillment center can offer.
\nUse this after selecting a location/fulfillment center from Get Locations.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Gifts service.
\nOn success code is 1000 and data holds a paginated list of products, each with its details (name, SKU, images, description) and pricing (price, VAT, currency, total). See the example below.
Optional keyword to search in product names or descriptions.
\n","type":"text/plain"},"key":"searchTerm","value":"string"},{"description":{"content":"Optional exact product SKU to filter by.
\n","type":"text/plain"},"key":"sku","value":"string"},{"description":{"content":"Optional product ID to filter by.
\n","type":"text/plain"},"key":"productId","value":"string"},{"description":{"content":"Optional minimum price filter.
\n","type":"text/plain"},"key":"minPrice","value":"6039.208844241599"},{"description":{"content":"Optional maximum price filter.
\n","type":"text/plain"},"key":"maxPrice","value":"6039.208844241599"},{"description":{"content":"Optional minimum quantity filter.
\n","type":"text/plain"},"key":"minQty","value":"6997"},{"description":{"content":"Optional maximum quantity filter.
\n","type":"text/plain"},"key":"maxQty","value":"6997"},{"description":{"content":"Optional field to sort by: Details.ProductName, Details.Sku, Pricing.Price, Availability.Qty.
\n","type":"text/plain"},"key":"sortBy","value":"Details.ProductName"},{"description":{"content":"Optional whether to sort descending (default: false).
\n","type":"text/plain"},"key":"sortDescending","value":"false"},{"description":{"content":"Page number for pagination (default: 1).
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"Number of items per page (default: 50).
\n","type":"text/plain"},"key":"pageSize","value":"50"},{"description":{"content":"Language for text fields: \"ar\" (Arabic, default) or \"en\" (English).
\n","type":"text/plain"},"key":"lang","value":"ar"}],"variable":[{"description":{"content":"The fulfillment center identifier to filter products by.
\n","type":"text/plain"},"type":"any","value":"string","key":"fulfillmentCenterId"}]}},"response":[{"id":"e8fc37ae-2209-46fb-9302-d5a94b532779","name":"OK","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"text/plain"}],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/products/fc/:fulfillmentCenterId?searchTerm=string&sku=string&productId=string&minPrice=6039.208844241599&maxPrice=6039.208844241599&minQty=6997&maxQty=6997&sortBy=Details.ProductName&sortDescending=false&page=1&pageSize=50&lang=ar","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","products","fc",":fulfillmentCenterId"],"query":[{"description":"Optional keyword to search in product names or descriptions.","key":"searchTerm","value":"string"},{"description":"Optional exact product SKU to filter by.","key":"sku","value":"string"},{"description":"Optional product ID to filter by.","key":"productId","value":"string"},{"description":"Optional minimum price filter.","key":"minPrice","value":"6039.208844241599"},{"description":"Optional maximum price filter.","key":"maxPrice","value":"6039.208844241599"},{"description":"Optional minimum quantity filter.","key":"minQty","value":"6997"},{"description":"Optional maximum quantity filter.","key":"maxQty","value":"6997"},{"description":"Optional field to sort by: Details.ProductName, Details.Sku, Pricing.Price, Availability.Qty.","key":"sortBy","value":"Details.ProductName"},{"description":"Optional whether to sort descending (default: false).","key":"sortDescending","value":"false"},{"description":"Page number for pagination (default: 1).","key":"page","value":"1"},{"description":"Number of items per page (default: 50).","key":"pageSize","value":"50"},{"description":"Language for text fields: \"ar\" (Arabic, default) or \"en\" (English).","key":"lang","value":"ar"}],"variable":[{"key":"fulfillmentCenterId","value":"string","description":"The fulfillment center identifier to filter products by."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"id\": \"prod_10021\",\n \"details\": {\n \"name\": \"Red Roses Bouquet\",\n \"sku\": \"FLW-ROSE-RED-12\",\n \"mainImage\": \"https://cdn.example.com/products/roses-red.jpg\",\n \"imageUrls\": [\n \"https://cdn.example.com/products/roses-red-1.jpg\",\n \"https://cdn.example.com/products/roses-red-2.jpg\"\n ],\n \"description\": \"A dozen premium long-stem red roses, hand-arranged.\",\n \"shortDescription\": \"12 premium red roses\"\n },\n \"pricing\": {\n \"price\": 199,\n \"vat\": 29.85,\n \"currency\": \"SAR\",\n \"total\": 228.85\n }\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"},{"id":"0c90832d-8359-4b10-b4ad-e2a5056bfc8d","name":"Internal Server Error","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/products/fc/:fulfillmentCenterId?searchTerm=string&sku=string&productId=string&minPrice=6039.208844241599&maxPrice=6039.208844241599&minQty=6997&maxQty=6997&sortBy=Details.ProductName&sortDescending=false&page=1&pageSize=50&lang=ar","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","products","fc",":fulfillmentCenterId"],"query":[{"description":"Optional keyword to search in product names or descriptions.","key":"searchTerm","value":"string"},{"description":"Optional exact product SKU to filter by.","key":"sku","value":"string"},{"description":"Optional product ID to filter by.","key":"productId","value":"string"},{"description":"Optional minimum price filter.","key":"minPrice","value":"6039.208844241599"},{"description":"Optional maximum price filter.","key":"maxPrice","value":"6039.208844241599"},{"description":"Optional minimum quantity filter.","key":"minQty","value":"6997"},{"description":"Optional maximum quantity filter.","key":"maxQty","value":"6997"},{"description":"Optional field to sort by: Details.ProductName, Details.Sku, Pricing.Price, Availability.Qty.","key":"sortBy","value":"Details.ProductName"},{"description":"Optional whether to sort descending (default: false).","key":"sortDescending","value":"false"},{"description":"Page number for pagination (default: 1).","key":"page","value":"1"},{"description":"Number of items per page (default: 50).","key":"pageSize","value":"50"},{"description":"Language for text fields: \"ar\" (Arabic, default) or \"en\" (English).","key":"lang","value":"ar"}],"variable":[{"key":"fulfillmentCenterId","value":"string","description":"The fulfillment center identifier to filter products by."}]}},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""},{"id":"acb3fbc4-1777-41d0-89c3-f42a23a469b1","name":"Service Unavailable","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/products/fc/:fulfillmentCenterId?searchTerm=string&sku=string&productId=string&minPrice=6039.208844241599&maxPrice=6039.208844241599&minQty=6997&maxQty=6997&sortBy=Details.ProductName&sortDescending=false&page=1&pageSize=50&lang=ar","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","products","fc",":fulfillmentCenterId"],"query":[{"description":"Optional keyword to search in product names or descriptions.","key":"searchTerm","value":"string"},{"description":"Optional exact product SKU to filter by.","key":"sku","value":"string"},{"description":"Optional product ID to filter by.","key":"productId","value":"string"},{"description":"Optional minimum price filter.","key":"minPrice","value":"6039.208844241599"},{"description":"Optional maximum price filter.","key":"maxPrice","value":"6039.208844241599"},{"description":"Optional minimum quantity filter.","key":"minQty","value":"6997"},{"description":"Optional maximum quantity filter.","key":"maxQty","value":"6997"},{"description":"Optional field to sort by: Details.ProductName, Details.Sku, Pricing.Price, Availability.Qty.","key":"sortBy","value":"Details.ProductName"},{"description":"Optional whether to sort descending (default: false).","key":"sortDescending","value":"false"},{"description":"Page number for pagination (default: 1).","key":"page","value":"1"},{"description":"Number of items per page (default: 50).","key":"pageSize","value":"50"},{"description":"Language for text fields: \"ar\" (Arabic, default) or \"en\" (English).","key":"lang","value":"ar"}],"variable":[{"key":"fulfillmentCenterId","value":"string","description":"The fulfillment center identifier to filter products by."}]}},"status":"Service Unavailable","code":503,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"d5bc9587-115b-4385-8e77-75c4c166f1fa"},{"name":"Get Products","id":"7d37b92a-9b42-4e36-bea8-c431a767922e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"text/plain"}],"url":"https://eservicespre.hoicom.net/api/v0/gifts/products?searchTerm=string&sku=string&productId=string&minPrice=6039.208844241599&maxPrice=6039.208844241599&minQty=6997&maxQty=6997&sortBy=Details.ProductName&sortDescending=false&page=1&pageSize=50&lang=ar","description":"Returns gift products across all fulfillment centers, with the same search, filtering, and sorting options as Get Products by Fulfillment Center. Use this to browse the full catalogue when you are not yet tied to a specific fulfillment center.
\n\n\nTo order a product, the recipient's fulfillment center must be able to fulfill it — prefer Get Products by Fulfillment Center once a delivery area is known.
\n
Requires Basic Authentication with your client credentials. Your account must be enabled for the Gifts service.
\nOn success code is 1000 and data holds a paginated list of products (details + pricing). See the example below.
Optional keyword to search in product names or descriptions.
\n","type":"text/plain"},"key":"searchTerm","value":"string"},{"description":{"content":"Optional exact product SKU to filter by.
\n","type":"text/plain"},"key":"sku","value":"string"},{"description":{"content":"Optional product ID to filter by.
\n","type":"text/plain"},"key":"productId","value":"string"},{"description":{"content":"Optional minimum price filter.
\n","type":"text/plain"},"key":"minPrice","value":"6039.208844241599"},{"description":{"content":"Optional maximum price filter.
\n","type":"text/plain"},"key":"maxPrice","value":"6039.208844241599"},{"description":{"content":"Optional minimum quantity filter.
\n","type":"text/plain"},"key":"minQty","value":"6997"},{"description":{"content":"Optional maximum quantity filter.
\n","type":"text/plain"},"key":"maxQty","value":"6997"},{"description":{"content":"Optional field to sort by: Details.ProductName, Details.Sku, Pricing.Price, Availability.Qty.
\n","type":"text/plain"},"key":"sortBy","value":"Details.ProductName"},{"description":{"content":"Optional whether to sort descending (default: false).
\n","type":"text/plain"},"key":"sortDescending","value":"false"},{"description":{"content":"Page number for pagination (default: 1).
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"Number of items per page (default: 50).
\n","type":"text/plain"},"key":"pageSize","value":"50"},{"description":{"content":"Language for text fields: \"ar\" (Arabic, default) or \"en\" (English).
\n","type":"text/plain"},"key":"lang","value":"ar"}],"variable":[]}},"response":[{"id":"5b6da409-153e-4a5a-9f40-aed589d9a536","name":"OK","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"text/plain"}],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/products?searchTerm=string&sku=string&productId=string&minPrice=6039.208844241599&maxPrice=6039.208844241599&minQty=6997&maxQty=6997&sortBy=Details.ProductName&sortDescending=false&page=1&pageSize=50&lang=ar","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","products"],"query":[{"description":"Optional keyword to search in product names or descriptions.","key":"searchTerm","value":"string"},{"description":"Optional exact product SKU to filter by.","key":"sku","value":"string"},{"description":"Optional product ID to filter by.","key":"productId","value":"string"},{"description":"Optional minimum price filter.","key":"minPrice","value":"6039.208844241599"},{"description":"Optional maximum price filter.","key":"maxPrice","value":"6039.208844241599"},{"description":"Optional minimum quantity filter.","key":"minQty","value":"6997"},{"description":"Optional maximum quantity filter.","key":"maxQty","value":"6997"},{"description":"Optional field to sort by: Details.ProductName, Details.Sku, Pricing.Price, Availability.Qty.","key":"sortBy","value":"Details.ProductName"},{"description":"Optional whether to sort descending (default: false).","key":"sortDescending","value":"false"},{"description":"Page number for pagination (default: 1).","key":"page","value":"1"},{"description":"Number of items per page (default: 50).","key":"pageSize","value":"50"},{"description":"Language for text fields: \"ar\" (Arabic, default) or \"en\" (English).","key":"lang","value":"ar"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"id\": \"prod_10021\",\n \"details\": {\n \"name\": \"Red Roses Bouquet\",\n \"sku\": \"FLW-ROSE-RED-12\",\n \"mainImage\": \"https://cdn.example.com/products/roses-red.jpg\",\n \"imageUrls\": [\n \"https://cdn.example.com/products/roses-red-1.jpg\",\n \"https://cdn.example.com/products/roses-red-2.jpg\"\n ],\n \"description\": \"A dozen premium long-stem red roses, hand-arranged.\",\n \"shortDescription\": \"12 premium red roses\"\n },\n \"pricing\": {\n \"price\": 199,\n \"vat\": 29.85,\n \"currency\": \"SAR\",\n \"total\": 228.85\n }\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"},{"id":"53a31442-f9f5-47e1-b1cb-bded0a3951e1","name":"Internal Server Error","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/products?searchTerm=string&sku=string&productId=string&minPrice=6039.208844241599&maxPrice=6039.208844241599&minQty=6997&maxQty=6997&sortBy=Details.ProductName&sortDescending=false&page=1&pageSize=50&lang=ar","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","products"],"query":[{"description":"Optional keyword to search in product names or descriptions.","key":"searchTerm","value":"string"},{"description":"Optional exact product SKU to filter by.","key":"sku","value":"string"},{"description":"Optional product ID to filter by.","key":"productId","value":"string"},{"description":"Optional minimum price filter.","key":"minPrice","value":"6039.208844241599"},{"description":"Optional maximum price filter.","key":"maxPrice","value":"6039.208844241599"},{"description":"Optional minimum quantity filter.","key":"minQty","value":"6997"},{"description":"Optional maximum quantity filter.","key":"maxQty","value":"6997"},{"description":"Optional field to sort by: Details.ProductName, Details.Sku, Pricing.Price, Availability.Qty.","key":"sortBy","value":"Details.ProductName"},{"description":"Optional whether to sort descending (default: false).","key":"sortDescending","value":"false"},{"description":"Page number for pagination (default: 1).","key":"page","value":"1"},{"description":"Number of items per page (default: 50).","key":"pageSize","value":"50"},{"description":"Language for text fields: \"ar\" (Arabic, default) or \"en\" (English).","key":"lang","value":"ar"}]}},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""},{"id":"3e5ed2b4-2484-4668-8294-1e5256b3a5c7","name":"Service Unavailable","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/products?searchTerm=string&sku=string&productId=string&minPrice=6039.208844241599&maxPrice=6039.208844241599&minQty=6997&maxQty=6997&sortBy=Details.ProductName&sortDescending=false&page=1&pageSize=50&lang=ar","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","products"],"query":[{"description":"Optional keyword to search in product names or descriptions.","key":"searchTerm","value":"string"},{"description":"Optional exact product SKU to filter by.","key":"sku","value":"string"},{"description":"Optional product ID to filter by.","key":"productId","value":"string"},{"description":"Optional minimum price filter.","key":"minPrice","value":"6039.208844241599"},{"description":"Optional maximum price filter.","key":"maxPrice","value":"6039.208844241599"},{"description":"Optional minimum quantity filter.","key":"minQty","value":"6997"},{"description":"Optional maximum quantity filter.","key":"maxQty","value":"6997"},{"description":"Optional field to sort by: Details.ProductName, Details.Sku, Pricing.Price, Availability.Qty.","key":"sortBy","value":"Details.ProductName"},{"description":"Optional whether to sort descending (default: false).","key":"sortDescending","value":"false"},{"description":"Page number for pagination (default: 1).","key":"page","value":"1"},{"description":"Number of items per page (default: 50).","key":"pageSize","value":"50"},{"description":"Language for text fields: \"ar\" (Arabic, default) or \"en\" (English).","key":"lang","value":"ar"}]}},"status":"Service Unavailable","code":503,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"7d37b92a-9b42-4e36-bea8-c431a767922e"},{"name":"Get Delivery Time Slots","id":"08484a03-cca2-4749-b70b-f6d5a8bc26e4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://eservicespre.hoicom.net/api/v0/gifts/delivery/fc/:fulfillmentCenterId/timeslots/:date","description":"Returns the delivery time slots a fulfillment center can serve on a given date. The slot id returned here is what you pass in delivery.slotId when creating an order.
Call this after choosing products, to confirm the recipient can receive the gift on the intended date.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Gifts service.
\nOn success code is 1000 and data holds the date and its available slots, each with an id and a human-readable name (time window). See the example below.
The fulfillment center identifier.
\n","type":"text/plain"},"type":"any","value":"string","key":"fulfillmentCenterId"},{"description":{"content":"The delivery date to check availability for.
\n","type":"text/plain"},"type":"any","value":"1960-01-01","key":"date"}]}},"response":[{"id":"0fdfbf51-7db6-44c5-a2f6-ec879c4662c7","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/delivery/fc/:fulfillmentCenterId/timeslots/:date","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","delivery","fc",":fulfillmentCenterId","timeslots",":date"],"variable":[{"key":"fulfillmentCenterId","value":"string","description":"The fulfillment center identifier."},{"key":"date","value":"1960-01-01","description":"The delivery date to check availability for."}]},"description":"Returns the delivery **time slots** a fulfillment center can serve on a given date. The slot `id` returned here is what you pass in `delivery.slotId` when creating an order.\n\nCall this after choosing products, to confirm the recipient can receive the gift on the intended date.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Gifts service.\n\n---\n\n## Path Parameters\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `fulfillmentCenterId` | `string` | Yes | The fulfillment center to check availability for. |\n| `date` | `string` (date) | Yes | The delivery date to check, in `YYYY-MM-DD` format. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` holds the date and its available slots, each with an `id` and a human-readable `name` (time window). See the example below."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"deliveryDate\": \"2026-07-10\",\n \"slots\": [\n {\n \"id\": \"slot_morning\",\n \"name\": \"09:00 - 12:00\"\n },\n {\n \"id\": \"slot_evening\",\n \"name\": \"16:00 - 19:00\"\n }\n ]\n }\n}"},{"id":"f60d0b5b-fca6-4c13-adef-9d58fa3af3b7","name":"Internal Server Error","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/delivery/fc/:fulfillmentCenterId/timeslots/:date","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","delivery","fc",":fulfillmentCenterId","timeslots",":date"],"variable":[{"key":"fulfillmentCenterId","value":"string","description":"The fulfillment center identifier."},{"key":"date","value":"1960-01-01","description":"The delivery date to check availability for."}]}},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""},{"id":"26a603d9-9040-4126-80c4-091372d7efa5","name":"Service Unavailable","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/delivery/fc/:fulfillmentCenterId/timeslots/:date","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","delivery","fc",":fulfillmentCenterId","timeslots",":date"],"variable":[{"key":"fulfillmentCenterId","value":"string","description":"The fulfillment center identifier."},{"key":"date","value":"1960-01-01","description":"The delivery date to check availability for."}]}},"status":"Service Unavailable","code":503,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"08484a03-cca2-4749-b70b-f6d5a8bc26e4"},{"name":"Create Order","id":"3ad4724d-9abd-4b88-aae6-d22dc0847d6a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"externalReference\": \"string\",\n \"recipient\": {\n \"name\": \"string\",\n \"phone\": \"string\",\n \"fulfillmentCenterId\": \"string\"\n },\n \"sender\": {\n \"name\": \"string\",\n \"email\": \"string\",\n \"phone\": \"string\",\n \"countryCode\": \"string\"\n },\n \"items\": [\n {\n \"productId\": \"string\",\n \"quantity\": 2035\n },\n {\n \"productId\": \"string\",\n \"quantity\": 141\n }\n ],\n \"delivery\": {\n \"slotId\": \"string\",\n \"deliveryDate\": \"1967-09-20T22:20:15.581Z\"\n },\n \"cardMessage\": {\n \"from\": \"string\",\n \"to\": \"string\",\n \"message\": \"string\",\n \"cardType\": \"string\"\n },\n \"amount\": 712.2471014755782,\n \"currency\": \"string\"\n}","options":{"raw":{"headerFamily":"json","language":"json"}}},"url":"https://eservicespre.hoicom.net/api/v0/gifts/orders/async","description":"Submits a gift order for asynchronous processing. The request returns immediately once accepted; the order is then processed in the background and moves through the fulfillment stages described in the folder overview. Poll Get Order by ID to track progress.
\nOrders are idempotent on externalReference — reusing a reference that has already been processed will not create a duplicate order.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Gifts service.
\nOn acceptance code is 1000 and data contains the transactionId used to track the order. See the example below.
Returns a single gift order by its transaction id, including its overall status and detailed processingStage (see the folder overview for the stage lifecycle). Use this to poll an order after creating it.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Gifts service.
\nOn success code is 1000 and data holds the order — status, processing stage, timestamps, recipient, sender, delivery, and amounts. Products and card messages are included only when the matching include flag is true. If the order is not found the response carries 1105. See the example below.
Include product details in the response (default: false).
\n","type":"text/plain"},"key":"includeProducts","value":"false"},{"description":{"content":"Include card messages in the response (default: false).
\n","type":"text/plain"},"key":"includeCardMessages","value":"false"}],"variable":[{"description":{"content":"The unique identifier of the gift order transaction.
\n","type":"text/plain"},"type":"any","value":"string","key":"id"}]}},"response":[{"id":"a65bf598-aee9-4ca8-b3c0-c77222e3e702","name":"OK","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"text/plain"}],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/orders/:id?includeProducts=false&includeCardMessages=false","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","orders",":id"],"query":[{"description":"Include product details in the response (default: false).","key":"includeProducts","value":"false"},{"description":"Include card messages in the response (default: false).","key":"includeCardMessages","value":"false"}],"variable":[{"key":"id","value":"string","description":"The unique identifier of the gift order transaction."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"transactionId\": \"gift_txn_8f3a2b7c\",\n \"externalReference\": \"client-ref-1001\",\n \"status\": \"Completed\",\n \"processingStage\": \"Delivered\",\n \"timestamp\": {\n \"requestedAt\": \"2026-07-01T09:30:00Z\",\n \"completedAt\": \"2026-07-02T14:05:00Z\"\n },\n \"recipient\": {\n \"name\": \"Sara Al-Ahmad\",\n \"phone\": \"+966500000000\"\n },\n \"sender\": {\n \"name\": \"Omar Khan\",\n \"email\": \"omar@example.com\",\n \"phone\": \"+966511111111\"\n },\n \"delivery\": {\n \"deliveryTimeSlot\": \"09:00 - 12:00\",\n \"deliveryDate\": \"2026-07-02T00:00:00Z\",\n \"requestedDeliveryDate\": \"2026-07-02T00:00:00Z\",\n \"actualDeliveryDate\": \"2026-07-02T11:15:00Z\",\n \"fulfillmentCenter\": {\n \"id\": \"fc_riyadh_01\",\n \"name\": \"Riyadh Central\",\n \"city\": \"Riyadh\",\n \"countryCode\": \"SA\"\n }\n },\n \"amounts\": {\n \"requestedAmount\": {\n \"amount\": 228.85,\n \"currency\": \"SAR\"\n },\n \"finalAmount\": {\n \"amount\": 228.85,\n \"currency\": \"SAR\"\n },\n \"pricing\": {\n \"subTotal\": 199,\n \"vatAmount\": 29.85,\n \"vatPercentage\": 15,\n \"deliveryCost\": 0,\n \"discount\": 0,\n \"currency\": \"SAR\"\n }\n }\n }\n}"},{"id":"61acd115-8b0d-4624-9b2d-0fe3e8c354b6","name":"Internal Server Error","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/orders/:id?includeProducts=false&includeCardMessages=false","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","orders",":id"],"query":[{"description":"Include product details in the response (default: false).","key":"includeProducts","value":"false"},{"description":"Include card messages in the response (default: false).","key":"includeCardMessages","value":"false"}],"variable":[{"key":"id","value":"string","description":"The unique identifier of the gift order transaction."}]}},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""},{"id":"b1b67ce8-6710-431e-bdc7-fd22eb55c16f","name":"Service Unavailable","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/orders/:id?includeProducts=false&includeCardMessages=false","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","orders",":id"],"query":[{"description":"Include product details in the response (default: false).","key":"includeProducts","value":"false"},{"description":"Include card messages in the response (default: false).","key":"includeCardMessages","value":"false"}],"variable":[{"key":"id","value":"string","description":"The unique identifier of the gift order transaction."}]}},"status":"Service Unavailable","code":503,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"504fe16d-809a-4665-9977-6f345245964e"},{"name":"Get Order Products","id":"45d16dd2-ef31-4f1f-80ac-52048f9a796a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://eservicespre.hoicom.net/api/v0/gifts/orders/:id/products","description":"Returns just the products belonging to a gift order. Equivalent to calling Get Order by ID with includeProducts=true and reading only the products.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Gifts service.
\nOn success code is 1000 and data holds the order's transactionId and its list of products (details, quantity, pricing). See the example below.
The unique identifier of the gift order transaction.
\n","type":"text/plain"},"type":"any","value":"string","key":"id"}]}},"response":[{"id":"3b5b9656-3b28-4d44-b230-30019c88380f","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/orders/:id/products","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","orders",":id","products"],"variable":[{"key":"id","value":"string","description":"The unique identifier of the gift order transaction."}]},"description":"Returns just the **products** belonging to a gift order. Equivalent to calling **Get Order by ID** with `includeProducts=true` and reading only the products.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Gifts service.\n\n---\n\n## Path Parameters\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `id` | `string` | Yes | The gift order transaction identifier. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` holds the order's `transactionId` and its list of products (details, quantity, pricing). See the example below."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"transactionId\": \"gift_txn_8f3a2b7c\",\n \"products\": [\n {\n \"id\": \"prod_10021\",\n \"details\": {\n \"name\": \"Red Roses Bouquet\",\n \"nameAr\": \"باقة ورد أحمر\",\n \"mainImage\": \"https://cdn.example.com/products/roses-red.jpg\",\n \"sku\": \"FLW-ROSE-RED-12\"\n },\n \"quantity\": 1,\n \"pricing\": {\n \"currency\": \"SAR\",\n \"unitPrice\": 199,\n \"totalPrice\": 199,\n \"vat\": 29.85\n }\n }\n ]\n }\n}"},{"id":"c2765b3d-74fe-42db-909f-1826b85e10fc","name":"Internal Server Error","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/orders/:id/products","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","orders",":id","products"],"variable":[{"key":"id","value":"string","description":"The unique identifier of the gift order transaction."}]}},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""},{"id":"1e9e3c4a-433b-4682-97ea-6f608b347c54","name":"Service Unavailable","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/orders/:id/products","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","orders",":id","products"],"variable":[{"key":"id","value":"string","description":"The unique identifier of the gift order transaction."}]}},"status":"Service Unavailable","code":503,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"45d16dd2-ef31-4f1f-80ac-52048f9a796a"},{"name":"Get Order Card Messages","id":"ea378616-0852-4440-8beb-e87508e4921e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://eservicespre.hoicom.net/api/v0/gifts/orders/:id/card-messages","description":"Returns just the card / gift messages attached to a gift order. Equivalent to calling Get Order by ID with includeCardMessages=true and reading only the card messages.
Requires Basic Authentication with your client credentials. Your account must be enabled for the Gifts service.
\nOn success code is 1000 and data holds the order's transactionId and its list of card messages (from, to, message, cardType). See the example below.
The unique identifier of the gift order transaction.
\n","type":"text/plain"},"type":"any","value":"string","key":"id"}]}},"response":[{"id":"77d08a3a-f8bf-4c78-a994-a2211d0aa191","name":"OK","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/orders/:id/card-messages","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","orders",":id","card-messages"],"variable":[{"key":"id","value":"string","description":"The unique identifier of the gift order transaction."}]},"description":"Returns just the **card / gift messages** attached to a gift order. Equivalent to calling **Get Order by ID** with `includeCardMessages=true` and reading only the card messages.\n\n---\n\n## Authorization\n\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Gifts service.\n\n---\n\n## Path Parameters\n\n| Parameter | Type | Required | Description |\n| --- | --- | --- | --- |\n| `id` | `string` | Yes | The gift order transaction identifier. |\n\n---\n\n## Response\n\nOn success `code` is `1000` and `data` holds the order's `transactionId` and its list of card messages (`from`, `to`, `message`, `cardType`). See the example below."},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"transactionId\": \"gift_txn_8f3a2b7c\",\n \"cardMessages\": [\n {\n \"from\": \"Omar\",\n \"to\": \"Sara\",\n \"message\": \"Happy Birthday!\",\n \"cardType\": \"Birthday\"\n }\n ]\n }\n}"},{"id":"a668c31a-68c4-4869-921a-f1834ace7408","name":"Internal Server Error","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/orders/:id/card-messages","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","orders",":id","card-messages"],"variable":[{"key":"id","value":"string","description":"The unique identifier of the gift order transaction."}]}},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""},{"id":"1b198d97-6bb6-41c6-b026-a20e4da4c503","name":"Service Unavailable","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/orders/:id/card-messages","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","orders",":id","card-messages"],"variable":[{"key":"id","value":"string","description":"The unique identifier of the gift order transaction."}]}},"status":"Service Unavailable","code":503,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"ea378616-0852-4440-8beb-e87508e4921e"},{"name":"Get Orders","id":"e5dc07e1-57f7-4abe-b84a-80325961cc82","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"text/plain"}],"url":"https://eservicespre.hoicom.net/api/v0/gifts/orders?transactionId=string&externalReference=string&status=string&fromDate=2024-09-26T09:33:32.577Z&toDate=2024-09-26T09:33:32.577Z&page=1&pageSize=50&includeProducts=false&includeCardMessages=false","description":"Returns a paginated, filterable list of gift orders for your account. Use it to look up orders by transaction id, external reference, status, or date range.
\nRequires Basic Authentication with your client credentials. Your account must be enabled for the Gifts service.
\nOn success code is 1000 and data holds a paginated list of orders. Valid status values: Submitted, Pending, Completed, Failed, Cancelled. See the example below.
Optional transaction ID to filter by.
\n","type":"text/plain"},"key":"transactionId","value":"string"},{"description":{"content":"Optional external reference to filter by.
\n","type":"text/plain"},"key":"externalReference","value":"string"},{"description":{"content":"Optional transaction status to filter by (enum name, e.g. \"Completed\").
\n","type":"text/plain"},"key":"status","value":"string"},{"description":{"content":"Optional start date for filtering.
\n","type":"text/plain"},"key":"fromDate","value":"2024-09-26T09:33:32.577Z"},{"description":{"content":"Optional end date for filtering.
\n","type":"text/plain"},"key":"toDate","value":"2024-09-26T09:33:32.577Z"},{"description":{"content":"Page number for pagination (default: 1).
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"Number of items per page (default: 50).
\n","type":"text/plain"},"key":"pageSize","value":"50"},{"description":{"content":"Include product details in the response (default: false).
\n","type":"text/plain"},"key":"includeProducts","value":"false"},{"description":{"content":"Include card messages in the response (default: false).
\n","type":"text/plain"},"key":"includeCardMessages","value":"false"}],"variable":[]}},"response":[{"id":"477c62bb-2ddd-4662-9eae-d0acc4f43851","name":"OK","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"text/plain"}],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/orders?transactionId=string&externalReference=string&status=string&fromDate=2024-09-26T09:33:32.577Z&toDate=2024-09-26T09:33:32.577Z&page=1&pageSize=50&includeProducts=false&includeCardMessages=false","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","orders"],"query":[{"description":"Optional transaction ID to filter by.","key":"transactionId","value":"string"},{"description":"Optional external reference to filter by.","key":"externalReference","value":"string"},{"description":"Optional transaction status to filter by (enum name, e.g. \"Completed\").","key":"status","value":"string"},{"description":"Optional start date for filtering.","key":"fromDate","value":"2024-09-26T09:33:32.577Z"},{"description":"Optional end date for filtering.","key":"toDate","value":"2024-09-26T09:33:32.577Z"},{"description":"Page number for pagination (default: 1).","key":"page","value":"1"},{"description":"Number of items per page (default: 50).","key":"pageSize","value":"50"},{"description":"Include product details in the response (default: false).","key":"includeProducts","value":"false"},{"description":"Include card messages in the response (default: false).","key":"includeCardMessages","value":"false"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"code\": 1000,\n \"message\": \"Success\",\n \"data\": {\n \"items\": [\n {\n \"transactionId\": \"gift_txn_8f3a2b7c\",\n \"externalReference\": \"client-ref-1001\",\n \"status\": \"Completed\",\n \"processingStage\": \"Delivered\",\n \"timestamp\": {\n \"requestedAt\": \"2026-07-01T09:30:00Z\",\n \"completedAt\": \"2026-07-02T14:05:00Z\"\n },\n \"recipient\": {\n \"name\": \"Sara Al-Ahmad\",\n \"phone\": \"+966500000000\"\n },\n \"sender\": {\n \"name\": \"Omar Khan\",\n \"email\": \"omar@example.com\",\n \"phone\": \"+966511111111\"\n },\n \"delivery\": {\n \"deliveryTimeSlot\": \"09:00 - 12:00\",\n \"deliveryDate\": \"2026-07-02T00:00:00Z\",\n \"requestedDeliveryDate\": \"2026-07-02T00:00:00Z\",\n \"actualDeliveryDate\": \"2026-07-02T11:15:00Z\",\n \"fulfillmentCenter\": {\n \"id\": \"fc_riyadh_01\",\n \"name\": \"Riyadh Central\",\n \"city\": \"Riyadh\",\n \"countryCode\": \"SA\"\n }\n },\n \"amounts\": {\n \"requestedAmount\": {\n \"amount\": 228.85,\n \"currency\": \"SAR\"\n },\n \"finalAmount\": {\n \"amount\": 228.85,\n \"currency\": \"SAR\"\n },\n \"pricing\": {\n \"subTotal\": 199,\n \"vatAmount\": 29.85,\n \"vatPercentage\": 15,\n \"deliveryCost\": 0,\n \"discount\": 0,\n \"currency\": \"SAR\"\n }\n }\n }\n ],\n \"count\": 1,\n \"page\": 1,\n \"pageSize\": 50,\n \"totalPages\": 1,\n \"totalItems\": 1\n }\n}"},{"id":"8c0b81ae-e137-46c2-8635-da6ea42f9452","name":"Internal Server Error","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/orders?transactionId=string&externalReference=string&status=string&fromDate=2024-09-26T09:33:32.577Z&toDate=2024-09-26T09:33:32.577Z&page=1&pageSize=50&includeProducts=false&includeCardMessages=false","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","orders"],"query":[{"description":"Optional transaction ID to filter by.","key":"transactionId","value":"string"},{"description":"Optional external reference to filter by.","key":"externalReference","value":"string"},{"description":"Optional transaction status to filter by (enum name, e.g. \"Completed\").","key":"status","value":"string"},{"description":"Optional start date for filtering.","key":"fromDate","value":"2024-09-26T09:33:32.577Z"},{"description":"Optional end date for filtering.","key":"toDate","value":"2024-09-26T09:33:32.577Z"},{"description":"Page number for pagination (default: 1).","key":"page","value":"1"},{"description":"Number of items per page (default: 50).","key":"pageSize","value":"50"},{"description":"Include product details in the response (default: false).","key":"includeProducts","value":"false"},{"description":"Include card messages in the response (default: false).","key":"includeCardMessages","value":"false"}]}},"status":"Internal Server Error","code":500,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""},{"id":"4b496f94-6768-4da4-a80c-b23a25fd5b57","name":"Service Unavailable","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://eservicespre.hoicom.net/api/v0/gifts/orders?transactionId=string&externalReference=string&status=string&fromDate=2024-09-26T09:33:32.577Z&toDate=2024-09-26T09:33:32.577Z&page=1&pageSize=50&includeProducts=false&includeCardMessages=false","host":["https://eservicespre.hoicom.net"],"path":["api","v0","gifts","orders"],"query":[{"description":"Optional transaction ID to filter by.","key":"transactionId","value":"string"},{"description":"Optional external reference to filter by.","key":"externalReference","value":"string"},{"description":"Optional transaction status to filter by (enum name, e.g. \"Completed\").","key":"status","value":"string"},{"description":"Optional start date for filtering.","key":"fromDate","value":"2024-09-26T09:33:32.577Z"},{"description":"Optional end date for filtering.","key":"toDate","value":"2024-09-26T09:33:32.577Z"},{"description":"Page number for pagination (default: 1).","key":"page","value":"1"},{"description":"Number of items per page (default: 50).","key":"pageSize","value":"50"},{"description":"Include product details in the response (default: false).","key":"includeProducts","value":"false"},{"description":"Include card messages in the response (default: false).","key":"includeCardMessages","value":"false"}]}},"status":"Service Unavailable","code":503,"_postman_previewlanguage":"text","header":[],"cookie":[],"responseTime":null,"body":""}],"_postman_id":"e5dc07e1-57f7-4abe-b84a-80325961cc82"}],"id":"929999d6-c4ee-4663-9e8d-79bb2ffaefb2","description":"The Gifts service enables ordering and delivering physical gift products (flowers, chocolates, gift baskets, etc.) to recipients. It covers the full lifecycle — from browsing available products and locations, to placing orders and tracking their fulfillment status.
\nA gift order follows this flow:
\nBrowse locations — get available locations with fulfillment centers
\nBrowse products — search and filter products by fulfillment center
\nCheck delivery slots — get available time slots for the chosen date and fulfillment center
\nPlace order — submit an asynchronous order with recipient, delivery, and product details
\nTrack order — poll the order status and processing stage until fulfillment
\nThe processingStage field provides detailed fulfillment progress, independent of the overall status. It tracks the physical journey of the order:
OrderSubmitted → OrderConfirmed → PreparingOrder → OutForDelivery → Delivered\n\nOrder responses can include additional detail via query parameters:
\nThese apply to both single order (GET /orders/{id}) and order list (GET /orders) endpoints. Products and card messages are also available as dedicated sub-endpoints:
GET /orders/{id}/products
GET /orders/{id}/card-messages