Skip to content

Orders – API methods 

Using API, you can automate activities related to orders placed by your customers. We provide 3 HTTP methods: 

  1. POST – Adding a new order or updating order data. 
  2. GET  – Obtaining information about an order using the order ID number. 
  3. PUT – Adding an order that has not been registered in the platform. 
  4. 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: 

  1. Server address (endpoint): https://api.ecdp.app/orders  
  2. Parameters
Parameter Type Category Max character countDescription 
x-api-key*string header Your API key, which you can find in Settings > API. 
id*string body 128Order 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 countDescription 
email string 320Email address of the customer who placed the order 
phone string 20Telephone number of the customer who placed the order 
crmId string 128CRM ID number of the customer who placed the order 

For products these are: 

Parameter Type  Max character countDescription 
id* string 128ID number of the purchased product
name* string 2048Product 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 2048URL of the purchased product 
imageUrl string 2048Image URL of the purchased product 
category string 2048Category of the purchased product 
productAttributes  Product attributes; includes an additional set of parameters >>> see table below 

For productAttributes these are: 

Parameter Type  Character countDescription 
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 countDescription 
timeZonestring 100The timezone that the order was placed in. You can find the values for this parameter here: Supported time zones for orders
websiteIdinteger($int32) Integer($int32): The ID number of the store website where the order was placed
statusstring  The order status, which can be one of the following: placed, paid, completed, canceled
currencystring min: 3
max: 3
The currency in which the order was placed
returnsValuenumber($double)
The value of returned products
orderAttributesOrder attributes; includes an additional set of parameters >>> see table below 

For orderAttributes these are: 

Parameter Type  Max character countDescription 
name* string 256Order 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: 

  1. Server address (endpoint): https://api.ecdp.app/orders/{id} 
  2. Order ID: Order number 
  3. 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: 

  1. Server address (endpoint): https://api.ecdp.app/orders/status
  2. Parameters:
Parameter Type CategoryDescription 
x-api-keystringheaderUnique API key available in Settings > API
orderId* stringbodyOrder ID number; minimum number of characters: 1 
orderStatus*stringbodyOrder 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: 

  1. Server address (endpoint): https://api.ecdp.app/orders/{orderId} 
  2. Order ID: Order ID number 
  3. 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"
}
On this page
To top