How to Display Rates at Checkout

The Rates at Checkout (RaC) feature allows you to provide end customers with multiple shipping options before the order is placed. This feature can be easily integrated into your shopping website.

πŸ“˜

This guide covers the Rates at Checkout feature API integration into your custom website.

To learn more about the Rates at Checkout integration workflow for e-commerce platforms with list of supported stores, refer to our Shipping Rates at Checkout Feature Help Centre article.

Endpoint description

The RaC feature is available via the Rates API and requires the Rate authorisation scope.

POST https://api.easyship.com/2023-01/rates

In request body, this API method requires the shipment details below.

  1. Origin address is an origin address object. Use Addresses API to get the origin address object.
  2. Destination address is an address object from the data provided by the end customer. To make sure the customer’s address is valid and correct, use our Address Validation feature.
  3. Parcel details is a parcel object with the following required fields:
    • items β€” array of item objects describing items to be shipped. Item objects can be filled from scratch or assigned by product IDs in case you have pre-filled Products API
    • box β€” object with shipment packaging details. Box can be specified explicitly as a custom one or assigned by a slug from predefined options available via the Box API
    • total_actual_weight β€” total weight of a shipment in kilograms

In response, you will obtain the rates object containing an array of available couriers with their applicable shipment rates and additional data.

Courier rates are scored by Easyship and returned in ascending order by a total shipment charge and in descending order by best value for money. This array allows you to display the cheapest, fastest and best value for money options to your end customer.

International shipping

Depending on the shipment type and conditions, you can display different breakdown of costs at checkout for your end user. For international shipments, you may have the following duties payment options:

  1. Delivered Duty Unpaid (DDU) where the buyer is responsible for paying any taxes, duties, or import fees on the shipment.
  2. Delivered Duty Paid (DDP) where the seller is responsible for paying any taxes, duties, or import fees on the shipment.
    To learn more about DDP and DDU Incoterms, see our DDU vs. DDP: Understanding the Differences Help Centre article.
    DDP terms are different depending on whether your business uses the IOSS system or not.
  3. Import One Stop Shop (IOSS) is an electronic portal in the European Union that businesses can use to pay any Import VAT on commercial goods shipped into the EU, under the value of €150,00 (euros).

To learn more about IOSS system and how it will affect you as an international shipper, see our What is IOSS Help Centre article.

Refer to our How to Calculate Taxes and Duties API guide to obtain an easy-to-understand taxes and duties price breakdown.

Below, you will find the request and response body schemas, as well as complete request and response examples.

Request body parameters

Field nameData typeDescription
origin_addressObject (Address)Address object for shipment origin (Address API).
destination_addressObject (Address)Address object for shipment destination (Address API).
parcelsArray of objects:

items (Object)
box (Object)
total_actual_weight (Integer)
Shipment items:

The items object for shipment items

The box object for shipment packaging (Box API)

total_actual_weight of a shipment

Response body parameters

Field nameData typeDescription
courier_idStringCourier service identifier on the Easyship platform.
courier_nameStringName of the courier service.
courier_remarksStringAdditional details of the courier service.
descriptionStringShort courier service description.
full_descriptionStringFull courier service description.
easyship_ratingIntegerAverage ratings of the courier service provided by Easyship users and end customers.
cost_rankIntegerResult of the Easyship cost scoring for a specified shipment: 1 is the best option.
delivery_time_rankIntegerResult of the Easyship delivery time scoring based on minimal delivery time estimation: 1 is the best option.
tracking_ratingIntegerCourier’s rating based on number and accuracy of tracking details provided (from 1 to 5 in descending order).
value_for_money_rankIntegerCombined rank calculated by comparison of cost and delivery time ranks: 1 is the best option.
available_handover_optionsArray (Enum (String))Options provided by a courier for delivery handover:

dropoff
free_pickup
paid_pickup
incotermsEnum (String)Applicable Incoterms: DDU or DDP
max_delivery_timeIntegerUpper bound of the delivery window (working days).
min_delivery_timeIntegerLower bound of the delivery window (working days).
is_above_thresholdBooleanTrue if the purchase price of the shipment exceeds the customs threshold specified by an import country. In this case, the following charges will be applicable:

import_tax_charge
import_duty_charge
estimated_import_tax
If false, these charges will be 0.
currencyEnum (String)ISO-4217 three-letter alphabetic currency code.
payment_recipientEnum (String)Payment recipient for a shipment:

Easyship
EasyshipPayOnScan
Courier
discountObjectApplicable courier discount (amount or percentage):

amount β€” fixed discount amount

origin_amount β€” discount percentage
shipment_chargeNumberBase courier service charge.
shipment_charge_totalNumberSubtotal of the following charges:

shipment_charge
fuel_surcharge
residential_full_fee
residential_discounted_fee
remote_area_surcharge
additional_services_surcharge
oversized_surcharge
total_chargeNumberTotal charge including shipment_charge_total and all applicable fees, taxes and duties.
additional_services_surchargeNumberCharges applicable for additional delivery services (e.g. delivery confirmation).
ddp_handling_feeNumberAdditional fees for the DDP option: courier pays import taxes and duties on buyer’s behalf. DDP handling fee is not charged if the IOSS scheme is in place and an order value is less than 150 euro.
estimated_import_dutyNumberEstimated shipment import duty in case of DDU Incoterms.
estimated_import_taxNumberEstimated shipment import tax, in case of DDU Incoterms.
import_duty_chargeNumberShipment import duty for DDP Incoterms.
import_tax_chargeNumberShipment import duty for DDP Incoterms.
fuel_surchargeNumberFuel surcharge applicable for a shipment.
import_tax_non_chargeableNumberIOSS amount of import tax. This tax is not charged while shipping and is displayed for information purposes only.
insurance_feeNumberApplicable delivery insurance fee.
minimum_pickup_feeNumberMinimal estimated delivery pickup fee (for the paid_pickup handover option if available).
oversized_surchargeNumberSurcharge for an oversized package, if applicable.
provincial_sales_taxNumberState, province or local government taxes, if applicable.
remote_area_surchargeNumberTotal remote area surcharge for origin and destination areas (see remote_area_surcharges below).
remote_area_surchargesObjectAdditional surcharge payable if delivery is specified for distant areas (e.g. islands or highlands):

origin for a shipment origin
destination for a shipment destination

Both origin and destination objects include the following fields:

name β€” name of the distant area
base β€” amount payable
residential_discounted_feeNumberDiscounted fee provided by the courier if a recipient’s delivery address corresponds with their residential address.
residential_full_feeNumberFull fee payable if a recipient’s delivery address corresponds with their residential address.
sales_taxNumberNational government sales tax.
warehouse_handling_feeNumberFee added by a fulfilment service for warehouse operations.
other_surchargesObjectOther applicable surcharges:

total_fee β€” total amount of other surcharges

details:

name β€” surcharge name
fee β€” surcharge amount in the currency of the shipment
origin_fee β€” surcharge amount in the currency of the origin country
rates_in_origin_currencyObjectFees and charges in the currency of the shipment origin country:

currency
shipment_charge
shipment_charge_total
total_charge
additional_services_surcharge
ddp_handling_fee
estimated_import_duty
estimated_import_tax
import_duty_charge
import_tax_charge
fuel_surcharge
import_tax_non_chargeable
insurance_fee
minimum_pickup_fee
oversized_surcharge
provincial_sales_tax
remote_area_surcharge
residential_discounted_fee
residential_full_fee
sales_tax
warehouse_handling_fee

Examples

Request body

{
    "origin_address": {
        "line_1": "55 Prospect St",
        "line_2": "Unit 401",
        "state": "NY",
        "city": "Sydney",
        "postal_code": "11201",
        "country_alpha2": "US"
    },
    "destination_address": {
        "line_1": "1 quai de Jemmapes",
        "line_2": "Porte A",
        "state": "CA",
        "city": "Paris",
        "postal_code": "75010",
        "country_alpha2": "FR"
        },
        "output_currency": "HKD"
    },
    "parcels": [
            "items": [
                {
                    "description": "Silk dress",
                    "category": "fashion",
                    "sku": "test01",
                    "quantity": 2,
                    "dimensions": {
                        "length": null,
                        "width": null,
                        "height": null
                    },
                    "actual_weight": 10,
                    "declared_currency": "USD",
                    "declared_customs_value": 20
                }
            ]
        }
    ]
}

Response body

{
    "status": "success",
    "rates": [
        {
            "courier_id": "a6d078fd-e662-40ce-9efe-84caaa639bf7",
            "courier_name": "USPS - First Class International",
            "min_delivery_time": 5,
            "max_delivery_time": 9,
            "value_for_money_rank": 1.0,
            "delivery_time_rank": 5.0,
            "currency": "HKD",
            "shipment_charge": 200.86,
            "fuel_surcharge": 0.0,
            "remote_area_surcharge": 0.0,
            "remote_area_surcharges": {},
            "other_surcharges": {},
            "oversized_surcharge": 0.0,
            "additional_services_surcharge": 0.0,
            "residential_full_fee": 0.0,
            "residential_discounted_fee": 0.0,
            "shipment_charge_total": 200.86,
            "warehouse_handling_fee": 0.0,
            "insurance_fee": 0.0,
            "sales_tax": 0.0,
            "provincial_sales_tax": 0.0,
            "ddp_handling_fee": 0.0,
            "import_tax_charge": 0.0,
            "import_tax_non_chargeable": 0.0,
            "import_duty_charge": 0.0,
            "total_charge": 200.86,
            "is_above_threshold": true,
            "incoterms": "DDU",
            "estimated_import_tax": 102.94,
            "estimated_import_duty": 0.0,
            "minimum_pickup_fee": 0.0,
            "available_handover_options": "dropoff,free_pickup",
            "tracking_rating": 1,
            "easyship_rating": 3.5,
            "courier_remarks": null,
            "payment_recipient": "Easyship",
            "discount": {
                "amount": 0,
                "code": null,
                "percentage": null,
                "expires_at": null,
                "origin_amount": 0
            },
            "description": "Estimated  102.94 tax & duty due on delivery (Tax handling fees may apply)",
            "full_description": "USPS - First Class International (5-9 working days) Estimated  102.94 tax & duty due on delivery (Tax handling fees may apply)"
        }

To learn more about the calculation process, refer to our How Shipping Rates Are Calculated at Checkout Help Center article.