Product API Documentation

advanced By Vardast Team

Summary of Requirements

Method: GET
Path: /api/v1/products
Authentication: X-API-Key header
Response Format: application/json
Base Response Structure: {"result": {"products": [...]}}
Character Encoding: UTF-8

1. Authentication

To restrict access, define an access key:

X-API-Key: <YOUR_API_KEY>

If no key is provided, the API can work without authentication; however, it's recommended to always use a key.

2. API Endpoint

Our service requires a GET endpoint that returns a list of products.

Sample URL:

https://your-domain.com/api/v1/products

3. Response Structure

Success Status: 200 OK

The response body must have an object with a result key containing a products array. We recommend also returning a pagination object.

{
  "result": {
    "products": [
      {
        "id": 123,
        "name": "Product Name",
        "url": "/product/sample-product",
        "product_categories": [
          { "name": "Category 1" },
          { "name": "Category 2" }
        ],
        "product_attributes": [
          {
            "name": "description",
            "value": "Product description as HTML or text"
          }
        ],
        "product_variants": [
          {
            "stock_number": 10,
            "price": 250000,
            "product_attributes": [
              { "name": "color", "value": "red" },
              { "name": "size", "value": "L" }
            ]
          },
          {
            "stock_number": 5,
            "price": 260000,
            "product_attributes": [
              { "name": "color", "value": "blue" },
              { "name": "size", "value": "M" }
            ]
          }
        ]
      }
    ]
  }
}

4. Important Field Compatibility Notes

Required Fields:

id: Unique product identifier (required - must be an integer)
name: Product name (required)
url: Must be relative (e.g., /product/123). We will add it to your website's main domain (required)
product_variants: Array of variants. Each variant includes:

stock_number: Integer (inventory). Variants with stock_number <= 0 are ignored.

price: Integer (price) or string "unavailable". If price = "unavailable", that variant is ignored.

product_attributes: Array of { name, value } (such as color, size, warranty, etc.)

Note: If a product has no valid variants (or no variants at all), it will be removed from our system.

Optional Fields:

product_categories: Array of objects with at least a name field. Can be an empty array.
product_attributes: Array of objects with { name, value } structure, to include the description of that product.

For descriptions, make sure to return an item with name = "description". The value can be HTML. We will convert it to text. Note: Currently, only the description object is accepted. Any other objects in product_attributes are ignored and will not be added to the product information.

5. Aggregation and Validation Rules on Our Side

If a product has only one variant and that variant is valid (stock_number > 0 and price != "unavailable"), we consider it a "simple" product and directly store the price and stock for the product itself.
If a product has multiple variants:
Invalid variants are removed.
Valid variants are grouped based on their attribute sets (e.g., {color: red, size: L}) and inventories of variants with the same attributes are summed together.
If no valid variant groups remain after filtering, the product is discarded.

6. Error Statuses

401 Unauthorized: If the access key is not sent or is incorrect.
429 Too Many Requests: If the rate limit is exceeded.
500 Internal Server Error: Unexpected error on your side.

7. Quick Test Sample with cURL

  -H "Accept: application/json" \
  -H "X-API-Key: YOUR_API_KEY"

8. Final Checklist for You

[ ] Implement GET /api/v1/products endpoint
[ ] Return response in {"result": {"products": [...]}} format
[ ] For each product, have the keys: id, name, url, product_categories, product_attributes, product_variants
[ ] In product_attributes, have an item with name = "description" (HTML is allowed)
[ ] Variants include stock_number, price, and product_attributes
[ ] Remove variants with stock_number <= 0 or price = "unavailable" from the response (or don't send them at all)
[ ] Authentication with X-API-Key is active
[ ] Error status codes and error format are defined

9. Adding Website to Vardast Platform

Select "Other" as the website type
Enter your website address
In the token section, enter your access key

10. Product Examples

10.1 Simple Product with One Valid Variant

{
  "result": {
    "products": [
      {
        "id": 501,
        "name": "Plain T-Shirt",
        "url": "/p/tshirt-plain",
        "product_categories": [{ "name": "Clothing" }],
        "product_attributes": [
          {
            "name": "description",
            "value": "<p>High-quality cotton t-shirt</p>"
          },
          { "name": "brand", "value": "ACME" }
        ],
        "product_variants": [
          {
            "stock_number": 15,
            "price": 249000,
            "product_attributes": [{ "name": "size", "value": "M" }]
          }
        ]
      }
    ]
  }
}

10.2 Multi-Variant Product with Attribute Grouping

{
  "result": {
    "products": [
      {
        "id": 777,
        "name": "Running Shoes",
        "url": "/p/run-shoe",
        "product_categories": [{ "name": "Shoes" }, { "name": "Sports" }],
        "product_attributes": [
          {
            "name": "description",
            "value": "<p>Suitable for daily running</p>"
          }
        ],
        "product_variants": [
          {
            "stock_number": 5,
            "price": 1899000,
            "product_attributes": [
              { "name": "color", "value": "black" },
              { "name": "size", "value": 42 }
            ]
          },
          {
            "stock_number": 2,
            "price": 1899000,
            "product_attributes": [
              { "name": "color", "value": "black" },
              { "name": "size", "value": 42 }
            ]
          },
          {
            "stock_number": 0,
            "price": 1899000,
            "product_attributes": [
              { "name": "color", "value": "black" },
              { "name": "size", "value": 43 }
            ]
          },
          {
            "stock_number": 3,
            "price": "unavailable",
            "product_attributes": [
              { "name": "color", "value": "blue" },
              { "name": "size", "value": 42 }
            ]
          }
        ]
      }
    ]
  }
}

In the example above, only variants (black, 42) are valid and their inventories are summed (=7). Other variants are removed.

10.3 Product with No Valid Variants (Will be Removed)

{
  "result": {
    "products": [
      {
        "id": 888,
        "name": "Headphones",
        "url": "/p/headphone",
        "product_categories": [{ "name": "Audio" }],
        "product_attributes": [
          { "name": "description", "value": "<p>Strong bass sound</p>" }
        ],
        "product_variants": [
          {
            "stock_number": 0,
            "price": 990000,
            "product_attributes": [{ "name": "color", "value": "black" }]
          },
          {
            "stock_number": 1,
            "price": "unavailable",
            "product_attributes": [{ "name": "color", "value": "black" }]
          }
        ]
      }
    ]
  }
}

In this case, no valid variants exist; this product will be discarded.