Orders
Order API methods let e-commerce platforms sync order data with ECDP. This keeps customer purchase history up to date and supports analytics, segmentation, RFM analysis, and personalized marketing workflows.
POST/orders – add or update orders
creates new orders or updates existing order records.
Endpoint
The endpoint for GET requests is https://api.ecdp.app/orders
Request parameters
| Parameter | Location | Type | Required | Description | Allowed values / Notes |
| x-api-key | header | string | yes | API authentication key | Obtain from Settings > API |
| Content-Type | header | String | yes | Request content type | Application/json |
| mode | body | string | yes | Operation mode | Add, AddOrReplace, Replace |
| id | body | string | yes | Unique order identifier | Max: 128 characters |
| date | body | string | yes | Order placement timestamp | ISO 8601 format: YYYY-MM-DDT HH:mm:ss.sssZ |
| timeZone | body | string | no | Time zone for order date | See Supported time zones. Default: business unit time zone |
| websiteId | body | integer | No | Website identifier | Integer value |
| status | body | string | no | Order status | placed, paid, completed, canceled |
| currency | body | string | no | Currency code | Exactly 3 characters (ISO 4217) |
| totalValue | body | number | no | Total order value | Min: 0 |
| returnsValue | body | number | no | Value of returned items | Min: 0 |
| customer | body | object | yes | Customer identification | See Order customer data |
| products | body | array | yes | Ordered products | See Order product data |
| orderAttributes | body | array | no | Custom order attributes | See Order attribute value |
Order customer data
| Parameter | Location | Type | Required | Description | Notes |
| body | string | conditional | Customer email address | Required if email is the default matching mode. Max: 320 characters | |
| phone | body | string | conditional | Customer phone number | Required if phone is the default matching mode. Max: 20 characters |
| crmId | body | string | conditional | Customer CRM identifier | Required if CRM ID is the default matching mode. Max: 128 characters |
At least one customer identifier matching your Settings > Customers > Customers configuration is required.
Order product data
| Parameter | Location | Type | Required | Description | Notes |
| id | body | string | yes | Product identifier | Min: 1, Max: 128 characters |
| name | body | string | yes | Product name | Min: 0, Max: 2048 characters |
| price | body | number | yes | Unit price | Min: 0 |
| quantity | body | integer | yes | Quantity purchased | Min: 1, Max: 2147483647 |
| returned | body | integer | no | Quantity returned | Min: 0, Max: 2147483647 |
| url | body | string | no | Product page URL | Max: 2048 characters |
| imageUrl | body | string | no | Product image URL | Max: 2048 characters |
| category | body | string | no | Product category | Max: 2048 characters |
| productAttributes | body | array | no | Custom product attributes | See Product attribute value |
Product attribute value
| Parameter | Location | Type | Required | Description | Notes |
| name | body | string | yes | Attribute name | Max: 256 characters |
| value | body | string | no | Attribute value | — |
Order attribute value
| Parameter | Location | Type | Required | Description | Notes |
| name | body | string | yes | Attribute name | Max: 256 characters |
| value | body | string | no | Attribute value | — |
Example request
Add new order
{
"mode": "Add",
"data": [
{
"id": " 202478543",
"date": "2024-11-15T14:32:00.000Z",
"timeZone": "Central European Standard Time",
"websiteId": 1,
"status": "completed",
"currency": "EUR",
"totalValue": 249.99,
"returnsValue": 0,
"customer": {
"email": "jon.doe@example.com",
"phone": "+48501234567",
"crmId": "CRM-98765"
},
"products": [
{
"id": "SKU-12345",
"name": "Wireless Bluetooth Headphones",
"price": 199.99,
"quantity": 1,
"returned": 0,
"url": "https://shop.example.com/products/wireless-headphones",
"imageUrl": "https://shop.example.com/images/headphones-black.jpg",
"category": "Electronics > Audio",
"productAttributes": [
{
"name": "Color",
"value": "Black"
},
{
"name": "Warranty",
"value": "24 months"
}
]
},
{
"id": "SKU-67890",
"name": "USB-C Charging cable",
"price": 24.99,
"quantity": 2,
"returned": 0,
"url": "https://shop.example.com/products/usb-c-cable",
"imageUrl": "https://shop.example.com/images/cable-usbc.jpg",
"category": "Electronics > Accessories"
}
],
"orderAtt
{
"name": "Shipping method",
"value": "Express delivery"
},
{
"name": "Payment method",
"value": "Credit card"
}
]
}
]
}Add new order or replace existing order data
{
"mode": "AddOrReplace",
"data": [
{
"id": "ORD-2024-78543",
"date": "2024-11-15T14:32:00.000Z",
"status": "paid",
"currency": "EUR",
"totalValue": 249.99,
"customer": {
"email": "jan.kowalski@example.com"
},
"products": [
{
"id": "SKU-12345",
"name": "Wireless Bluetooth Headphones",
"price": 199.99,
"quantity": 1
}
]
}
]
}Response codes
| Code | Status | Description |
| 201 | Created | Order successfully created or updated |
| 400 | Bad Request | Invalid request parameters or missing required fields |
| 401 | Unauthorized | Missing or invalid API key |
Example response#
201 Created
The endpoint returns an empty response body on success.
400 Bad request
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "Bad Request",
"status": 400,
"detail": "Validation failed",
"instance": "/orders",
"errors": [
"Field 'id' is required",
"Field 'totalValue' must be greater than or equal to 0"
]
}GET /orders/{id} – retrieve order by ID
GET/orders/{id} method retrieves complete order details.
Endpoint
The endpoint for GET requests is https://api.ecdp.app/orders/{id}
Request parameters#
| Parameter | Location | Type | Required | Description | Notes |
| id | path | string | Yes | Order identifier | The unique ID assigned when the order was created |
| x-api-key | header | string | Yes | API authentication key | Obtain from Settings > API |
Example request
GET /orders/202478543
Response codes
| Code | Status | Description |
| 200 | Success | Order data returned successfully |
| 401 | Unauthorized | Missing or invalid API key |
| 404 | Not Found | Order with specified ID does not exist |
Example response
200 Success
{
"status": 0,
"data": {
"id": "202478543",
"date": "2024-11-15T14:32:00.000Z",
"timeZone": "Central European Standard Time",
"websiteId": 1,
"status": "completed",
"currency": "EUR",
"totalValue": 249.99,
"returnsValue": 0,
"customer": {
"id": 458721,
"email": "john.doe@example.com",
"phone": "+48501234567",
"crmId": "CRM-98765"
},
"products": [
{
"id": "SKU-12345",
"name": "Wireless Bluetooth Headphones",
"price": 199.99,
"quantity": 1,
"returned": 0,
"url": "https://shop.example.com/products/wireless-headphones",
"imageUrl": "https://shop.example.com/images/headphones-black.jpg",
"category": "Electronics > Audio",
"productAttributes": [
{
"name": "Color",
"value": "Black"
},
{
"name": "Warranty",
"value": "24 months"
}
]
},
{
"id": "SKU-67890",
"name": "USB-C Charging cable",
"price": 24.99,
"quantity": 2,
"returned": 0,
"url": "https://shop.example.com/products/usb-c-cable",
"imageUrl": "https://shop.example.com/images/cable-usbc.jpg",
"category": "Electronics > Accessories",
"productAttributes": []
}
],
"orderAttributes": [
{
"name": "Shipping method",
"value": "Express delivery"
},
{
"name": "Payment method",
"value": "Credit card"
}
]
}
}404 Not Found
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
"title": "Not Found",
"status": 404,
"detail": "Order not found",
"instance": "/orders/ORD-INVALID-123"
}PUT /orders/status – Update order status
The PUT method updates the status of an existing order.
Endpoint
The endpoint for GET requests is https://api.ecdp.app/orders/status
Request parameters
| Parameter | Location | Type | Required | Description | Allowed values / Notes |
| x-api-key | header | string | Yes | API authentication key | Obtain from Settings > API |
| orderId | body | string | Yes | Order identifier | Must reference an existing order, min: 1 character |
| orderStatus | body | string | Yes | New order status | placed, paid, completed, canceled |
Example request
Mark order as paid
{
"orderId": "202478543",
"orderStatus": "paid"
}Mark order as completed
{
"orderId": "202478543 ",
"orderStatus": "completed"
}Response codes
| Code | Status | Description |
| 200 | Success | Order status updated successfully |
| 400 | Bad Request | Invalid status value or missing required fields |
| 401 | Unauthorized | Missing or invalid API key |
Example response
400 Bad Request
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "Bad Request",
"status": 400,
"detail": "Invalid order status",
"instance": "/orders/status",
"errors": [
"Field 'orderStatus' must be one of: placed, paid, completed, canceled"
]
}DELETE /orders/{id} – mark order as deleted
DELETE /orders/{id} marks an order as deleted by setting the IsDeleted flag. This operation performs a soft delete, preserving the order record for audit purposes while excluding it from active reporting and analytics.
Endpoint
The endpoint for GET requests is https://api.ecdp.app/orders/{id}
Request parameters
| Parameter | Location | Type | Required | Description | Notes |
| id | path | string | Yes | Order identifier | Must reference an existing order |
| x-api-key | header | string | Yes | API authentication key | Obtain from Settings > API |
Example request
DELETE /orders/2024-78543
Response codes
| Code | Status | Description |
| 200 | Success | Order marked as deleted; returns order data |
| 401 | Unauthorized | Missing or invalid API key |
| 404 | Not Found | Order with specified ID does not exist |
Example response
200 Success
{
"status": 0,
"data": {
"id": "202478543 ",
"date": "2024-11-15T14:32:00.000Z",
"timeZone": "Central European Standard Time",
"websiteId": 1,
"status": "completed",
"currency": "EUR",
"totalValue": 249.99,
"returnsValue": 0,
"customer": {
"id": 458721,
"email": "john.doe@example.com",
"phone": "+48501234567",
"crmId": "CRM-98765"
},
"products": [
{
"id": "SKU-12345",
"name": "Wireless Bluetooth Headphones",
"price": 199.99,
"quantity": 1,
"returned": 0,
"url": "https://shop.example.com/products/wireless-headphones",
"imageUrl": "https://shop.example.com/images/headphones-black.jpg",
"category": "Electronics > Audio",
"productAttributes": [
{
"name": "Color",
"value": "Black"
}
]
}
],
"orderAttributes": [
{
"name": "Shipping method",
"value": "Express delivery"
}
]
}
}Validation and behavior rules
The following validation rules apply to all Orders API endpoints:
- Order ID must be unique within the business unit.
- At least one customer identifier (email, phone, or crmId) matching your configured matching mode is required.
- The products array must contain at least one product with valid id, name, price, and quantity.
- Product quantity must be at least 1. Product price and totalValue must be 0 or greater.
- If timeZone is omitted in order date, the business unit’s configured time zone applies.
- Order status accepts only: placed, paid, completed, canceled (case-insensitive).
- DELETE operation performs soft delete. The order remains in the database with IsDeleted flag set to true.
Reference documentation#
Swagger – Orders