Rate Requests
POST https://your-domain.com/path-to-rates
Evance will send Shipping Service rate requests during the checkout process to obtain available postage options for a delivery and their associated costs. This will be sent as a POST request to the Rates URL you specified when you added your Shipping Service.
It is important to note that a Rate Request represents a quotation for shipping from the Shipping Provider. The Merchant's
account with the Shipping Provider must not be charged for this request.
A user's cart may be broken down into multiple deliveries. How this is achieved is governed by product packaging settings, available boxes and shipping settings for the Account. Each delivery posts a separate Rate Request to your Shipping Service whenever shipping costs need to be calculated. Evance will then aggregate available postage options and the total costs for each.
The JSON we post to you
Evance will send a POST request which includes a payload with a "delivery" object.
{
"delivery": {
"width": 1030,
"height": 530,
"depth": 1000,
"weight": 850,
"currency": "GBP",
"origin": {
"id": 552,
"firstname": "",
"lastname": "",
"company": "Evance",
"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": true
},
"destination": {
"id": 1398,
"firstname": "Toby",
"lastname": "Wilson",
"company": "Tobys Tackle",
"line1": "154 Buena Vista Way",
"line2": "",
"line3": "",
"city": "Nottingham",
"region": "Nottinghamshire",
"country": "United Kingdom",
"countryCode": "GB",
"zip": "NG1",
"latitude": 52.683916,
"longitude": -0.922509,
"isPrimary": true
},
"items": [
{
"id": "1695",
"sku": "T-RED-001-S",
"commodityCode": "2204101100",
"title": "Red Polo T-Shirt",
"quantity": 1,
"weight": 750,
"priceExcTax": "8.33",
"priceIncTax": "10.00",
"currency": "GBP"
}
],
"dispatchDate": "2018-03-15"
}
}
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:
|
| 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. |
| 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 Rate Request with a JSON response:
{
"rates": [
{
"serviceCode": "ups-worldwide-express-plus",
"title": "UPS Worldwide Express Plus",
"description": "Includes costs of shipping and any applicable landed costs \/ duties.",
"currency": "GBP",
"priceExcTax": 146.72,
"priceIncTax": 169.29,
"minDeliveryDate": "2018-05-22",
"maxDeliveryDate": "2018-05-22"
},
{
"serviceCode": "ups-express",
"title": "UPS Express",
"description": "Includes costs of shipping and any applicable landed costs \/ duties.",
"currency": "GBP",
"priceExcTax": 89.72,
"priceIncTax": 100.89,
"minDeliveryDate": "2018-05-22",
"maxDeliveryDate": "2018-05-22"
}
]
}
Rates properties explained
Let's go over the properties supplied within the "rates" array.
Each element within the rates array must represent a delivery/postage option. In the example above you will note that we're returning two UPS postage options from a custom Shipping Service.
| currency | The currency returned should match the currency requested. However, if it does not match Evance will attempt
to convert the "priceExcTax" and "priceIncTax" properties to the requested currency. |
| description | The description for the postage/delivery option will be presented to customers at checkout when choosing a shipping option. |
| maxDeliveryDate | The maximum estimated date of delivery. If you are supplying delivery dates, please ensure you calculate your
delivery date based upon the "dispatchDate" sent to you during the Rate Request. |
| minDeliveryDate | The soonest delivery date possible for the delivery. If you are supplying delivery dates, please ensure
you calculate your delivery date based upon the "dispatchDate" sent to you during
the Rate Request.
|
| priceExcTax | The total cost of shipping as a decimal value appropriate to the currency, excluding sales tax. |
| priceIncTax | The total cost of shipping as a decimal value appropriate to the currency, including sales tax. |
| serviceCode | The unique service code/reference your Shipping Service uses to recognise this postage method. |
| title | The title of the postage option to be presented to the customer at checkout when choosing a shipping option. |
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: Rate request from Evance to your App
Evance prepares and sends a Rate Request to your App for each delivery (see The JSON we post to you).
Step 2: Rate request from your App to your Shipping Provider
Your App must translate the JSON payload into a Rate Request your Shipping Provider can understand. We try to provide enough information about the Delivery, and the items within the box, so that your Shipping Provider has enough information to return accurate quotations. If you discover you are missing information we encourage you to contact us.
Step 3: Rate response from the Shipping Provider to your App
Your Shipping Provider will return Rate Data based on your request. Unfortunately, we cannot offer technical or development support on behalf of third party providers. You should consult your Shipping Provider's API documentation for full details on their data formats.
Step 4: Decide whether to include Landed Costs
If your Shipping Provider offers Landed Cost calculations for cross-border duties, you may decide to include these costs within the data you return to Evance. This may require several additional requests to your Shipping Provider's API. But, will offer users the full imported cost of goods into their country, for which the Merchant will be responsible for paying. You should be aware that your Shipping Provider may invoice Landed Cost separately from the cost of shipping.
Step 5: Landed Cost responses
The Shipping Provider will calculate Landed Costs and return these to you in response with Duty data. It is important to note that Landed Costs may be charged separately from Shipping Costs by your Shipping Provider. Your provider may also issue questions based on your request which your App must respond to before a Landed Cost may be fully calculated.
Step 6: Combine data and send your response
Your App must include the Shipping and Landed Costs as appropriate to The JSON you send back to us.
Step 7: Postage options offered to users
Evance will collate all Shipping Calculations for each delivery and present all commonly available Postage options to the user.
Why can't I see my Shipping Calculations?
There are a number of reasons why you may not be able to see your Shipping Calculations from your App during checkout. You should check:
- Your App is throwing an internal Server Error
To aid a smooth checkout for our users, Evance will silently ignore errors generated by your App during shipping calculations. You should check your own server logs to determine if you are encountering an during a request.
- Product data may be missing in Evance
Your App may not be able to calculate shipping costs if some data is not available to you. You should check that the items in your cart have the appropriate amount of data for your App to calculate shipping costs. For example, your App may require packed dimensions, weight or commodity codes to provide calculations. You should ensure your App's requirements are communicated to Merchants so that data may be maintained as appropriate.
- Delivery data may be missing
Your App may require delivery information which is not available to you. You should check that you are receiving the correct box dimensions and weight, as well as complete origin and destination addresses. You should correct this information as appropriate.
- Destination address unavailable or inaccurate
You should ensure that the destination address supplied to your App is complete and that your Shipping Provider supports the destination supplied.
- Origin address unavailable or inaccurate
Evance will send your App an origin address based on Warehouse data. You should check that the Warehouse assigned to the Shipping Service calculation in Evance has an appropriate address.
- Shipping Service not set-up in a Shipping Calculator
Your shipping service calculations are not automatically available to all products. Each product is assigned to a Shipping Calculator. You should ensure that your Shipping Service has been defined within the Shipping Calculator for all appropriate products.
- Shipping calculations are not commonly available
If your cart contains products spanning more than one Shipping Calculator you should ensure that your Shipping Service is available across all Shipping Calculators within the Evance control panel.
Why are prices different to what I expected?
The most common reasons prices are not what you expected are:
- Incorrect origin address
You should double check the origin address is correct. - Shipping cost modifiers
Evance allows administrators to add a fixed value and/or percentage modifier to any costs you provide. You should check if this is the case and retest. - Inaccurate product data
it is common for product data to either be missing or inaccurate. We recommend checking all products in your cart have appropriate settings to perform the calculations within your App. - Box data has not been set-up
If you were expecting more than one delivery, or even if you aren't, but your cost of deliveries are not accurate, check that boxes and their appropriate constraints have been added to your Evance control panel. - Shipping Provider account related costs
You should check that you are providing correct account information to your Shipping Provider as this may alter the shipping rates supplied to your App.