Merchant orders

Changelog

Date 31.08.2018
DescriptionInitial version of the API
Author Andrzej Bednarz
18.09.2018
apiKey added as authentication method and quantity instead of amount in order item json
Andrzej Bednarz
31.01.2019
Updated sample response with new prices fields (totalPrice, merchantPrice, vatValue)
Andrzej Bednarz

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:


{ "itemsCount":1, "pageIndex":0, "items":[ { "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" } } ]} ]}

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)

Sandbox access

The Merchant Order API can be used with the Tipser Sandbox environment by replacing all calls to the URL

https://t3-prod-api.tipser.com

With the sandbox environment:

https://t3-stage-api.tipser.com