🛒Orders

💡 Bulk upsert orders with items for a tenant

🚀 TL;DR - Quick Reference

Endpoint: POST /orders/{tenantId}

Use When:

Customer completes a purchase
Importing historical order data
Order refund/cancellation
Syncing e-commerce transactions

Required: OrderId, Currency Auth: x-replenit-auth-key header Returns: Count of upserted orders

Quickest Example:

POST /orders/{YOUR_TENANT_ID}
[{
  "OrderId": "O-789",
  "Currency": "USD",
  "TotalRevenue": 99.99,
  "OrderItems": []
}]

Jump to Full API Reference ↓

🔗 Endpoint

POST /orders/{tenantId}

📋 Parameters

Parameter

Type

Required

Description

tenantId

GUID

✅ Yes

The tenant identifier (must exist)

📨 Request

Body: JSON array of UpsertOrderDto 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

Customer Identification

Priority Setting

Identifier Used

customerid

Customer ID from order

email (default)

Email address from order

Product Identification

📝 Note: Order items currently use ProductId for identification

📄 Request Schema

UpsertOrderDto Fields

Field

Type

Max Length

Default

Required

Description

OrderId

string

100

✅

Unique order identifier

Email

string

❌

Customer email (optional if CustomerId is sent)

CustomerId

string

❌

Customer ID (used if priority is "CustomerId")

TotalQuantity

int

❌

Total items in order

TotalRevenue

double

❌

Total order value

OrderDate

string

UTC now

❌

ISO-8601 datetime; defaults to server UTC time if omitted

Currency

string

USD

✅

Currency code (ISO 4217)

UniqueQuantity

int

❌

Number of unique items

IsOrderCancelled

bool

false

❌

Cancellation status

OrderItems

CreateOrderItemDto[]

[]

❌

Order line items

CreateOrderItemDto Fields

Field

Type

Max Length

Required

Description

ProductId

string

100

✅

Product identifier

Sku

string

✅

Product SKU

Quantity

int

✅

Item quantity

Price

double

✅

Item price

Size

string

❌

Size (e.g., "1l")

Color

string

❌

Color variant

Brand

string

❌

Brand name

IsGift

bool

❌

Gift item flag

OriginalPrice

double

❌

Pre-discount price

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

🗑️ DELETE Endpoint

🔗 Delete Order

DELETE /orders/{tenantId}/{orderId}

📋 Parameters

Parameter

Type

Required

Description

tenantId

GUID

✅ Yes

The tenant identifier

orderId

string

✅ Yes

The order ID to delete

✅ Success Response

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

{
  "success": true,
  "message": "Order removed.",
  "data": { 
    "orderId": "O-789",
    "deletedAt": "2024-12-22T14:02:49Z"
  }
}

❌ Error Responses

|| Status | Scenario | Example Response | || ------ | -------- | ---------------- | || 400 | Missing order ID | {"success": false, "message": "Order ID is required.", "data": {}} | || 404 | Tenant not found | {"success": false, "message": "Tenant not found.", "data": {}} | || 404 | Order not found | {"success": false, "message": "Order not found.", "data": {}} | || 500 | Storage failure | {"success": false, "message": "Failed to delete order.", "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

cURL

curl -X DELETE "https://api.replen.it/orders/{tenantId}/O-789" \
  -H 'x-replenit-auth-key: YOUR_BASE64_ACCESS_KEY'

Python

import requests

url = "https://api.replen.it/orders/{tenantId}/O-789"
headers = {
    "x-replenit-auth-key": "YOUR_BASE64_ACCESS_KEY"
}

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

Node.js

const axios = require('axios');

const url = 'https://api.replen.it/orders/{tenantId}/O-789';
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: E-commerce Purchase

Scenario: Customer just purchased 2 items from your online store

What to send:

[{
  "OrderId": "SHOP-2024-789",
  "Email": "customer@example.com",
  "CustomerId": "C-123",
  "TotalQuantity": 3,
  "TotalRevenue": 149.97,
  "Currency": "USD",
  "OrderDate": "2024-12-22T10:30:00Z",
  "OrderItems": [
    {
      "ProductId": "P-42",
      "Sku": "SKU-42-L",
      "Quantity": 2,
      "Price": 49.99,
      "Size": "L"
    },
    {
      "ProductId": "P-43",
      "Sku": "SKU-43-M",
      "Quantity": 1,
      "Price": 49.99,
      "Size": "M"
    }
  ]
}]

What happens:

✅ Order synced to customer profile
🎯 Triggers "post-purchase" automation
📧 Thank you email sent
📊 Revenue attributed to customer

Use Case 2: Order Refund

Scenario: Customer returned an order, mark it as cancelled

What to send:

[{
  "OrderId": "O-789",
  "IsOrderCancelled": true,
  "TotalRevenue": -99.99,
  "Currency": "USD"
}]

What happens:

✅ Order marked as cancelled
📊 Revenue metrics updated (subtracted)
🎯 Customer removed from post-purchase flow

Use Case 3: Subscription Order

Scenario: Recurring monthly subscription payment

What to send:

[{
  "OrderId": "SUB-2024-12-001",
  "CustomerId": "C-456",
  "TotalRevenue": 29.99,
  "Currency": "EUR",
  "OrderDate": "2024-12-01T00:00:00Z",
  "OrderItems": [{
    "ProductId": "SUBSCRIPTION-PREMIUM",
    "Sku": "SUB-PREMIUM-MONTHLY",
    "Quantity": 1,
    "Price": 29.99
  }]
}]

Best practice: Use consistent OrderId pattern for subscriptions (e.g., SUB-{YYYY-MM}-{ID})

Use Case 4: Gift Order

Scenario: Customer bought items as gifts

What to send:

[{
  "OrderId": "GIFT-2024-999",
  "Email": "buyer@example.com",
  "TotalRevenue": 150.00,
  "Currency": "GBP",
  "OrderItems": [
    {
      "ProductId": "P-100",
      "Sku": "SKU-100",
      "Quantity": 3,
      "Price": 50.00,
      "IsGift": true
    }
  ]
}]

What happens:

✅ Order tracked as gift purchase
🎁 Analytics show gift behavior
🎯 Can trigger gift-specific campaigns

📝 Complete Example Request (All Fields)

[
  {
    "OrderId": "O-789",
    "Email": "john.doe@example.com",
    "CustomerId": "C-123",
    "TotalQuantity": 3,
    "TotalRevenue": 89.97,
    "OrderDate": "2025-08-22T21:00:00Z",
    "Currency": "USD",
    "UniqueQuantity": 2,
    "IsOrderCancelled": false,
    "OrderItems": [
      {
        "ProductId": "P-42",
        "Sku": "SKU-42-RED-L",
        "Quantity": 2,
        "Price": 29.99,
        "Size": "1l",
        "Color": "red",
        "Brand": "Acme Corp",
        "IsGift": false,
        "OriginalPrice": 39.99
      },
      {
        "ProductId": "P-43",
        "Sku": "SKU-43-BLUE-M",
        "Quantity": 1,
        "Price": 29.99,
        "Size": "500ml",
        "Color": "blue",
        "Brand": "Acme Corp",
        "IsGift": true,
        "OriginalPrice": 29.99
      }
    ]
  },
  {
    "OrderId": "O-790",
    "Email": "jane.smith@example.com",
    "CustomerId": "C-124",
    "TotalQuantity": 5,
    "TotalRevenue": 149.95,
    "OrderDate": "2025-08-23T10:30:00Z",
    "Currency": "EUR",
    "UniqueQuantity": 3,
    "IsOrderCancelled": false,
    "OrderItems": [
      {
        "ProductId": "P-100",
        "Sku": "SKU-100",
        "Quantity": 3,
        "Price": 29.99,
        "Size": "XL",
        "Color": "black",
        "Brand": "Premium Brand",
        "IsGift": false,
        "OriginalPrice": 49.99
      },
      {
        "ProductId": "P-101",
        "Sku": "SKU-101",
        "Quantity": 1,
        "Price": 39.99,
        "Size": "M",
        "Color": "white",
        "Brand": "Premium Brand",
        "IsGift": false,
        "OriginalPrice": 39.99
      },
      {
        "ProductId": "P-102",
        "Sku": "SKU-102",
        "Quantity": 1,
        "Price": 19.99,
        "Size": "S",
        "Color": "green",
        "Brand": "Eco Brand",
        "IsGift": false,
        "OriginalPrice": 24.99
      }
    ]
  }
]

📝 Minimal Example Request (Required Fields Only)

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

📝 Cancelled Order Example

[
  {
    "OrderId": "O-792",
    "Email": "cancelled@example.com",
    "TotalQuantity": 1,
    "TotalRevenue": 49.99,
    "OrderDate": "2025-08-23T08:00:00Z",
    "Currency": "GBP",
    "UniqueQuantity": 1,
    "IsOrderCancelled": true,
    "OrderItems": [
      {
        "ProductId": "P-200",
        "Sku": "SKU-200",
        "Quantity": 1,
        "Price": 49.99
      }
    ]
  }
]

🚀 cURL Example

curl -sS \
  -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
from datetime import datetime

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

orders = [
    {
        "OrderId": "O-789",
        "Email": "john.doe@example.com",
        "CustomerId": "C-123",
        "TotalQuantity": 2,
        "TotalRevenue": 29.99,
        "OrderDate": datetime.utcnow().isoformat() + "Z",
        "Currency": "USD",
        "OrderItems": [
            {
                "ProductId": "P-42",
                "Sku": "SKU-42",
                "Quantity": 1,
                "Price": 14.99,
                "Size": "1l",
                "Color": "red",
                "Brand": "Acme"
            }
        ]
    }
]

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

🟢 Node.js Example

const axios = require('axios');

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

const orders = [
    {
        OrderId: 'O-789',
        Email: 'john.doe@example.com',
        CustomerId: 'C-123',
        TotalQuantity: 2,
        TotalRevenue: 29.99,
        OrderDate: new Date().toISOString(),
        Currency: 'USD',
        OrderItems: [
            {
                ProductId: 'P-42',
                Sku: 'SKU-42',
                Quantity: 1,
                Price: 14.99,
                Size: '1l',
                Color: 'red',
                Brand: 'Acme'
            }
        ]
    }
];

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

📊 Response Examples

✅ Success Response (200)

{
  "success": true,
  "message": "Orders 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-xyz789...",
  "errors": {
    "[0].OrderId": [
      "The OrderId field is required."
    ],
    "[0].Currency": [
      "The Currency field is required."
    ],
    "[0].OrderItems[0].ProductId": [
      "The ProductId field is required."
    ],
    "[0].OrderItems[0].Sku": [
      "The Sku field is required."
    ]
  }
}

📖 What this means:

Your first order (index [0]) is missing required fields
OrderId and Currency are required for all orders
Each order item needs ProductId and Sku

✅ How to fix:

[
  {
    "OrderId": "O-789",
    "Currency": "USD",
    "OrderItems": [
      {
        "ProductId": "P-42",
        "Sku": "SKU-42",
        "Quantity": 1,
        "Price": 29.99
      }
    ]
  }
]

💡 Required fields:

Order level: OrderId, Currency
Order item level: ProductId, Sku, Quantity, Price

❌ 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-mno456...",
  "errors": {
    "[0].OrderId": [
      "The field OrderId must be a string with a maximum length of 100."
    ],
    "[0].Currency": [
      "The field Currency must be a string with a maximum length of 3."
    ]
  }
}

📖 What this means:

Field values exceed maximum allowed length
OrderId: maximum 100 characters (shorten your order IDs)
Currency: maximum 3 characters (use standard 3-letter codes)

✅ How to fix:

{
  "OrderId": "ORD-2024-12345",     // ✓ Under 666 chars
  "Currency": "USD"                 // ✓ Standard 3-letter code
}

💡 Field length limits:

Field

Max Length

OrderId, ProductId

100

Sku, Size, Color

Currency

❌ 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

Order IDs: Use unique, sequential order identifiers
Timestamps: Always use UTC timezone for OrderDate in ISO-8601 format
Currency Format: Use ISO 4217 currency codes:
- Examples: USD, EUR, GBP, JPY, AUD, CAD, CHF
- Always use 3-letter codes (not symbols like $ or €)
- Reference: ISO 4217 Currency Codes
Calculations: Ensure TotalRevenue matches sum of item prices × quantities
Customer Data: Include either Email or CustomerId based on your identifier priority
Order Items: Always include the parent OrderId in each item
ProductIdentifiers: Please ensure that product identifiers (ProductId, SKU) are matched with your Product Catalog, so each event can be accurately linked to the correct product details (e.g., name, image, price)
Batch Size: Recommended batch size is 50-200 orders per request
Error Handling: Implement retry logic with exponential backoff for 500 errors

📈 Common Use Cases

💳 Processing a Simple Order

{
  "OrderId": "O-12345",
  "Email": "customer@example.com",
  "TotalQuantity": 1,
  "TotalRevenue": 9.99,
  "OrderDate": "2025-08-23T10:30:00Z",
  "Currency": "USD",
  "OrderItems": [
    {
      "ProductId": "P-100",
      "Sku": "SKU-100",
      "Quantity": 1,
      "Price": 9.99
    }
  ]
}

🎁 Order with Gift Items

{
  "OrderId": "O-GIFT-789",
  "CustomerId": "C-456",
  "TotalQuantity": 3,
  "TotalRevenue": 75.00,
  "OrderDate": "2025-08-23T14:45:00Z",
  "Currency": "EUR",
  "OrderItems": [
    {
      "ProductId": "P-200",
      "Sku": "SKU-200",
      "Quantity": 2,
      "Price": 30.00,
      "IsGift": false
    },
    {
      "ProductId": "P-201",
      "Sku": "SKU-201",
      "Quantity": 1,
      "Price": 15.00,
      "IsGift": true
    }
  ]
}

PreviousGetting Started NextProducts

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

hashtagCustomer Identification

hashtagProduct Identification

hashtag📄 Request Schema

hashtagUpsertOrderDto Fields

hashtagCreateOrderItemDto Fields

hashtag🗑️ DELETE Endpoint

hashtag🔗 Delete Order

hashtag📋 Parameters

hashtag✅ Success Response

hashtag❌ Error Responses

hashtag🚀 DELETE Examples

hashtagcURL

hashtagPython

hashtagNode.js

hashtag💡 Real-World Use Cases

hashtagUse Case 1: E-commerce Purchase

hashtagUse Case 2: Order Refund

hashtagUse Case 3: Subscription Order

hashtagUse Case 4: Gift Order

hashtag📝 Complete Example Request (All Fields)

hashtag📝 Minimal Example Request (Required Fields Only)

hashtag📝 Cancelled Order Example

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📈 Common Use Cases

hashtag💳 Processing a Simple Order

hashtag🎁 Order with Gift Items

hashtag🔍 Related Resources

🚀 TL;DR - Quick Reference

🔗 Endpoint

📋 Parameters

📨 Request

✅ Success Response

❌ Error Responses

🎯 Identifier Behavior

Customer Identification

Product Identification

📄 Request Schema

UpsertOrderDto Fields

CreateOrderItemDto Fields

🗑️ DELETE Endpoint

🔗 Delete Order

📋 Parameters

✅ Success Response

❌ Error Responses

🚀 DELETE Examples

cURL

Python

Node.js

💡 Real-World Use Cases

Use Case 1: E-commerce Purchase

Use Case 2: Order Refund

Use Case 3: Subscription Order

Use Case 4: Gift Order

📝 Complete Example Request (All Fields)

📝 Minimal Example Request (Required Fields Only)

📝 Cancelled Order Example

🚀 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

📈 Common Use Cases

💳 Processing a Simple Order

🎁 Order with Gift Items

🔍 Related Resources