API Reference

Orders API

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

Endpoints

POST/orders/{tenantId}

DELETE/orders/{tenantId}/{orderId}

Authentication

x-replenit-auth-keyheader required

Usage

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

Required Fields

• OrderId
• Currency

Base URL

https://api.replen.it

Response

Returns the number of processed orders

Endpoints

POST/orders/{tenantId}

DELETE/orders/{tenantId}/{orderId}

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

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.)

Rule of thumb:

If a field exists, is well-populated, and carries business meaning, it should be sent.

Optional fields never block ingestion, but richer payloads consistently produce better decisions.

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
      }
    ]
  }
]

Request Examples

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

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."
    ]
  }
}

Orders API

Overview

Quick Reference

Endpoints

Authentication

Usage

Required Fields

Base URL

Response

Endpoints

Parameters

Request

Success Response

Error Responses

Identifier Behavior

Order Identification

Customer Identification

Identifier Alignment and PII Considerations

Product Identification

Request Schema

UpsertOrderDto

CreateOrderItemDto

Data Completeness & Decision Quality

Rule of thumb:

Examples

Minimal Order

Standard Order (All Supported Fields)

Request Examples

Response Examples

Success

Validation Error

Related Documentation

Customers API

Products API

Getting Started

Authentication

Need help or have questions?