Orders
This is used to view, create, update and delete orders.
Order Properties
| id |
{ "id" : 255 }
The unique ID of the order |
| reference |
{ "reference" : 1001 }
The business account's reference for the order (order ID) |
| created |
{ "created" : "Mon, 23 Nov 2015 18:42:29 +0000" }
The date the order was created |
| archived |
{ "archived" : false }
Either true or false (whether the order is archived) |
| trackingUrl |
{ "trackingUrl" : "http://www.royalmail.com/tracking-id=ABC123" }
The value for the trackingUrl field (usually a tracking Url for the shipment but can relate to anything) |
| status |
{ "status" : { "id": 1381, "name": "Paid", "type": "paid" } }
The status of the order. Contains the Order Status ID, Name and Type. The order status type is either paid, unpaid, cancelled, shipped or custom. |
| billingAddress |
{ "billingAddress" : {
"name": "...",
"emailAddress": "...",
"telephone": "...",
"companyName": "...",
"addressLine1": "...",
"addressLine2": "...",
"addressLine3": "...",
"city": "...",
"postcode": "...",
"province": "...",
"country": "..."
}
}
The order's billing address. Where the country is USA the province field will be substituted with state. |
| shippingAddress |
{ "shippingAddress" : {
"name": "...",
"emailAddress": "...",
"telephone": "...",
"companyName": "...",
"addressLine1": "...",
"addressLine2": "...",
"addressLine3": "...",
"city": "...",
"postcode": "...",
"province": "...",
"country": "..."
}
}
The order's shipping address. Where the country is USA the province field will be substituted with state. |
| paymentMethod |
{ "paymentMethod" : "SagePay" }
The payment method of the order, e.g. PayPal, SagePay, eBay, Amazon |
| total |
{ "total" : 132.00 }
The grand total of the order (including shipping) |
| subTotal |
{ "subTotal" : 100.00 }
The products subtotal for the order (excluding discounts), if tax is charged then it should be excluding tax |
| shippingTotal |
{ "shippingTotal" : 9.95 }
The total cost of shipping after any shipping discounts were applied |
| originalShippingTotal |
{ "originalShippingTotal" : 19.95 }
The total cost of shipping before any shipping discounts were applied |
| partialPaymentTotal |
{ "partialPaymentTotal" : 10.00 }
The total amount of partial payments (e.g. gift voucher or reward points) made on the order |
| tax |
{ "tax" : { "type": "vat", "value": 22.00 } }
The total tax on the order (products and shipping taxes) |
| discounts |
{ "discounts": [
{
"name": "Voucher Code (10%)",
"value": 0.9588,
"type": "voucher",
"code": "10PERCENT"
}
]
}
Any discounts received on the order |
| fees |
{ "fees": [
{
"name": "Payment Gateway Fee",
"value": 0.85,
"type": "payment_gateway"
}
]
}
The transaction fee on the order |
| shipping |
{ "shipping": [
{
"name": "First Class",
"value": 10.00,
"id": 1,
"vatRate": 20
}
]
}
The shipping rate used for the order, if tax is charged the value is excluding tax |
| refunds |
{ "refunds" : [
{
"name": "Shoes Returned",
"value": 1
},
{
"name": "Coat Returned",
"value": 2
}
]
}
Any refunds applied to the order |
| products |
{ "products" : [
{
"id": 168397,
"title": "Product Title",
"sku": "SKU101",
"price": 100.00,
"originalPrice": 120.00,
"quantity": 1,
"vatRate": 20,
"comments": "engrave with I love Jim",
"weight": 1.3,
"warehouseNotes": "ABC1",
"hsCode": "3000010101"
}
]
}
The products ordered, if tax is charged then the price should be listed without tax The price property returns the price paid for the product after discounts were applied The originalPrice property returns the price of the product before discounts If the ordered product is a bundle then use embed=bundle_products to return the products part of the bundle (the response will contain the title and sku for each constituent product). |
| totalWeight |
{ "totalWeight": "30kg" }
|
| acceptsMarketing |
{ "acceptsMarketing": true }Either true or false (whether the customer accepts marketing or not) |
| comments |
{ "comments": "please deliver on Tuesday" }
The comments attached to the order |
| adminComments |
{ "adminComments": [
{
"id": 618713,
"created": "Wed, 27 Jun 2018 09:49:02 +0000",
"content": "Customer called to chase delivery",
"status_id": 127
}
]
}
Any admin comments added to the order (the status_id represents the curreent status of the order) Present only when embed=admin_comments |
| customer |
{ "customer": { "id": 12345 } }
The customer ID, returned when an order is created |
| deliveryDate |
{ "deliveryDate": "26/07/2018" }
The delivery date requested by the customer |
| transactionId |
{ "transactionId": "0HJ384JKL227GG" }
The transaction ID returned by the payment gateway (note, not all gateways return a transaction ID) |
| earnedRewardPoints |
{ "earnedRewardPoints": 30 }
The number of reward points earned by the customer for the order |
The products, status, shippingRate and sendEmails properties are only available when creating an order (they override normal properties).
| shippingRate |
{ "shippingRate" : 1 }
The ID of the shipping rate |
| sendEmails |
{ "sendEmails" : true }
Either true or false (whether to send an order confirmation email to the customer |
What you can do with orders
GET /v1/orders
Receive a list of all orders
GET /v1/orders/count
Count the number of orders
GET /v1/orders/ID
Receive a single order
POST /v1/orders
Create a new order
POST /v1/orders/ID/status
Update an order's status
DELETE /v1/orders/ID
Delete an order
GET /v1/orders
Returns all orders. By default the first 50 regular orders are returned, sorted by creation date.
The ids parameter can be used to return specific orders (limited to 50).
| fields | Comma separated list of properties to include |
| sort | date or date_desc |
| archived | 0 or 1 |
| status | Order Status ID |
| from | From date created (UNIX timestamp) |
| to | To date created (UNIX timestamp) |
| count | Count |
| offset | Offset |
GET /v1/orders
HTTP/1.1 200 OK
[
{
"id": 1,
"reference": 1,
"created": "Mon, 23 Nov 2015 18:42:29 +0000",
"archived": false,
"trackingUrl": "",
"status": {
"id": 1,
"name": "Paid",
"type": "paid"
},
"billingAddress": {
"name": "...",
"emailAddress": "...",
"telephone": "...",
"companyName": "...",
"addressLine1": "...",
"addressLine2": "...",
"addressLine3": "...",
"city": "...",
"postcode": "...",
"province": "...",
"country": "..."
},
"shippingAddress": {
"name": "...",
"emailAddress": "...",
"telephone": "...",
"companyName": "...",
"addressLine1": "...",
"addressLine2": "...",
"addressLine3": "...",
"city": "...",
"postcode": "...",
"province": "...",
"country": "..."
},
"paymentMethod": "SagePay",
"total": 132.00
}
]
GET /v1/orders/count
Returns a count of the orders.
| archived | 0 or 1 |
| status | Order Status ID |
| from | From date created (UNIX timestamp) |
| to | To date created (UNIX timestamp) |
GET /v1/orders/count
HTTP/1.1 200 OK
{
"count": 99
}
GET /v1/orders/ID
Returns a single order.
| fields | Comma separated list of properties to include |
| embed | admin_comments |
GET /v1/orders/1
HTTP/1.1 200 OK
{
"id": 255,
"reference": 1001,
"created": "Mon, 23 Nov 2015 18:42:29 +0000",
"archived": false,
"trackingUrl": "",
"status": {
"id": 1,
"name": "Paid",
"type": "paid"
},
"billingAddress": {
"name": "...",
"emailAddress": "...",
"telephone": "...",
"companyName": "...",
"addressLine1": "...",
"addressLine2": "...",
"addressLine3": "...",
"city": "...",
"postcode": "...",
"province": "...",
"country": "..."
},
"shippingAddress": {
"name": "...",
"emailAddress": "...",
"telephone": "...",
"companyName": "...",
"addressLine1": "...",
"addressLine2": "...",
"addressLine3": "...",
"city": "...",
"postcode": "...",
"province": "...",
"country": "..."
},
"paymentMethod": "SagePay",
"total": 132.00,
"subTotal": 100.00,
"shippingTotal": 10.00,
"originalShippingTotal": 10.00,
"tax": {
"type": "vat",
"value": 22.00
},
"shipping": [
{
"name": "First Class",
"value": 10.00,
"id": 1,
"vatRate": 20
}
],
"products": [
{
"id": 1238473,
"title": "Nike Airmax Trainers",
"sku": "",
"price": 100.00,
"quantity": 1,
"vatRate": 20,
"weight": 1.3,
"extras": [
{
"name": "Free Laces",
"value": 0.00
}
],
"variation": [
{
"name": "Size",
"value": "UK9"
},
{
"name": "Colour",
"value": "Black/White Trim"
}
],
"comments": "please engrave with I love Jim"
}
],
"totalWeight": "1.3kg",
"customer": {
"id": 143316
}
}
POST /v1/orders
Creates a new order.
| billingAddress | required |
| shippingAddress | required |
| province/state |
when the country is USA the state attribute must be set using a valid state ID see https://api.ecommerceapi.uk/v1/countries/223?embed=states |
| products | required |
| status | required |
| shippingRate | required |
| reference |
optional if specified it must be unique (an error will not be returned if the reference supplied is not unique) |
POST /v1/orders
POST /v1/orders
{
"status": 1,
"billingAddress": {
"name": "...",
"emailAddress": "...",
"telephone": "...",
"companyName": "...",
"addressLine1": "...",
"addressLine2": "...",
"addressLine3": "...",
"city": "...",
"postcode": "...",
"province": "...",
"country": 222
},
"shippingAddress": {
"name": "...",
"emailAddress": "...",
"telephone": "...",
"companyName": "...",
"addressLine1": "...",
"addressLine2": "...",
"addressLine3": "...",
"city": "...",
"postcode": "...",
"province": "...",
"country": 222
},
"products": [
{
"id": 1,
"quantity": 1,
"variation": 1,
"extras": [1, 2],
"choices": [3],
"comments": "I would like green laces"
}
],
"shippingRate": 1,
"comments": "please deliver on Tuesday"
}
POST /v1/orders
HTTP/1.1 201 Created
{
"id": 1,
"reference": 1,
"created": "Mon, 23 Nov 2015 18:42:29 +0000",
"archived": false,
"trackingUrl": "",
"status": {
"id": 1,
"name": "Paid"
},
"billingAddress": {
"name": "...",
"emailAddress": "...",
"telephone": "...",
"companyName": "...",
"addressLine1": "...",
"addressLine2": "...",
"addressLine3": "...",
"city": "...",
"postcode": "...",
"province": "...",
"country": "..."
},
"shippingAddress": {
"name": "...",
"emailAddress": "...",
"telephone": "...",
"companyName": "...",
"addressLine1": "...",
"addressLine2": "...",
"addressLine3": "...",
"city": "...",
"postcode": "...",
"province": "...",
"country": "..."
},
"paymentMethod": "Admin Order",
"total": 132.00,
"subTotal": 100.00,
"tax": {
"type": "vat",
"value": 22.00
},
"shipping": [
{
"name": "First Class",
"value": 10.00,
"id": 1
}
],
"comments": "please deliver on Tuesday",
"products": [
{
"title": "Nike Airmax Trainers",
"sku": "",
"price": 100.00,
"quantity": 1,
"extras": [
{
"name": "Free Laces",
"value": 0.00
}
],
"variation": [
{
"name": "Size",
"value": "UK9"
},
{
"name": "Colour",
"value": "Black/White Trim"
}
],
"choices": [
{
"name": "Material",
"value": "Wood",
}
],
"comments": "I would like green laces"
}
],
"totalWeight": "1.3kg",
"customer": {
"id": 143316
}
}
POST /v1/orders/ID/status
Update an order's status.
Returns 200 OK on success.
| sendEmail | Either true or false (whether to send an order status update email to the customer) |
| status | the new status ID |
| trackingUrl | the new value for the tracking URL field |
| sendToEbay | set to true to send the updated order status to ebay |
| eBayShippingCarrier | the value for the ebay shipping carrier |
| eBayShipmentTrackingNumber | the value for the ebay shipping tracking number |
POST /v1/orders/1/status
POST /v1/orders/1/status
{
"sendEmail": true,
"status": 2,
"trackingUrl": ""
}
DELETE /v1/orders/ID
Deletes an existing order.
Returns 204 No Content on success.