Product Data API Guide #

The Product Data API allows you to send, update, and manage product catalog data with Replenit. This guide outlines the available endpoints, payload structures, and best practices for integration.

Overview #

The API enables you to manage product catalog data, such as product details, variants, and pricing, ensuring accurate replenishment reminders and analytics. The Offline Exclusive field specifies that a product is exclusively available through physical retail channels and has no online purchase options.

Base URL #

https://services.replen.it

Authorization #

All routes require an Access Token with the correct permission level in the Authorization header. You can access your client ID and Access Token details in the platform under the Data Health and Management section.

Endpoints #

Method	Endpoint	Description
POST	`/products/{clientId}/many`	Inserts new product data in bulk.
POST	`/products/{clientId}`	Inserts a single product.
PUT	`/products/{clientId}/many`	Updates existing product data in bulk.
PUT	`/products/{clientId}`	Updates a single product.
DELETE	`/products/{clientId}`	Deletes product data.
GET	`/products/{clientId}?productId={productId}</code >`	Retrieves details of a product by its ID.

Field Descriptions #

Product (Object) #

Field	Type	Mandatory	Description
`productId`	String	Yes	Unique identifier for the product.
`taxonomy`	Array	No	Category taxonomy for the product.
`isOfflineExclusive`	Boolean	No	Indicates if the product is exclusively available offline.

Variants (Array) #

Field	Type	Mandatory	Description
`variantId`	String	Yes	Unique identifier for the variant.
`sku`	String	Yes	Stock Keeping Unit for the variant.
`productName`	String	Yes	Name of the product variant.
`productUrl`	String	No	URL of the product variant.
`productImage`	String	Yes	Image URL of the product variant.
`productBrand`	String	No	Brand of the product variant.
`productColor`	String	No	Color of the product variant.
`productSize`	String	No	Size of the product variant (e.g., “100ml”).
`description`	String	No	Description of the product variant.
`isAvailable`	Boolean	Yes	Indicates if the product variant is currently available.
`stockQuantity`	Number	No	Current stock quantity of the product variant.
`language`	String	Yes	Language for the product variant (e.g., “US_en”).

Price (Object) #

Field	Type	Mandatory	Description
`productOriginalPrice`	Float	Yes	Original price of the product variant.
`productSalePrice`	Float	Yes	Sale price of the product variant.
`currency`	String	Yes	Currency code for the product prices (e.g., “USD”).

Sample Payloads #

1. Bulk Product Ingest

Endpoint: /products/{clientId}/many


  [
    {
      "productId": "P123456",
      "taxonomy": ["Beauty", "Fragrances"],
      "isOfflineExclusive": true,
      "variants": [
        {
          "variantId": "V123456",
          "sku": "SKU123456",
          "productName": "Perfume 100ml",
          "productUrl": "https://example.com/perfume-100ml",
          "productImage": "https://example.com/images/perfume-100ml.jpg",
          "productBrand": "BrandName",
          "productColor": "Clear",
          "productSize": "100ml",
          "description": "A premium fragrance.",
          "isAvailable": true,
          "stockQuantity": 50,
          "language": "US_en",
          "price": {
            "productOriginalPrice": 150.00,
            "productSalePrice": 120.00,
            "currency": "USD"
          }
        }
      ]
    }
  ]

2. Single Product Ingest

Endpoint: /products/{clientId}


  {
    "productId": "P123457",
      "taxonomy": ["Beauty", "Skincare"],
        "isOfflineExclusive": false,
         "variants": [
      {
        "variantId": "V123457",
          "sku": "SKU123457",
            "productName": "Lotion 200ml",
              "productUrl": "https://example.com/lotion-200ml",
                "productImage": "https://example.com/images/lotion-200ml.jpg",
                   "productBrand": "BrandName",
                     "productColor": "White",
                      "productSize": "200ml",
                        "description": "A hydrating lotion.",
                           "isAvailable": true,
                             "stockQuantity": 100,
                              "language": "US_en",
        "price": {
          "productOriginalPrice": 50.00,
            "productSalePrice": 45.00,
              "currency": "USD"
        }
      }
    ]
  }

3. Bulk Product Update

Endpoint: /products/{clientId}/many


  [
    {
      "productId":  "P123456",
        "taxonomy":  ["Beauty", "Fragrances"],
          "isOfflineExclusive":  true,
            "variants": [
        {
           "variantId": "V123456",
           "sku": "SKU123456",
           "productName":  "Perfume 100ml - Updated",
           "productUrl":  "https://example.com/perfume-100ml",
           "productImage":  "https://example.com/images/perfume-100ml.jpg",
           "productBrand":  "BrandName",
           "productColor":  "Clear",
           "productSize":  "100ml",
           "description":  "A premium fragrance with an updated description.",
           "isAvailable":  true,
           "stockQuantity":  45,
           "language":  "US_en",
          "price": {
             "productOriginalPrice":  150.00,
             "productSalePrice":  130.00,
             "currency":  "USD"
          }
        }
      ]
    }
  ]

4. Product Delete

Endpoint: /products/{clientId}


  {
     "productId": "P123456",
      "variants": [
      {
        "sku": "SKU123456"
      }
    ]
  }

5. Check Product Existence

Endpoint:
/products/{clientId}?productId={productId}


  {
    "productId": "P123456",
     "taxonomy": ["Beauty", "Fragrances"],
      "isOfflineExclusive": true,
    "variants": [
      {
        "variantId": "V123456",
        "sku": "SKU123456",
        "productName": "Perfume 100ml",
         "productUrl": "https://example.com/perfume-100ml",
           "productImage": "https://example.com/images/perfume-100ml.jpg",
            "productBrand": "BrandName",
               "productColor": "Clear",
                 "productSize": "100ml",
                   "isAvailable": true,
                     "stockQuantity": 50,
                       "language": "US_en",
       "price": {
           "productOriginalPrice": 150.00,
             "productSalePrice": 120.00,
               "currency": "USD"
        }
      }
    ]
  }

This endpoint can also help determine the appropriate method (POST or PUT) to use when managing roduct data in Replenit.

Retry Mechanism #

For all API operations, implement a retry mechanism to handle transient failures, such as network interruptions or server errors (e.g., HTTP 500). Use an exponential backoff strategy with a maximum of 5 retries.

Example Retry Logic:

Retry after 1 second for the first failure.
Double the retry delay (2, 4, 8 seconds) for subsequent failures.
Stop retries after 5 attempts or upon a successful request.

Ensure Complete Product Data #

Whenever product data is added or updated, ensure all relevant fields (both mandatory and optional) are passed in the payload. Missing fields may result in incomplete or incorrect data processing.

For example, always include:

productId, sku, productName, productImage, and isAvailable.
Price details like productOriginalPrice, productSalePrice, and currency.

This ensures seamless integration and avoids errors in downstream processes.

Error Handling #

Error Code	Description
400	Bad Request – Invalid or missing parameters.
401	Unauthorized – Invalid API key or token.
404	Not Found – Product or resource not found.
500	Internal Server Error – Unexpected error.

Best Practices #

Batch Updates: Use the /many endpoints for multiple products to optimize performance.
Validation: Validate input fields (e.g., image URLs, currency codes) before sending requests.
Retry Mechanism: Implement an exponential backoff strategy for retries.
Ensure Data Completeness: Always pass all relevant fields in the payload for accuracy.

Contact and Support #

For any questions or support, please contact the Replenit team at [email protected]

User Guide

Developer Guide

Product Data API Guide