Products API

Overview

The Products endpoint supports bulk creation and updates of product catalog records for a tenant.

Each request processes an array of product objects and applies upsert semantics based on the tenant's product identifier configuration.

This endpoint is used to synchronize product catalogs, variants, pricing, attributes, and availability from upstream systems into Replenit. Product data is a prerequisite for accurate order ingestion, decisioning, recommendations, and downstream activation.

Quick Reference

Endpoints

Parameters

Request

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

Success Response

• Status: 200 OK
• Body: Response envelope containing data.count

Error Responses

Identifier Behavior

Product matching is determined by the tenant's product identifier priority configuration.

Identifier Priority

Matching Rules

• If the configured identifier exists, the product record is updated
• If the configured identifier does not exist, a new product record is created
• Secondary identifiers may be stored but are not used for matching

Example

{
  "ProductId": "P-100",
  "Sku": "SKU-100",
  "Name": "Premium Shampoo"
}

Identifier priority can be viewed or modified in the tenant configuration within the Replenit platform.

Product Identifier Configuration

Product matching and resolution in Replenit is controlled by the tenant-level Product Identifier Selection.

This configuration defines which field is used as the primary identifier when ingesting and resolving products across the platform.

Where to Configure

This setting requires Admin access. If you do not have access, contact your platform administrator or your Replenit Customer Success Manager (CSM).

Supported Identifier Modes

Behavior During Ingestion

• The configured identifier is used to match incoming products to existing records
• If a matching product exists, it is updated
• If no matching product exists, a new product is created
• Secondary identifiers may be stored but are not used for matching

Impact on APIs

This configuration affects:

Operational Requirement

Ensure that the identifier used in API payloads (ProductId or Sku) is:

• Consistently generated in upstream systems
• Stable over time
• Aligned with the configured Product Identifier Selection

Misalignment between payload identifiers and tenant configuration may result in unresolved or duplicated products.

Request Schema

UpsertProductDTO

VariantDTO

Data Completeness & Decision Quality

Replenit's decisioning accuracy improves with broader and richer data across all entities, including users, products, orders, and events.

You are encouraged to send as many fields as possible for every object, as long as the data is:

• Stable – consistently defined over time
• Complete – high coverage across records
• Reliable – not sparsely populated or frequently changing in meaning

While only a subset of fields is required for ingestion, additional attributes directly enhance:

• Profiling accuracy (user, product, and behavioral)
• Contextual understanding for decisioning
• Reasoning quality for all downstream decisions (replenishment, substitution, cross-sell, churn prevention, etc.)

Examples

[
  {
    "ProductId": "P-001",
    "Name": "Basic Product"
  }
]

[
  {
    "ProductId": "P-100",
    "Sku": "SKU-100",
    "Name": "Premium Shampoo",
    "Brand": "Acme",
    "Category": "Hair Care",
    "Currency": "EUR",
    "Price": 19.99,
    "OriginalPrice": 24.99,
    "IsActive": true
  }
]

[
  {
    "ProductId": "P-200",
    "Name": "Conditioner",
    "Brand": "Acme",
    "Category": "Hair Care",
    "Variants": [
      {
        "VariantId": "V-200-250",
        "Sku": "SKU-200-250ML",
        "Price": 14.99,
        "Size": "250ml",
        "IsActive": true
      },
      {
        "VariantId": "V-200-500",
        "Sku": "SKU-200-500ML",
        "Price": 24.99,
        "Size": "500ml",
        "IsActive": true
      }
    ]
  }
]

curl -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

Response Examples

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

{
  "status": 400,
  "errors": {
    "": [
      "At least one of the following properties must have a value: ProductId, Sku"
    ]
  }
}