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.


POSTapi.evership.app/v1/validate-address

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

POST
/v1/validate-address
{
  "address_1": "101 Florida Road",
  "address_2": "Apartment 4B",
  "suburb": "Morningside",
  "city": "Durban",
  "province": "KwaZulu-Natal",
  "postal_code": "4001",
  "country": "South Africa"
}

Response

200
Success
{
  "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

400
Error
{
  "status": "error",
  "message": "Missing or invalid postal_code in delivery_address"
}

POSTapi.evership.app/v1/rates

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

POST
/rates
{
  "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

200
Success
{
  "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

400
Error
{
  "status": "error",
  "message": "Missing or invalid postal_code in delivery_address"
}

Was this page helpful?