📦Products

💡 Bulk upsert products with variants for a tenant

🚀 TL;DR - Quick Reference

Endpoint: POST /products/{tenantId}

Use When:

Adding new products to catalog
Updating prices or inventory
Syncing product information
Managing product variants (sizes, colors)

Required: ProductId, ProductVariants (can be empty array) Auth: x-replenit-auth-key header Returns: Count of upserted products

Quickest Example:

POST /products/{YOUR_TENANT_ID}
[{
  "ProductId": "P-42",
  "ProductName": "Premium Soap",
  "ProductVariants": []
}]

Jump to Full API Reference ↓

🔗 Endpoint

POST /products/{tenantId}

📋 Parameters

Parameter

Type

Required

Description

tenantId

GUID

✅ Yes

The tenant identifier (must exist)

📨 Request

Body: JSON array of UpsertProductDto objects
Content-Type: application/json

✅ Success Response

Status: 200 OK
Body: Response envelope with data.count

❌ Error Responses

Status

Description

400 Bad Request

Invalid or missing tenant identifier

404 Not Found

Tenant does not exist in our system

500 Internal Server Error

Unexpected server errors

🎯 Identifier Behavior

The product identifier is determined by your tenant's configuration:

Priority Setting

Identifier Used

productid

Product ID

sku

SKU

📝 Note: Configure your identifier priority in the tenant settings

📄 Request Schema

UpsertProductDto Fields

Field

Type

Max Length

Required

Description

ProductId

string

100

✅

Unique product identifier

ProductName

string

200

❌

Product name/title

Taxonomy

string[]

❌

Product categories/tags

IsOfflineExclusive

bool

❌

Available offline only

ProductVariants

UpsertProductVariantDto[]

✅

Product variants (can be empty)

UpsertProductVariantDto Fields

|| Field | Type | Max Length | Required | Description | ||| --------------- | -------- | ---------- | -------- | --------------------------------- | ||| VariantId | string | 100 | ✅ | Unique variant identifier | ||| Sku | string | 200 | ✅ | Variant SKU | || Name | string | 600 | ❌ | Variant name | | Image | string | 2000 | ❌ | Image URL | | Size | string | 50 | ❌ | Size (e.g., "1l", "500ml") | | Stock | int | - | ❌ | Available inventory | | OriginalPrice | double | - | ❌ | Regular price | | SalePrice | double | - | ❌ | Discounted price | | Currency | string | 3 | ❌ | Currency code (ISO 4217) | | IsAvailable | bool | - | ❌ | Availability status | | Language | string | 10 | ❌ | Language code (IETF BCP 47) | | BrandName | string | 200 | ❌ | Brand name | | Url | string | 2000 | ❌ | Product page URL |

💡 Note: Size is automatically parsed into SizeNumeric and SizeMetric on the server

🗑️ DELETE Endpoints

🔗 Delete Product

DELETE /products/{tenantId}/{productId}

📋 Parameters

Parameter

Type

Required

Description

tenantId

GUID

✅ Yes

The tenant identifier

productId

string

✅ Yes

The product ID to delete

✅ Success Response

Status: 200 OK
Body: Response envelope with deleted product ID

{
  "success": true,
  "message": "Product removed.",
  "data": { 
    "productId": "P-42",
    "deletedAt": "2024-12-22T14:02:49Z"
  }
}

🔗 Delete Product Variant

DELETE /products/{tenantId}/variants/{variantId}

📋 Parameters

Parameter

Type

Required

Description

tenantId

GUID

✅ Yes

The tenant identifier

variantId

string

✅ Yes

The variant ID to delete

✅ Success Response

Status: 200 OK
Body: Response envelope with deleted variant ID

{
  "success": true,
  "message": "Variant removed.",
  "data": { 
    "variantId": "V-42",
    "deletedAt": "2024-12-22T14:02:49Z"
  }
}

❌ Error Responses

Delete Product:

|| Status | Scenario | Example Response | || ------ | -------- | ---------------- | || 400 | Missing product ID | {"success": false, "message": "Product ID is required.", "data": {}} | || 404 | Tenant not found | {"success": false, "message": "Tenant not found.", "data": {}} | || 404 | Product not found | {"success": false, "message": "Product not found.", "data": {}} | || 500 | Storage failure | {"success": false, "message": "Failed to delete product.", "data": {}} |

Delete Variant:

|| Status | Scenario | Example Response | || ------ | -------- | ---------------- | || 400 | Missing variant ID | {"success": false, "message": "Variant ID is required.", "data": {}} | || 404 | Tenant not found | {"success": false, "message": "Tenant not found.", "data": {}} | || 404 | Variant not found | {"success": false, "message": "Variant not found.", "data": {}} | || 500 | Storage failure | {"success": false, "message": "Failed to delete variant.", "data": {}} |

Note: The tenant validation is performed automatically by middleware before reaching the endpoint. If tenant doesn't exist, you'll receive a 404 error immediately.

🚀 DELETE Examples

Delete Product - cURL

curl -X DELETE "https://api.replen.it/products/{tenantId}/P-42" \
  -H 'x-replenit-auth-key: YOUR_BASE64_ACCESS_KEY'

Delete Variant - Python

import requests

url = "https://api.replen.it/products/{tenantId}/variants/V-42"
headers = {
    "x-replenit-auth-key": "YOUR_BASE64_ACCESS_KEY"
}

response = requests.delete(url, headers=headers)
print(response.json())

Delete Product - Node.js

const axios = require('axios');

const url = 'https://api.replen.it/products/{tenantId}/P-42';
const headers = {
    'x-replenit-auth-key': 'YOUR_BASE64_ACCESS_KEY'
};

axios.delete(url, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

💡 Real-World Use Cases

Use Case 1: New Product Launch

Scenario: Launching a new product with multiple variants (sizes/colors)

What to send:

[{
  "ProductId": "P-2024-NEW",
  "ProductName": "Winter Collection Sweater",
  "Taxonomy": ["Clothing", "Winter", "Sweaters"],
  "ProductVariants": [
    {
      "VariantId": "P-2024-NEW-RED-S",
      "Sku": "SWEATER-RED-S",
      "Name": "Red Small",
      "Size": "S",
      "Stock": 50,
      "OriginalPrice": 79.99,
      "SalePrice": 79.99,
      "Currency": "USD",
      "IsAvailable": true
    },
    {
      "VariantId": "P-2024-NEW-RED-M",
      "Sku": "SWEATER-RED-M",
      "Name": "Red Medium",
      "Size": "M",
      "Stock": 100,
      "OriginalPrice": 79.99,
      "SalePrice": 79.99,
      "Currency": "USD",
      "IsAvailable": true
    }
  ]
}]

What happens:

✅ Product added to catalog
🎯 Can be used in product recommendation campaigns
📊 Inventory tracked per variant

Use Case 2: Price Update (Sale)

Scenario: Running a limited-time sale on specific products

What to send:

[{
  "ProductId": "P-42",
  "ProductVariants": [{
    "VariantId": "V-42",
    "Sku": "SKU-42",
    "OriginalPrice": 99.99,
    "SalePrice": 79.99,
    "Currency": "USD"
  }]
}]

What happens:

✅ Sale price updated
🎯 Can trigger "price drop" alerts to interested customers
📊 Campaign ROI tracked with new pricing

Use Case 3: Out of Stock

Scenario: Product sold out, update availability

What to send:

[{
  "ProductId": "P-POPULAR",
  "ProductVariants": [{
    "VariantId": "V-POPULAR-L",
    "Sku": "SKU-POPULAR-L",
    "Stock": 0,
    "IsAvailable": false
  }]
}]

What happens:

✅ Product marked as unavailable
🚫 Removed from recommendation engine
📧 Can trigger "back in stock" notification setup

Use Case 4: Multi-Pack Product

Scenario: Product sold in packs (e.g., "4 x 500ml")

What to send:

[{
  "ProductId": "P-PACK",
  "ProductName": "Organic Juice Pack",
  "ProductVariants": [{
    "VariantId": "V-PACK-4X500",
    "Sku": "JUICE-PACK-4X500ML",
    "Name": "4-Pack Orange Juice",
    "Size": "4x500ml",
    "Stock": 25,
    "OriginalPrice": 15.99,
    "Currency": "EUR"
  }]
}]

Smart parsing: System automatically calculates:

SizeNumeric: 2.0 (litres total)
SizeMetric: "l"

📝 Complete Example Request (All Fields)

[
  {
    "ProductId": "P-42",
    "ProductName": "Premium Acme Soap Collection",
    "Taxonomy": ["Personal Care", "Hygiene", "Bath & Body", "Soap"],
    "IsOfflineExclusive": false,
    "ProductVariants": [
      {
        "VariantId": "V-42-RED-L",
        "Sku": "SKU-42-RED-L",
        "Name": "Premium Red Rose Scent - Large",
        "Image": "https://cdn.example.com/products/soap/red-rose-large.jpg",
        "Size": "1l",
        "Stock": 150,
        "OriginalPrice": 29.99,
        "SalePrice": 24.99,
        "Currency": "USD",
        "IsAvailable": true,
        "Language": "en-US",
        "BrandName": "Acme Luxury Collection"
      },
      {
        "VariantId": "V-42-BLUE-M",
        "Sku": "SKU-42-BLUE-M",
        "Name": "Ocean Blue Fresh - Medium",
        "Image": "https://cdn.example.com/products/soap/ocean-blue-medium.jpg",
        "Size": "500ml",
        "Stock": 75,
        "OriginalPrice": 19.99,
        "SalePrice": 14.99,
        "Currency": "USD",
        "IsAvailable": true,
        "Language": "en-US",
        "BrandName": "Acme Luxury Collection"
      },
      {
        "VariantId": "V-42-GREEN-S",
        "Sku": "SKU-42-GREEN-S",
        "Name": "Green Tea Mint - Small",
        "Image": "https://cdn.example.com/products/soap/green-tea-small.jpg",
        "Size": "250ml",
        "Stock": 0,
        "OriginalPrice": 12.99,
        "SalePrice": 12.99,
        "Currency": "USD",
        "IsAvailable": false,
        "Language": "en-US",
        "BrandName": "Acme Luxury Collection"
      }
    ]
  },
  {
    "ProductId": "P-100",
    "ProductName": "Organic Shampoo Bar",
    "Taxonomy": ["Hair Care", "Organic", "Eco-Friendly"],
    "IsOfflineExclusive": true,
    "ProductVariants": [
      {
        "VariantId": "V-100-LAVENDER",
        "Sku": "SKU-100-LAV",
        "Name": "Lavender Dreams",
        "Image": "https://cdn.example.com/products/shampoo/lavender.jpg",
        "Size": "100g",
        "Stock": 50,
        "OriginalPrice": 15.99,
        "SalePrice": 15.99,
        "Currency": "EUR",
        "IsAvailable": true,
        "Language": "en-GB",
        "BrandName": "EcoBeauty"
      }
    ]
  }
]

📝 Minimal Example Request (Required Fields Only)

[
  {
    "ProductId": "P-200",
    "ProductVariants": []
  }
]

📝 Example with Excluded Product

[
  {
    "ProductId": "P-300",
    "Sku": "SKU-300",
    "ProductName": "Discontinued Item",
    "Taxonomy": ["Clearance"],
    "ProductVariants": [
      {
        "VariantId": "V-300",
        "Sku": "SKU-300-LAST",
        "Stock": 5,
        "IsAvailable": false
      }
    ]
  }
]

🚀 cURL Example

curl -sS \
  -X POST "https://api.replen.it/products/{tenantId}" \
  -H 'Content-Type: application/json' \
  -H 'x-replenit-auth-key: YOUR_BASE64_ACCESS_KEY' \
  -d @products.json

🐍 Python Example

import requests
import json

url = "https://api.replen.it/products/{tenantId}"
headers = {
    "Content-Type": "application/json",
    "x-replenit-auth-key": "YOUR_BASE64_ACCESS_KEY"
}

products = [
    {
        "ProductId": "P-42",
        "ProductName": "Acme Soap",
        "Taxonomy": ["Hygiene", "Soap"],
        "ProductVariants": [
            {
                "VariantId": "V-42",
                "Sku": "SKU-42-RED",
                "Name": "Red 1L",
                "Size": "1l",
                "Stock": 10,
                "OriginalPrice": 19.99,
                "SalePrice": 14.99,
                "Currency": "USD",
                "IsAvailable": True
            }
        ]
    }
]

response = requests.post(url, headers=headers, json=products)
print(response.json())

🟢 Node.js Example

const axios = require('axios');

const url = 'https://api.replen.it/products/{tenantId}';
const headers = {
    'Content-Type': 'application/json',
    'x-replenit-auth-key': 'YOUR_BASE64_ACCESS_KEY'
};

const products = [
    {
        ProductId: 'P-42',
        ProductName: 'Acme Soap',
        Taxonomy: ['Hygiene', 'Soap'],
        ProductVariants: [
            {
                VariantId: 'V-42',
                Sku: 'SKU-42-RED',
                Name: 'Red 1L',
                Size: '1l',
                Stock: 10,
                OriginalPrice: 19.99,
                SalePrice: 14.99,
                Currency: 'USD',
                IsAvailable: true
            }
        ]
    }
];

axios.post(url, products, { headers })
    .then(response => console.log(response.data))
    .catch(error => console.error(error));

📊 Response Examples

✅ Success Response (200)

{
  "success": true,
  "message": "Products saved.",
  "data": {
    "count": 2,
    "processedAt": "2024-12-22T14:05:51Z"
  }
}

❌ Validation Error (400) - Missing Required Fields

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-pqr789...",
  "errors": {
    "[0].ProductId": [
      "The ProductId field is required."
    ],
    "[0].ProductVariants[0].VariantId": [
      "The VariantId field is required."
    ],
    "[0].ProductVariants[0].Sku": [
      "The Sku field is required."
    ]
  }
}

📖 What this means:

Your first product (index [0]) is missing required fields
ProductId is required for the product
The first variant (index [0]) is missing VariantId and Sku

✅ How to fix:

[
  {
    "ProductId": "P-123",
    "ProductVariants": [
      {
        "VariantId": "V-123-RED",
        "Sku": "SKU-123-RED"
      }
    ]
  }
]

💡 Common causes:

Forgot to include required fields
Typo in field names (they are case-sensitive)
Sending empty object {}

❌ Validation Error (400) - String Length Exceeded

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-stu123...",
  "errors": {
    "[0].ProductId": [
      "The field ProductId must be a string with a maximum length of 100."
    ],
    "[0].ProductVariants[0].Image": [
      "The field Image must be a string with a maximum length of 2000."
    ],
    "[0].ProductVariants[0].Currency": [
      "The field Currency must be a string with a maximum length of 3."
    ]
  }
}

📖 What this means:

One or more fields exceed their maximum allowed length
ProductId: maximum 100 characters
Image URLs: maximum 2000 characters
Currency: maximum 3 characters

✅ How to fix:

Shorten the field values to meet length limits
For ProductId: use shorter IDs or codes
For Image: use URL shorteners or CDN paths
For Currency: use standard 3-letter codes (USD, EUR, etc.)

💡 Field length limits: || Field | Max Length | |||-------|------------| || ProductId | 100 | || VariantId | 100 | || Sku | 200 | || Size, Color | 50 | || ProductName, BrandName | 200 | || Variant Name | 600 | || Image, Url | 2000 | || Currency | 3 | || Language | 10 |

❌ Not Found (404)

{
  "success": false,
  "message": "Tenant not found.",
  "data": {}
}

❌ Internal Server Error (500)

{
  "success": false,
  "message": "An unexpected error occurred. Please try again.",
  "data": {}
}

💡 Best Practices

Variant Management: Always include at least one variant, even for simple products
Image URLs: Use HTTPS URLs for product images (max 2000 characters)
Size Format: Use standard size notations (e.g., "1l", "500ml", "XL")
Pricing: Ensure SalePrice is less than or equal to OriginalPrice
Taxonomy: Use consistent category naming across products (hierarchical structure recommended)
Stock Levels: Keep stock information updated to prevent overselling
Language Format: Use IETF language tags (BCP 47):
- Examples: en, en-US, en-GB, fr-FR, de-DE, es-ES
- Pattern: language[-script][-region]
- Reference: IETF BCP 47
Currency Format: Use ISO 4217 currency codes:
- Examples: USD, EUR, GBP, JPY, CAD, AUD
- Always use 3-letter codes
- Reference: ISO 4217
Batch Size: Recommended batch size is 50-100 products per request
Product Identifiers: Ensure consistency between ProductId and SKU across your systems

🎨 Size Parsing Examples

Input

SizeNumeric

SizeMetric

"1l"

"l"

"500ml"

500

"ml"

"2.5kg"

2.5

"kg"

"XL"

null

"XL"

PreviousOrders NextRate Limits

Last updated 1 month ago

hashtag🚀 TL;DR - Quick Reference

hashtag🔗 Endpoint

hashtag📋 Parameters

hashtag📨 Request

hashtag✅ Success Response

hashtag❌ Error Responses

hashtag🎯 Identifier Behavior

hashtag📄 Request Schema

hashtagUpsertProductDto Fields

hashtagUpsertProductVariantDto Fields

hashtag🗑️ DELETE Endpoints

hashtag🔗 Delete Product

hashtag📋 Parameters

hashtag✅ Success Response

hashtag🔗 Delete Product Variant

hashtag📋 Parameters

hashtag✅ Success Response

hashtag❌ Error Responses

hashtag🚀 DELETE Examples

hashtagDelete Product - cURL

hashtagDelete Variant - Python

hashtagDelete Product - Node.js

hashtag💡 Real-World Use Cases

hashtagUse Case 1: New Product Launch

hashtagUse Case 2: Price Update (Sale)

hashtagUse Case 3: Out of Stock

hashtagUse Case 4: Multi-Pack Product

hashtag📝 Complete Example Request (All Fields)

hashtag📝 Minimal Example Request (Required Fields Only)

hashtag📝 Example with Excluded Product

hashtag🚀 cURL Example

hashtag🐍 Python Example

hashtag🟢 Node.js Example

hashtag📊 Response Examples

hashtag✅ Success Response (200)

hashtag❌ Validation Error (400) - Missing Required Fields

hashtag❌ Validation Error (400) - String Length Exceeded

hashtag❌ Not Found (404)

hashtag❌ Internal Server Error (500)

hashtag💡 Best Practices

hashtag🎨 Size Parsing Examples

hashtag🔍 Related Resources

🚀 TL;DR - Quick Reference

🔗 Endpoint

📋 Parameters

📨 Request

✅ Success Response

❌ Error Responses

🎯 Identifier Behavior

📄 Request Schema

UpsertProductDto Fields

UpsertProductVariantDto Fields

🗑️ DELETE Endpoints

🔗 Delete Product

📋 Parameters

✅ Success Response

🔗 Delete Product Variant

📋 Parameters

✅ Success Response

❌ Error Responses

🚀 DELETE Examples

Delete Product - cURL

Delete Variant - Python

Delete Product - Node.js

💡 Real-World Use Cases

Use Case 1: New Product Launch

Use Case 2: Price Update (Sale)

Use Case 3: Out of Stock

Use Case 4: Multi-Pack Product

📝 Complete Example Request (All Fields)

📝 Minimal Example Request (Required Fields Only)

📝 Example with Excluded Product

🚀 cURL Example

🐍 Python Example

🟢 Node.js Example

📊 Response Examples

✅ Success Response (200)

❌ Validation Error (400) - Missing Required Fields

❌ Validation Error (400) - String Length Exceeded

❌ Not Found (404)

❌ Internal Server Error (500)

💡 Best Practices

🎨 Size Parsing Examples

🔍 Related Resources