Merchant orders
Changelog
Prerequisites
API key access
The Merchant Order API can be accessed through a shared secret: apiKey. This method requires adding apiKey param to each request, e.g.:
GET https://t3-prod-api.tipser.com/v3/merchants/orders/5b83a2199d25800e649a5d5d?apiKey=xxx
Standard authorisation
The merchant order API can also be accessed through the standard Tipser Authentication API.
Fetching list of orders
The following endpoint allows to fetch orders for a merchant (identified thanks to Authorization header or additional param apiKey):
GET https://t3-prod-api.tipser.com/v3/merchants/orders?from=2018-05-31&states=0,1
The obligatory parameters are: from (in format yyyy-mm-dd) and states. States are defined in the following table:
The optional params are: to, pageSize, pageIndex. All params are described in the following table:
Example of a response:
Fetching details of an order
Details of a single order are returned from the following request:
GET https://t3-prod-api.tipser.com/v3/merchants/orders/:orderId
Last element on the path is ID of the requested order (taken e.g. from the orders list)
Example of a response:
{ "id":"5be5e8c4ac564b000165003f", "orderNumber":"21660", "orderDate":"2018-11-09T20:06:28.853Z", "status":3, "customer":{ "firstName":"John", "lastName":"Doe", "email":"5be5e8c4ac564b000165003d@mailinator.com", "phoneNumber":"Doe", "homeAddress":{ "streetAddress":"1600 Pennsylvania Ave NW", "zipCode":"DC 20500", "city":"Washington", "country":"US" }, "deliveryAddress":{ "streetAddress":"1600 Pennsylvania Ave NW", "zipCode":"DC 20500", "city":"Washington", "country":"US" }, "useHomeAddressAsDeliveryAddress":false }, "items":[ { "id":"5be5e8c4ac564b000165003e", "productId":"5aa16508c0bdfb2ca4045088", "sku":"8809389031511", "productName":"POMEGRANATE", "amount":1, "quantity":1, "attributesValue":"", "status":2, "nextStatuses":[ 4 ], "merchantProductId":"185851052051", "totalPriceIncVat":{ "value":39.9, "currency":"EUR", "formatted":"39,90 €" }, "totalPriceExVat":{ "value":33.53, "currency":"EUR", "formatted":"33,53 €" }, "vatValue":{ "value":6.37, "currency":"EUR", "formatted":"6,37 €" }, "merchantPriceIncVat":{ "value":27.93, "currency":"EUR", "formatted":"27,93 €" }, "merchantPriceExVat":{ "value":23.47, "currency":"EUR", "formatted":"23,47 €" } } ], "shippingPreferences":{ "shippingProvider":"DHL", "sendDeliveryNoteToCustomer":true }, "shippingLines":{ "priceIncVat":{ "value":0, "currency":"EUR", "formatted":"0 €" }, "priceExVat":{ "value":0, "currency":"EUR", "formatted":"0 €" }, "vatValue":{ "value":0, "currency":"EUR", "formatted":"0 €" } }, "activityLogs":[ { "messageType":2, "date":"2018-11-12T20:30:09.546Z", "text":{ "changedProducts":[ { "name":"POMEGRANATE", "productVariantId":"5aa16508c0bdfb2ca4045088", "productAttributes":[] } ], "newState":"Shipped", "trackingLink":"", "comment":"Merchant integration" } }, { "messageType":4, "user":"Order integration", "date":"2018-11-10T14:35:32.730Z", "text":{ "updateType":"Placed", "success":true, "response":"id: 667754856511" } } ]}
Providing information about shipping
Order can be updated by shipping information and at the same time optionally customer can be notified about this change using the following request:
POST https://t3-prod-api.tipser.com/v3/merchants/orders/:orderId/shipping
Body:
{
"shippingProvider":string,
"comment":string,
"sendDeliveryNoteToCustomer":boolean,
"trackingNumber":string,
"orderItemsIds":[
string
]
}
where one before last path element is the ID of the order.
Supported shipping providers are defined in market request (in proper market section):
GET https://t3-prod-api.tipser.com/v3/markets
If preferred shipping provider is not found there, one can use null value as shippingProvider, it will be then treated as "other" shipping provider.
Updating order status
Order status can be updated using the following request:
PUT https://t3-prod-api.tipser.com/v3/merchants/orders/:orderId
Body:
{
"status":integer,
"orderItemsIds":[
string
],
"comment":string
}
Partial update of the order
The order update API can update each line item separately using the items.id in the orderItemsIds
{
"status":1,
"orderItemsIds":["5bc9dbf7fe887c00014f3f52"],
"comment":"Testing to set the status to hold!"
}
Next statuses for the order
where the last path element is the ID of the order. Field status of the order item must be in line with field nextStatuses of this order item (see above example of a response for order details). Meaning of order item statuses are as follows:
For instance, if we have the following response for order details:
{
"id":"5b7bd6e79d25801804f04d3b",
"orderNumber":"15645",
"orderDate":"2018-08-21T09:09:59.486Z",
"status":0,
"customer":{
"firstName":"aaaa",
[...]
},
"useHomeAddressAsDeliveryAddress":false
},
"items":[
{
"id":"5b7bd6e79d25801804f04d3a",
"productId":"50c0e73c5c3d091434743f53",
[...]
"status":0,
"nextStatuses":[
1,
2,
3,
6
]
}
],
"shippingPreferences":{
"shippingProvider":"Post Nord",
"sendDeliveryNoteToCustomer":true
},
"activityLogs":[
]
}
then for order 5b7bd6e79d25801804f04d3b and order item 5b7bd6e79d25801804f04d3a we can only set status 1, 2, 3 or 6 (Hold, Shipped, Cancelled, Acknowledged)