Rates
Rates are at the heart of Evership’s delivery engine — they represent the available shipping options and pricing returned for a given shipment. The Rates API allows you to fetch real-time quotes from multiple courier partners by submitting a collection and delivery address, along with parcel dimensions and weight.
On this page, we’ll explore how to use the Rates API to display delivery options during checkout or calculate fulfillment costs programmatically. You can retrieve all available services for a shipment, including pricing, estimated delivery times, and cutoff deadlines.
Introduction
The rate model contains all the information returned from Evership’s carrier integrations based on your request data. Each rate represents a single service offered by a courier, matched to your route and parcel specifications. The API can also normalize and validate addresses as part of the process to improve downstream reliability.
Validate address
Using the “Validate address” API you can validate an address without having to implement and pay for Google Maps address validation. This API can consume the address passed and then will return the address found during the geo-coding process, the validation status and an partial match suggestion if applicable.
Request Fields
- Name
collection_address.line1
- Type
- string
- Description
Street line of the collection address
- Name
collection_address.line2
- Type
- string
- Description
Optional second line of address
- Name
collection_address.city
- Type
- string
- Description
City of the collection address
- Name
collection_address.postal_code
- Type
- string
- Description
Postal code of the collection address
- Name
collection_address.state
- Type
- string
- Description
Province/state of the collection address
- Name
collection_address.country
- Type
- string
- Description
ISO 3166-1 alpha-2 country code (e.g. ZA)
- Name
delivery_address.line1
- Type
- string
- Description
Street line of the delivery address
- Name
delivery_address.line2
- Type
- string
- Description
Optional second line of address
- Name
delivery_address.city
- Type
- string
- Description
City of the delivery address
- Name
delivery_address.postal_code
- Type
- string
- Description
Postal code of the delivery address
- Name
delivery_address.state
- Type
- string
- Description
Province/state of the delivery address
- Name
delivery_address.country
- Type
- string
- Description
ISO 3166-1 alpha-2 country code
- Name
parcels
- Type
- array
- Description
List of parcel objects
- Name
parcels[].quantity
- Type
- integer
- Description
Number of identical parcels of this size/weight
- Name
parcels[].weight
- Type
- float
- Description
Weight in kilograms
- Name
parcels[].length
- Type
- float
- Description
Length in cm
- Name
parcels[].width
- Type
- float
- Description
Width in cm
- Name
parcels[].height
- Type
- float
- Description
Height in cm
- Name
service_codes
- Type
- array
- Description
Optional list of preferred service codes
Response Fields
- Name
status
- Description
Indicates success or failure (success, error)
- Name
timestamp
- Description
Time the response was generated
- Name
collection_address
- Description
Normalized version of the input collection address
- Name
delivery_address
- Description
Normalized version of the input delivery address
- Name
rates
- Description
Array of available shipping options
- Name
rates[].provider
- Description
Carrier name (e.g. "The Courier Guy")
- Name
rates[].service
- Description
Service name (e.g. "Express")
- Name
rates[].service_code
- Description
Internal service code used by Evership
- Name
rates[].currency
- Description
3-letter currency code (e.g. ZAR)
- Name
rates[].amount
- Description
Shipping cost
- Name
rates[].estimated_delivery
- Description
Estimated delivery date/time in ISO 8601 format
- Name
rates[].cutoff_time
- Description
Latest time to book for same-day dispatch
Request
{
"address_1": "101 Florida Road",
"address_2": "Apartment 4B",
"suburb": "Morningside",
"city": "Durban",
"province": "KwaZulu-Natal",
"postal_code": "4001",
"country": "South Africa"
}
Response
{
"status": "success",
"validation_status": "fully_matched",
"partial_match": false,
"matched_address": [
{
"formatted_address": "4b, 101 Florida Rd, Morningside, Durban, 4001, South Africa",
"address_components": {
"address_1": "101 Florida Road",
"address_2": "4b",
"suburb": "Morningside",
"city": "Durban",
"province": "KwaZulu-Natal",
"postal_code": "4001",
"country": "South Africa"
},
"coordinates": {
"latitude": -29.8352193,
"longitude": 31.0179579
}
}
],
"partial_match_suggestions": []
}
Error Response
{
"status": "error",
"message": "Missing or invalid postal_code in delivery_address"
}
Get Rates
This endpoint allows you to retrieve available delivery options, rates, and providers for a given collection and delivery address.
Request Fields
- Name
collection_address.line1
- Type
- string
- Description
Street line of the collection address
- Name
collection_address.line2
- Type
- string
- Description
Optional second line of address
- Name
collection_address.city
- Type
- string
- Description
City of the collection address
- Name
collection_address.postal_code
- Type
- string
- Description
Postal code of the collection address
- Name
collection_address.state
- Type
- string
- Description
Province/state of the collection address
- Name
collection_address.country
- Type
- string
- Description
ISO 3166-1 alpha-2 country code (e.g. ZA)
- Name
delivery_address.line1
- Type
- string
- Description
Street line of the delivery address
- Name
delivery_address.line2
- Type
- string
- Description
Optional second line of address
- Name
delivery_address.city
- Type
- string
- Description
City of the delivery address
- Name
delivery_address.postal_code
- Type
- string
- Description
Postal code of the delivery address
- Name
delivery_address.state
- Type
- string
- Description
Province/state of the delivery address
- Name
delivery_address.country
- Type
- string
- Description
ISO 3166-1 alpha-2 country code
- Name
parcels
- Type
- array
- Description
List of parcel objects
- Name
parcels[].quantity
- Type
- integer
- Description
Number of identical parcels of this size/weight
- Name
parcels[].weight
- Type
- float
- Description
Weight in kilograms
- Name
parcels[].length
- Type
- float
- Description
Length in cm
- Name
parcels[].width
- Type
- float
- Description
Width in cm
- Name
parcels[].height
- Type
- float
- Description
Height in cm
- Name
service_codes
- Type
- array
- Description
Optional list of preferred service codes
Response Fields
- Name
status
- Description
Indicates success or failure (success, error)
- Name
timestamp
- Description
Time the response was generated
- Name
collection_address
- Description
Normalized version of the input collection address
- Name
delivery_address
- Description
Normalized version of the input delivery address
- Name
rates
- Description
Array of available shipping options
- Name
rates[].provider
- Description
Carrier name (e.g. "The Courier Guy")
- Name
rates[].service
- Description
Service name (e.g. "Express")
- Name
rates[].service_code
- Description
Internal service code used by Evership
- Name
rates[].currency
- Description
3-letter currency code (e.g. ZAR)
- Name
rates[].amount
- Description
Shipping cost
- Name
rates[].estimated_delivery
- Description
Estimated delivery date/time in ISO 8601 format
- Name
rates[].cutoff_time
- Description
Latest time to book for same-day dispatch
Request
{
"collection_address": {
"line1": "Unit 3",
"line2": "Black River Park",
"city": "Cape Town",
"postal_code": "7925",
"state": "Western Cape",
"country": "ZA"
},
"delivery_address": {
"line1": "14 Long Street",
"line2": "",
"city": "Cape Town",
"postal_code": "8001",
"state": "Western Cape",
"country": "ZA"
},
"parcels": [
{
"quantity": 1,
"weight": 1,
"height": 10,
"width": 10,
"length": 10
}
],
"service_codes": ["Express-001"]
}
Response
{
"status": "success",
"timestamp": "2024-01-22T15:22:01.293Z",
"collection_address": {
"country": "ZA",
"state": "Western Cape",
"postal_code": "7925",
"city": "Cape Town",
"line1": "Unit 3",
"line2": "Black River Park",
"formatted": "Unit 3, Black River Park, Cape Town 7925, Western Cape, South Africa"
},
"delivery_address": {
"country": "ZA",
"state": "Western Cape",
"postal_code": "8001",
"city": "Cape Town",
"line1": "14 Long Street",
"line2": "",
"formatted": "14 Long Street, Cape Town 8001, Western Cape, South Africa"
},
"rates": [
{
"provider": "The Courier Guy",
"service": "Express",
"service_code": "Express-001",
"currency": "ZAR",
"amount": 89.99,
"estimated_delivery": "2024-01-23T17:00:00+02:00",
"cutoff_time": "2024-01-22T14:00:00+02:00"
},
{
"provider": "Aramex",
"service": "Overnight",
"service_code": "ONP",
"currency": "ZAR",
"amount": 129.50,
"estimated_delivery": "2024-01-23T12:00:00+02:00",
"cutoff_time": "2024-01-22T15:00:00+02:00"
}
]
}
Error Response
{
"status": "error",
"message": "Missing or invalid postal_code in delivery_address"
}