Label Requests

POST https://your-domain.com/path-to-labels

Evance will send your Shipping Service label printing requests during the dispatch process if your Shipping Service offers label printing services and supplied the "labelsUrl" when adding your Shipping Service.

It is important to note that a Label Request constitutes an order for a delivery label to be applied to a box and its tracking data. The Merchant's account with the Shipping Provider will be charged. However, if you have quoted Landed Costs during a Rate Request, these costs may be invoiced separately by your Shipping Provider during/after transit and not at the point of requesting a label.

The JSON we post to you

Evance will send a POST request to your Shipping Service when an administrator wishes to request a label for a delivery.

{
   "delivery":{
      "width":500,
      "height":250,
      "depth":500,
      "weight":10000,
      "currency":"GBP",
      "serviceCode":"ups-worldwide-saver",
      "origin":{
         "id":985,
         "title":"",
         "firstname":"",
         "lastname":"",
         "company":"Tobys Tackle",
         "line1":"2 Sorrel Horse Mews",
         "line2":"Grimwade Street",
         "line3":"",
         "city":"Ipswich",
         "region":"Suffolk",
         "country":"United Kingdom",
         "countryCode":"GB",
         "zip":"IP4 1LN",
         "latitude":52.05345,
         "longitude":1.162921,
         "isPrimary":false,
         "phone":"01473 694 500"
      },
      "destination":{
         "id":1424,
         "title":"",
         "firstname":"Andrew",
         "lastname":"Matthew",
         "company":"Evance",
         "line1":"13 Rue des Quartillons",
         "line2":"",
         "line3":"",
         "city":"Yssac-la-Tourette",
         "region":"Puy-de-D\u00f4me",
         "country":"France",
         "countryCode":"FR",
         "zip":"63200",
         "latitude":45.936254,
         "longitude":3.094035,
         "isPrimary":false,
         "phone":"01473694500"
      },
      "items":[
         {
            "quantity":"10",
            "reference":"T-RED-001-S",
            "commodityCode":"2204109800",
            "priceExcTax":83.33,
            "priceIncTax":100,
            "title":"Red Polo T-Shirt"
         }
      ]
   }
}

Delivery properties explained

Let's go over the properties supplied within the "delivery" wrapper.

currency	The ISO-3 code for the currency of the items within the Delivery (e.g. 'GBP' for Pounds Sterling).
depth	The outer depth/length dimension of the box for delivery in millimetres (mm).
destination	The destination address of the delivery. The properties within this object should be fairly self explanatory.
dispatchDate	The estimated dispatch date for the delivery is provided in year-month-day (Y-m-d) format. Evance specifies the estimated dispatch date from which you're able to calculate an estimated delivery date.
height	The outer height dimension of the box for delivery in millimetres (mm).
items	An array of items contained within the delivery. The information supplied for items does not reflect full Product data. We've cut down the amount of information to that required for shipping calculations. You may require this information to: calculate insurance based on the value of items within the delivery calculate landed costs or other duties for cross-border selling
items[].commodityCode	The HS Tariff code or international commodity code for Products being delivered. This is a requirement for calculating landed costs for cross-border selling.
items[].currency	The currency applicable to the `"priceExcTax"` and `"priceIncTax"` properties of this Item.
items[].id	Evance's System ID for the Product being delivered.
items[].priceExcTax	A string containing the total sale value for the quantity of this Product as a decimal, excluding sales tax. The decimal format is subject to the currency.
items[].priceIncTax	A string containing the total sale value for the quantity of this Product as a decimal, including sales tax. The decimal format is subject to the currency.
items[].quantity	The quantity of this product contained within the delivery.
items[].sku	The Stock Keeping Unit code for the Product.
items[].title	The title of the Product.
items[].weight	The total weight for the quantity of this Product in grams (g).
origin	The address of the Warehouse this delivery will be sent from. The properties within this object should be fairly self explanatory.
serviceCode	The postage option's unique identifier used by your App. This is the same as the `serviceCode` your App supplied in its response to the Rate Request.
weight	The total gross packaged weight of the box being delivered in grams (g).
width	The outer width of the box being delivered in millimetres (mm).

Validating requests from Evance

Your App should validate requests from Evance. Evance's service requests supply security Headers similar to those when Validating Webhooks.

The JSON you send back to us

Evance expects your Shipping Service to respond to a Label Request with a JSON response:

{
    "label": {
        "currency": "GBP",
        "image": "data:image/gif;base64,R0lGODdheAUgA+/...BASE64_ENCODED.../+CjsPgo=",
        "priceExcTax": "142.91",
        "priceIncTax": "171.49",
        "trackingNumber": "1Z7661V20419018125"
   }
}

Label properties explained

Let's go over the properties supplied within the "label" wrapper.

currency	The currency returned should be the same as the currency requested (e.g. `GBP`).
image	Represents an image of the label, which may be one of the following formats: `image/gif` `image/jpeg` `image/png` The value contained may be either: An absolute URL to an image (e.g. `https://my-app.com/path-to-image.png`) A data URI with a base64 encoded string representing the image data, such as `"data:image/png;base64,"`. A base64 encoded string representing the image data (not a data URI).
priceExcTax	The price for the label excluding taxes.
priceIncTax	The price for the label including taxes.
trackingNumber	The delivery tracking number from the Shipping Provider.

A typical App integration

Typically, an App will be used as a piece of middleware between Evance and a Shipping Provider. In this scenario the integration flow may look similar to:

Step 1: Label request from Evance to your App

Evance will send your App a single Label Request for a single box of one or more products to be dispatched (see The JSON we post to you).

Step 2: Request to ship from your App to your Shipping Provider

Your App will must convert Evance's data into a format your Shipping Provider will understand to order a shipment label for collection and delivery. We try to provide enough information about the Delivery, and the items within the box, so that your Shipping Provider has enough information to avoid shipping complications. if you discover you are missing information we encourage you to contact us.

Step 3: Label response from the Shipping Provider to your App

Your Shipping Provider will respond to your Ship Request with an order/label response which may include tracking and box labelling data. If your original Rate Request included Landed Costs for cross-border selling, the cost may not be included within the label data returned. Most Shipping Providers will invoice Landed Costs separately from a Label Request.

Step 4: Label response from your App to Evance

Your App must convert the data returned from your Shipping Provider into costs, tracking information and label data Evance will understand (see The JSON you send back to us). Label data may include an image of the Label for printing.

Step 5: Label and/or tracking recorded and presented for printing

Evance will store and present relevant tracking information, shipping costs and/or a label image depending on the information available within your response. Please note, if your original Rate Request included Landed Costs, Evance will use this value as the Shipping Cost for the shipment for the purposes of cost analysis. At this time the cost of duties and shipping are not separated.