Replenit
Replenit - Turn Every Customer Into Loyal Repeat Buyer
docs

Orders API

By Marta Szymanska
•February 3, 2026

Replenit Ingestion API | Orders

Orders

Bulk upsert order records with line items for a tenant.

Overview

The Orders endpoint supports bulk creation and updates of order records for a tenant.
Each request processes an array of order objects and applies upsert semantics based on OrderId.

Orders are associated with customers using the tenant’s configured customer identifier and with products using identifiers provided in order line items.

This endpoint is used to synchronize transactional purchase data from upstream commerce, billing, or order-management systems into Replenit.

Quick Reference

Endpoint

POST /orders/{tenantId}

 

Usage

  • Record completed purchases
  • Import historical orders
  • Update order state (cancellation or refund)
  • Synchronize transactions from external systems

Required Fields

  • OrderId
  • Currency

Authentication

  • x-replenit-auth-key header required

Response

  • Returns the number of processed orders

Base URL

https://api.replen.it

 

Authentication

All requests must include the following header:

x-replenit-auth-key: YOUR_BASE64_ACCESS_KEY

 

API Endpoints

Create or Update Orders

POST /orders/{tenantId}
Host: api.replen.it
Content-Type: application/json
x-replenit-auth-key: YOUR_BASE64_ACCESS_KEY

 

This endpoint supports bulk upsert semantics.
Each request processes an array of order objects.

Delete Order

DELETE /orders/{tenantId}/{orderId}
Host: api.replen.it
x-replenit-auth-key: YOUR_BASE64_ACCESS_KEY

 

This endpoint permanently removes an order record for the given tenant.

Parameters

Parameter Type Required Description
tenantId GUID Yes Tenant identifier

Request

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

Success Response

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

Error Responses

Status Description
400 Invalid request payload
404 Tenant not found
500 Internal server error

 

Identifier Behavior

Order Identification

  • Orders are uniquely identified by OrderId
  • If OrderId exists, the record is updated
  • If OrderId does not exist, a new order record is created

Customer Identification

Customer association depends on the tenant’s identifier priority configuration.

Priority Setting Identifier Used
Customer Id CustomerId
Email Email

 

Only the configured primary identifier is used for matching. Secondary identifiers may be stored but are not used for identity resolution.

Certain behaviors described in Replenit Ingestion APIs are controlled by tenant-level configuration in the Replenit platform, including customer identifier selection, supported languages, supported currencies, and tenant timezone. These settings determine how incoming order payloads are validated, matched, and processed.

Tenant configuration is managed in the Replenit platform under Settings → Tenant Settings. Access is limited to platform administrators.


 If you are unsure about the current configuration, do not have access to tenant settings, or have questions about the correct setup for your integration, please contact your Replenit Customer Success Manager (CSM) or your internal platform administrator.

 

Changes to tenant settings apply to all subsequent API requests.

 

Identifier Alignment and PII Considerations

If CustomerId is used as the primary identifier, the same identifier must be configured and used consistently across downstream systems consuming Replenit data, including marketing automation, CRM, analytics, and activation platforms.

If Email is used as the primary identifier, the same email address must be configured consistently in downstream systems.

When a stable, non-PII CustomerId is available and already used across downstream systems, email address should not be relied on for identity resolution. In this case, email may be omitted unless required for downstream communication.

Replenit does not require email address when a stable CustomerId is available.

Inconsistent identifier usage may result in fragmented customer-order relationships and increased data governance risk.

Product Identification

Order line items reference products using:

  • ProductId
  • Sku

These identifiers must correspond to products ingested via the Products API.

Request Schema

UpsertOrderDto

Field Type Max Length Required Default Description
OrderId string 100 Yes – Unique order identifier
CustomerId string – Yes – Customer identifier
Email string – Yes, If no CustomerId – Customer email
TotalQuantity int – No 1 Total item quantity
UniqueQuantity int – No 1 Number of unique items
TotalRevenue double – No 0 Total order value
Currency string 3 Yes USD ISO 4217 currency code
OrderDate string – No Server UTC ISO-8601 datetime
IsOrderCancelled bool – No false Cancellation flag
OrderItems array – No [] Order line items

 

CreateOrderItemDto

Field Type Max Length Required Description
ProductId string 100 Yes Product identifier
Sku string 50 Yes Product SKU
Quantity int – Yes Item quantity
Price double – Yes Item price
OriginalPrice double – No Pre-discount price
Size string 50 No Size variant
Color string 50 No Color variant
Brand string – No Brand
IsGift bool – No Gift flag

 

Examples

Minimal Order

[
  {
    “OrderId”: “O-791”,
    “Currency”: “USD”
  }
]

 

Standard Order (All Supported Fields)

[
  {
    “OrderId”: “O-789”,
    “CustomerId”: “C-123”,
    “Email”: “customer@example.com”,
    “TotalQuantity”: 3,
    “UniqueQuantity”: 2,
    “TotalRevenue”: 89.97,
    “Currency”: “USD”,
    “OrderDate”: “2025-08-23T10:30:00Z”,
    “IsOrderCancelled”: false,
    “OrderItems”: [
      {
        “ProductId”: “P-42”,
        “Sku”: “SKU-42-RED-L”,
        “Quantity”: 2,
        “Price”: 29.99,
        “OriginalPrice”: 39.99,
        “Size”: “1l”,
        “Color”: “red”,
        “Brand”: “Acme”,
        “IsGift”: false
      },
      {
        “ProductId”: “P-43”,
        “Sku”: “SKU-43-BLUE-M”,
        “Quantity”: 1,
        “Price”: 29.99,
        “OriginalPrice”: 29.99,
        “Size”: “500ml”,
        “Color”: “blue”,
        “Brand”: “Acme”,
        “IsGift”: true
      }
    ]
  }
]

 

cURL Example

curl -X POST “https://api.replen.it/orders/{tenantId}” \
  -H “Content-Type: application/json” \
  -H “x-replenit-auth-key: YOUR_BASE64_ACCESS_KEY” \
  -d @orders.json

 

Python Example

import requests

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

orders = [
    {
        “OrderId”: “O-789”,
        “CustomerId”: “C-123”,
        “Currency”: “USD”,
        “TotalRevenue”: 99.99,
        “OrderItems”: [
            {
                “ProductId”: “P-42”,
                “Sku”: “SKU-42”,
                “Quantity”: 1,
                “Price”: 99.99
            }
        ]
    }
]

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

 

Node.js Example

const axios = require(‘axios’);

axios.post(
  ‘https://api.replen.it/orders/{tenantId}’,
  [{
    OrderId: ‘O-789’,
    CustomerId: ‘C-123’,
    Currency: ‘USD’,
    OrderItems: [{
      ProductId: ‘P-42’,
      Sku: ‘SKU-42’,
      Quantity: 1,
      Price: 99.99
    }]
  }],
  { headers: { ‘x-replenit-auth-key’: ‘YOUR_BASE64_ACCESS_KEY’ } }
)
.then(res => console.log(res.data))
.catch(err => console.error(err));

 

Response Examples

Success

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

 

Validation Error

{
  “status”: 400,
  “errors”: {
    “[0].OrderId”: [
      “The OrderId field is required.”
    ]
  }
}

 

Back to Blog