I
IHerb Product Data Api
# iHerb API
Welcome to the **iHerb API**! This API allows you to retrieve a list of products by brand from the iHerb database, get all available brands, or even download a zip file with over 40,000 products (see plans for more details).
## **Endpoints**
### **GET** `/brands/{brandName}/products`
Retrieve a list of products for a specific brand with optional filters.
#### **Path Parameters**
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `brandName` | string | Yes | The name of the brand to search. |
#### **Query Parameters**
| Parameter | Type | Description | Default |
| --- | --- | --- | --- |
| `page` | `int` | Page number for pagination. | 1 |
| `productId` | `long` | Specific product ID to filter results. | null |
| `prohibitedAtCountry` | `bool` | Filter out products that are prohibited in the current country. | null |
| `upcCode` | `string` | Universal Product Code (UPC) to search for a specific product. | null |
| `hasDiscount` | `bool` | Filter products that have a discount available. | null |
| `hasStock` | `bool` | Filter products that are currently in stock. | null |
| `hasNewProductFlag` | `bool` | Filter products marked as new. | null |
| `isTrial` | `bool` | Filter products that are trial samples. | null |
| `isSpecial` | `bool` | Filter products with special flags. | null |
| `minPrice` | `float` | Minimum price for filtering. | null |
| `maxPrice` | `float` | Maximum price for filtering. | null |
| `minShippingWeight` | `float` | Minimum shipping weight for filtering. | null |
| `maxShippingWeight` | `float` | Maximum shipping weight for filtering. | null |
| `minRating` | `float` | Minimum rating value for filtering. | null |
| `minDiscountPercent` | `int` | Minimum percentage discount for filtering. | null |
## **Response Format**
The response is returned in JSON format, containing details about the products.
### **Example Response**
```json
{
"currentPage": 1,
"totalPages": 5,
"products": [
{
"productId": 12345,
"brandName": "iHerb",
"brandNameInHifenCase": "i-herb",
"brandId": "b123",
"outOfStock": false,
"isDiscontinued": false,
"title": "Vitamin D3 5000 IU",
"link": "https://www.iherb.com/vitamin-d3",
"sku": "VITD3-5000",
"formattedPrice": "$19.99",
"isSpecial": false,
"isTrial": false,
"hasNewProductFlag": true,
"productCatalogImage": "https://www.iherb.com/images/vitamin-d3.jpg",
"ratingValue": 4.7,
"reviewCount": 120,
"currencyUsed": "USD",
"countryUsed": "US",
"languageUsed": "en",
"unitsOfMeasureUsed": "oz",
"price": 19.99,
"formattedTrialPrice": null,
"trialPrice": 0.0,
"formattedSpecialPrice": null,
"specialPrice": 0.0,
"discountPercentValue": "10%",
"hasDiscount": true,
"soldPercent": "20%",
"prohibitedAtCountry": false,
"shippingWeight": 0.5,
"packageQuantity": "1 bottle",
"dimensions": {
"height": 5.0,
"length": 2.5,
"width": 2.5,
"weight": 0.5
},
"lastUpdate": "2024-11-20T10:30:00Z",
"allDescription": "This is a high-quality Vitamin D3 supplement...",
"hasAllData": true,
"productImages": [
"https://www.iherb.com/images/vitamin-d3-front.jpg",
"https://www.iherb.com/images/vitamin-d3-back.jpg"
],
"stockLeft": 0,
"bestByApproximately": "2025-08-15",
"upcCode": "123456789012",
"variation": {
"variationType": "Flavor",
"variationDescription": "Orange Flavor"
},
"serving": {
"servingType": "Capsules",
"servingDescription": "1 capsule per serving"
},
"categories": [
"Supplements",
"Vitamins"
],
"supplementFacts": {
"servingSize": "1 capsule",
"servingsPerContainer": "90",
"nutritionalFacts": [
{
"substancy": "Vitamin D3",
"amountPerServing": "5000 IU",
"dailyValuePercent": "1250%"
}
],
"disclaimer": "These statements have not been evaluated by the FDA..."
}
}
]
}
```
## **Response Fields**
| **Field** | **Type** | **Description** |
| --- | --- | --- |
| `currentPage` | `int` | The current page number of the paginated response. |
| `totalPages` | `int` | The total number of pages available. |
| `products` | `List` | A list of products retrieved based on the filters and brand specified. |
| `productId` | `int` | Unique ID of the product. |
| `brandName` | `string` | Name of the brand. |
| `brandNameInHifenCase` | `string` | Brand name formatted in hyphen-case. |
| `brandId` | `string` | Unique ID of the brand. |
| `outOfStock` | `bool` | Indicates if the product is currently out of stock. |
| `isDiscontinued` | `bool` | Indicates if the product has been discontinued. |
| `title` | `string` | Product title. |
| `link` | `string` | URL link to the product page. |
| `sku` | `string` | Stock Keeping Unit (SKU) identifier. |
| `formattedPrice` | `string` | Formatted display price of the product. |
| `isSpecial` | `bool` | Flag indicating if the product is marked as special. |
| `isTrial` | `bool` | Flag indicating if the product is a trial sample. |
| `hasNewProductFlag` | `bool` | Indicates if the product is marked as new. |
| `productCatalogImage` | `string` | URL of the product’s catalog image. |
| `ratingValue` | `float` | Average rating value of the product. |
| `reviewCount` | `int` | Number of reviews for the product. |
| `currencyUsed` | `string` | Currency code used for the product price. |
| `countryUsed` | `string` | Country code representing the product’s origin or sale location. |
| `languageUsed` | `string` | Language code used for the product’s description. |
| `unitsOfMeasureUsed` | `string` | Unit of measure used for the product. |
| `price` | `float` | Actual product price in float format. |
| `formattedTrialPrice` | `string` | Formatted price if the product is a trial sample. |
| `trialPrice` | `float` | Actual trial price in float format. |
| `formattedSpecialPrice` | `string` | Formatted price if the product is on special offer. |
| `specialPrice` | `float` | Actual special offer price in float format. |
| `discountPercentValue` | `string` | Discount percentage if applicable. |
| `hasDiscount` | `bool` | Indicates if the product has a discount. |
| `soldPercent` | `string` | Percentage of stock sold. |
| `prohibitedAtCountry` | `bool` | Indicates if the product is prohibited in the specified country. |
| `shippingWeight` | `float` | The weight of the product used for shipping calculations. |
| `packageQuantity` | `string` | Quantity description of the package. |
| `dimensions` | `object` | Product’s physical dimensions (height, length, width, weight). |
| `lastUpdate` | `string` | The last update date and time of the product information. |
| `allDescription` | `string` | Full product description text. |
| `hasAllData` | `bool` | Indicates if all detailed product data is included. |
| `productImages` | `List` | List of URLs for the product’s images. |
| `stockLeft` | `int` | Amount of stock left for the product. Pay attention: if zero it means stock IS available (not tracked individually). |
| `bestByApproximately` | `string` | Approximate best-by date for the product. |
| `upcCode` | `string` | UPC (Universal Product Code) of the product. |
| `variation` | `object` | Information about product variations (e.g., flavor, size). |
| `serving` | `object` | Information about serving size and description. |
| `categories` | `List` | List of categories the product belongs to. |
| `supplementFacts` | `object` | Detailed supplement facts, including serving size and nutritional information. |
### Usage Tips
* Use pagination with the `page` parameter to navigate through large datasets.
* Use the filters provided in the query parameters to get more specific results.
* * *
## Get All Brands
Retrieve a paginated list of all brands available in the iHerb database.
### **GET** `/api/IHerb/brands?page={page}`
### Query Parameters
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `page` | `int` | No | 1 | The page number for paginated results. Use this to navigate through the list of brands. |
### Response Format
```json
{
"currentPage": 1,
"totalPages": 50,
"allBrands": [
"Brand1",
"Brand2",
"Brand3",
"...",
"BrandN"
]
}
```
### Response Fields
| Field | Type | Description |
| --- | --- | --- |
| `currentPage` | `int` | The current page of the results. |
| `totalPages` | `int` | The total number of pages available. |
| `allBrands` | `List<string>` | A list of brand names available in the iHerb database. |
### Usage Tips
* Use the `page` parameter to navigate through the list of brands.
* This endpoint is useful to get a complete overview of all brands available on iHerb.
* * *
## Support
For questions or help, feel free to contact support.