Orders – API methods
Using API, you can automate activities related to orders placed by your customers. We provide 3 HTTP methods:
- POST – Adding a new order or updating order data.
- GET – Obtaining information about an order using the order ID number.
- PUT – Adding an order that has not been registered in the platform.
- DELETE – Changing order status to ‘deleted’ (IsDeleted).
POST method – adding order information
The actions you can perform using this method include adding new orders data and updating data about already placed orders. There are 3 modes for this (modes):
- Add – Adding an order in ExpertSender.
- AddOrReplace – Adding a new order to the platform or replacing its data, if the order is already in the platform.
- Replace – Changing the data set in the order.
POST method – request
To send a request using this method, it must contain:
- Server address (endpoint): https://api.ecdp.app/orders
- Parameters:
Parameter | Type | Category | Max character count | Description |
x-api-key* | string | header | – | Your API key, which you can find in Settings > API. |
id* | string | body | 128 | Order ID number |
date* | string($date-time) | body | – | Date of placing the order |
totalValue* | number($double) | body | – | Total order value |
customer* | body | Customer attributes; includes an additional set of parameters >>> see table below | ||
products* | body | Product data; includes an additional set of parameters >>> see table below |
The customer, products and orderAttributes parameters have their own parameters that will allow you to add or obtain more detailed order information. Parameters marked with an asterisk must be included in the request.
For customers these are:
Parameter | Type | Max character count | Description |
string | 320 | Email address of the customer who placed the order | |
phone | string | 20 | Telephone number of the customer who placed the order |
crmId | string | 128 | CRM ID number of the customer who placed the order |
For products these are:
Parameter | Type | Max character count | Description |
id* | string | 128 | ID number of the purchased product |
name* | string | 2048 | Product name |
price* | number($double) | – | Product price; |
quantity* | integer($int32) | – | Quantity of product purchased; maximum value: 2147483647 |
returned | integer($int32) | – | Number of returned products; maximum value: 2147483647 |
url | string | 2048 | URL of the purchased product |
imageUrl | string | 2048 | Image URL of the purchased product |
category | string | 2048 | Category of the purchased product |
productAttributes | Product attributes; includes an additional set of parameters >>> see table below |
For productAttributes these are:
Parameter | Type | Character count | Description |
name* | string | min: 0 max: 256 | Product feature name; minimum number of characters: 1 |
value | string | – | Product feature value |
Other parameters you can include in your request:
Parameter | Type | Max character count | Description |
timeZone | string | 100 | The timezone that the order was placed in. You can find the values for this parameter here: Supported time zones for orders |
websiteId | integer($int32) | – | Integer($int32): The ID number of the store website where the order was placed |
status | string | – | The order status, which can be one of the following: placed, paid, completed, canceled |
currency | string | min: 3 max: 3 | The currency in which the order was placed |
returnsValue | number($double) | – | The value of returned products |
orderAttributes | Order attributes; includes an additional set of parameters >>> see table below |
For orderAttributes these are:
Parameter | Type | Max character count | Description |
name* | string | 256 | Order feature name; minimum number of characters: 1 |
value | string | – | Value of the order feature |
Query syntax for the POST method
Below, you can see an example syntax of the query that allows you to add (Add) an order to the database:
{
"mode": "Add",
"data": [
{
"id": "12345",
"date": "2024-11-06T10:10:00.055Z",
"timeZone": "Pacific Standard Time",
"websiteId": 1,
"status": "Completed",
"currency": "USD",
"totalValue": 150.00,
"returnsValue": 0,
"customer": {
"email": "customer@example.com",
"phone": "+15551234567",
"crmId": "67890"
},
"products": [
{
"id": "p001",
"name": "Wireless Earbuds",
"price": 75.00,
"quantity": 2,
"returned": 0,
"url": "https://example.com/products/wireless-earbuds",
"imageUrl": "https://example.com/images/wireless-earbuds.jpg",
"category": "Electronics",
"productAttributes": [
{
"name": "Color",
"value": "Black"
},
{
"name": "Warranty",
"value": "1 Year"
}
]
}
],
"orderAttributes": [
{
"name": "Shipping Method",
"value": "Express"
},
{
"name": "Gift Wrap",
"value": "Yes"
}
]
}
]
}
If you do not know whether a given order is already in the database and you want to add its data, change the “mode” parameter to “AddOrReplace”.
POST query response codes
201: Created
The request has been created.
400: Bad request
The request was not processed. The reason is usually a missing or incorrect parameter. Sample response syntax:
{
"type": "string",
"title": "string",
"status": 0,
"substatus": "CustomerInvalidModelState",
"detail": "string",
"instance": "string",
"errors": [
"string"
]
401: Unauthorized
The request was missing an API key or you are requesting access to information that you do not have permission to access. Sample response syntax:
{
"type": "string",
"title": "string",
"status": 0,
"substatus": "CustomerInvalidModelState",
"detail": "string",
"instance": "string"
}
GET method – obtaining information about the order
The GET method is used to obtain information from ExpertSender about the order placed by the customer. For a valid GET query, you will receive a response with a ‘read-only’ status.
GET method using the order ID number
To send a query using this method, it must contain:
- Server address (endpoint): https://api.ecdp.app/orders/{id}
- Order ID: Order number
- API key: Your API key, which you can find in Settings > API.
The correct API request for order number 12 looks like this: https://client.ecdp.app/orders/{12}
GET query response codes
200: Success
The query was processed, the server returned a response. Sample response syntax:
{
"status": 0,
"data": {
"id": "string",
"date": "2024-07-25T10:08:59.197Z",
"timeZone": "string",
"websiteId": 0,
"status": "string",
"currency": "str",
"totalValue": 0,
"returnsValue": 0,
"customer": {
"id": 0,
"email": "string",
"phone": "string",
"crmId": "string"
},
"products": [
{
"id": "string",
"name": "string",
"price": 0,
"quantity": 2147483647,
"returned": 2147483647,
"url": "string",
"imageUrl": "string",
"category": "string",
"productAttributes": [
{
"name": "string",
"value": "string"
}
]
}
],
"orderAttributes": [
{
"name": "string",
"value": "string"
}
]
}
}
401: Unauthorized
The request was missing an API key, or you are requesting access to information that you do not have permission to access. Sample response syntax:
{
"type": "string",
"title": "string",
"status": 0,
"substatus": "CustomerInvalidModelState",
"detail": "string",
"instance": "string"
}
404: Not found
The data you are looking for is not on the server. Sample response syntax:
{ "type": "string",
"title": "string",
"status": 0,
"substatus": "CustomerInvalidModelState",
"detail": "string",
"instance": "string"
}
PUT method – adding an order that has not been registered in the platform
The method is used to add order details that have not been registered in the platform.
The PUT method is used to change the status of an order registered in ExpertSender. For a correct query using the PUT method, you will receive a response with a ‘read-only’ status.
PUT method – query
To send a query using this method, it must contain:
- Server address (endpoint): https://api.ecdp.app/orders/status
- Parameters:
Parameter | Type | Category | Description |
x-api-key | string | header | Unique API key available in Settings > API |
orderId* | string | body | Order ID number; minimum number of characters: 1 |
orderStatus* | string | body | Order status; minimum number of characters: 1 |
Query syntax for the PUT method
Below, you can see an example syntax of the query that can be used to change the order status:
{
"orderId": "string",
"orderStatus": "string"
}
PUT query response codes
200: Success
The query was processed, the server returned a response.
400: Bad request
The request was not processed. The reason is usually a missing or incorrect parameter. Sample response syntax:
{
"type": "string",
"title": "string",
"status": 0,
"substatus": "CustomerInvalidModelState",
"detail": "string",
"instance": "string",
"errors": [
"string"
]
}
401: Unauthorized
The request was missing an API key, or you are requesting access to information that you do not have permission to access. Sample response syntax:
{
"type": "string",
"title": "string",
"status": 0,
"substatus": "CustomerInvalidModelState",
"detail": "string",
"instance": "string"
}
DELETE{id} method – changing the order status to IsDeleted
The PUT method is used to change the status of an order registered in ExpertSender to Deleted (IsDeleted).
For a correct query using the PUT method, you will receive a response with a ‘read-only’ status.
DELETE method – query
To send a query using this method, it must contain:
- Server address (endpoint): https://api.ecdp.app/orders/{orderId}
- Order ID: Order ID number
- API key: Your API key, found in Settings > API.
The correct API query to change the status of order number 12 to Deleted looks like this: https://client.ecdp.app/orders/{12}
DELETE query response codes
200: Success
The query was processed, the server returned a response. Sample response syntax:
{
"status": 0,
"data": {
"id": "string",
"date": "2024-07-25T10:10:53.036Z",
"timeZone": "string",
"websiteId": 0,
"status": "string",
"currency": "str",
"totalValue": 0,
"returnsValue": 0,
"customer": {
"id": 0,
"email": "string",
"phone": "string",
"crmId": "string"
},
"products": [
{
"id": "string",
"name": "string",
"price": 0,
"quantity": 2147483647,
"returned": 2147483647,
"url": "string",
"imageUrl": "string",
"category": "string",
"productAttributes": [
{
"name": "string",
"value": "string"
}
]
}
],
"orderAttributes": [
{
"name": "string",
"value": "string"
}
]
}
}
401: Unauthorized
The request was missing an API key, or you are requesting access to information that you do not have permission to access. Sample response syntax:
{
"type": "string",
"title": "string",
"status": 0,
"substatus": "CustomerInvalidModelState",
"detail": "string",
"instance": "string"
}
404: Not found
The data you are looking for is not on the server. Sample response syntax:
{
"type": "string",
"title": "string",
"status": 0,
"substatus": "CustomerInvalidModelState",
"detail": "string",
"instance": "string"
}