Shipments

Shipments are the core records in Evership — they represent the packages being prepared for delivery, including the sender and recipient information, parcel dimensions, and selected shipping service. On this page, we'll explore the endpoints available for managing shipments programmatically. You can create, retrieve, update, purchase, cancel, and delete shipments through the API.

Introduction

The shipment model stores all the details needed to fulfill and track a shipment. Each shipment must have a collection and delivery address, at least one parcel, and can optionally include metadata like order number or customer contact information. Shipments can be created in a pending state or immediately purchased if a rate is available.

POSTapi.evership.app/v1/shipments

Create Shipment

The "Create shipment" API will allow you to create a single shipment record on your account in either a pending or purchased state with a single call. If the shipment is not purchased when the record is created you can purchase the shipment later using the Purchase shipments API

Request fields

Name
sender
Type
object
Description
Object containing information about the sender.
Name
sender.name
Type
string
Description
Name of the sender.
Name
sender.contact
Type
string
Description
Contact number of the sender. Format 0812345678, must contain at least 10 digits.
Name
sender.email
Type
string
Description
Email address of the sender.
Name
sender.collection_address
Type
object
Description
Object containing the collection address details for the sender.
Name
sender.collection_address.address1
Type
string
Description
First line of the address, typically including the unit or apartment number.
Name
sender.collection_address.address2
Type
string
Description
Second line of the address, typically including the street name and number.
Name
sender.collection_address.suburb
Type
string
Description
Suburb of the collection address.
Name
sender.collection_address.city
Type
string
Description
City of the collection address.
Name
sender.collection_address.province
Type
string
Description
Province of the collection address.
Name
sender.collection_address.postal_code
Type
string
Description
Postal code of the collection address.
Name
sender.collection_address.country
Type
string
Description
Country of the collection address.
Name
sender.collection_address.full_address
Type
string
Description
Full formatted address of the collection location.
Name
sender.collection_address.latitude
Type
float
Description
Latitude coordinate of the collection address. If not passed the address will be geocoded.
Name
sender.collection_address.longitude
Type
float
Description
Longitude coordinate of the collection address. If not passed the address will be geocoded.
Name
sender.pickup_instructions
Type
string
Description
Special instructions for pickup at the sender's location.
Name
receiver
Type
object
Description
Object containing information about the receiver.
Name
receiver.name
Type
string
Description
Name of the receiver.
Name
receiver.contact
Type
string
Description
Contact number of the receiver.
Name
receiver.email
Type
string
Description
Email address of the receiver.
Name
receiver.delivery_address
Type
object
Description
Object containing the delivery address details for the receiver.
Name
receiver.delivery_address.address1
Type
string
Description
First line of the address, typically including the unit or apartment number.
Name
receiver.delivery_address.address2
Type
string
Description
Second line of the address, typically including the street name and number.
Name
receiver.delivery_address.suburb
Type
string
Description
Suburb of the delivery address.
Name
receiver.delivery_address.city
Type
string
Description
City of the delivery address.
Name
receiver.delivery_address.province
Type
string
Description
Province of the delivery address.
Name
receiver.delivery_address.postal_code
Type
string
Description
Postal code of the delivery address.
Name
receiver.delivery_address.country
Type
string
Description
Country of the delivery address.
Name
receiver.delivery_address.full_address
Type
string
Description
Full formatted address of the delivery address, if the address is passed as a single string.
Name
receiver.delivery_address.latitude
Type
float
Description
Latitude coordinate of the delivery address. If empty the delivery address will be geocoded.
Name
receiver.delivery_address.longitude
Type
float
Description
Longitude coordinate of the delivery address. If empty the delivery address will be geocoded.
Name
receiver.drop_off_instructions
Type
string
Description
Special instructions for delivery at the receiver's location.
Name
parcels
Type
array
Description
Array of objects, each containing details about a parcel to be shipped.
Name
parcels.reference
Type
string
Description
Reference identifier for the parcel.
Name
parcels.description
Type
string
Description
Description of the parcel contents.
Name
parcels.dimensions
Type
object
Description
Object containing the dimensions of the parcel.
Name
parcels.dimensions.length
Type
float
Description
Length of the parcel in centimeters.
Name
parcels.dimensions.width
Type
float
Description
Width of the parcel in centimeters.
Name
parcels.dimensions.height
Type
float
Description
Height of the parcel in centimeters.
Name
parcels.weight
Type
float
Description
Weight of the parcel in kilograms.
Name
shipment_title
Type
string
Description
Title or identifier for the shipment. If left empty the title "Untitled shipment" will be appended.
Name
shipment_type
Type
string
Description
Type of shipment (outbound, inbound, transfer, or return).
Name
carrier_service
Type
string
Description
Carrier service to be used for the shipment. If left empty, the cheapest service is selected.
Name
purchase_label
Type
boolean
Description
Boolean indicating whether to purchase a shipping label.
- true = Shipment will be purchased and shipment label will be returned in the response
- false = Shipment will not be purchased, but the shipment record will be created in a pending state
Name
collection_date
Type
string
Description
Date for collection of the shipment. Leave empty if purchase_label is false.
Name
collection_time
Type
string
Description
Time for collection of the shipment. Leave empty if purchase_label is false.

Response Fields

Name
id
Type
integer
Description
Unique identifier for the shipment.
Name
waybill_number
Type
string
Description
Waybill number associated with the shipment.
Name
created_at
Type
string
Description
Timestamp of when the shipment was created.
Name
last_updated_at
Type
string
Description
Timestamp of the last update to the shipment.
Name
shipment_title
Type
string
Description
Title or identifier for the shipment.
Name
shipment_type
Type
string
Description
Type of shipment (outbound, inbound, transfer, return).
Name
label_purchased
Type
boolean
Description
Boolean indicating whether a shipping label has been purchased.
Name
collection_date
Type
string
Description
Date and time scheduled for collection of the shipment.
Name
billing
Type
array
Description
Array containing billing details related to the shipment.
Name
billing[].transaction_id
Type
integer
Description
Unique identifier for the billing transaction.
Name
billing[].timestamp
Type
string
Description
Timestamp of when the transaction occurred.
Name
billing[].type
Type
string
Description
Type of billing transaction (invoice or credit).
Name
billing[].description
Type
string
Description
Description of the billing transaction.
Name
billing[].transaction_ex_vat
Type
float
Description
Transaction amount excluding VAT.
Name
billing[].transaction_vat
Type
float
Description
VAT amount for the transaction.
Name
billing[].transaction_inc_vat
Type
float
Description
Transaction amount including VAT.
Name
billing[].transaction_status
Type
string
Description
Status of the transaction.
- invoice = wallet_debited
- credit = wallet_credited
Name
sender
Type
object
Description
Object containing information about the sender.
Name
sender.name
Type
string
Description
Name of the sender.
Name
sender.contact
Type
string
Description
Contact number of the sender.
Name
sender.email
Type
string
Description
Email address of the sender.
Name
sender.collection_address
Type
array
Description
Array containing the collection address details for the sender.
Name
sender.collection_address[].address1
Type
string
Description
First line of the collection address, typically including the unit, apartment name/number or business name.
Name
sender.collection_address[].address2
Type
string
Description
Second line of the collection address, typically including the street name and number.
Name
sender.collection_address[].suburb
Type
string
Description
Suburb of the collection address.
Name
sender.collection_address[].city
Type
string
Description
City of the collection address.
Name
sender.collection_address[].province
Type
string
Description
Province of the collection address.
Name
sender.collection_address[].postal_code
Type
string
Description
Postal code of the collection address.
Name
sender.collection_address[].country
Type
string
Description
Country of the collection address.
Name
sender.collection_address[].full_address
Type
string
Description
Full formatted address of the collection location.
Name
sender.collection_address[].latitude
Type
float
Description
Latitude coordinate of the collection address.
Name
sender.collection_address[].longitude
Type
float
Description
Longitude coordinate of the collection address.
Name
sender.collection_address[].geocode_status
Type
string
Description
Status of the geocoding process for the collection address.
Name
sender.pickup_instructions
Type
string
Description
Special instructions for pickup at the sender's location.
Name
receiver
Type
object
Description
Object containing information about the receiver.
Name
receiver.name
Type
string
Description
Name of the receiver.
Name
receiver.contact
Type
string
Description
Contact number of the receiver.
Name
receiver.email
Type
string
Description
Email address of the receiver.
Name
receiver.delivery_address
Type
object
Description
Object containing the delivery address details for the receiver.
Name
receiver.delivery_address.address1
Type
string
Description
First line of the delivery address, typically including the unit, apartment name/number or business name.
Name
receiver.delivery_address.address2
Type
string
Description
Second line of the delivery address, typically including the street name and number.
Name
receiver.delivery_address.suburb
Type
string
Description
Suburb of the delivery address.
Name
receiver.delivery_address.city
Type
string
Description
City of the delivery address.
Name
receiver.delivery_address.province
Type
string
Description
Province of the delivery address.
Name
receiver.delivery_address.postal_code
Type
string
Description
Postal code of the delivery address.
Name
receiver.delivery_address.country
Type
string
Description
Country of the delivery address.
Name
receiver.delivery_address.full_address
Type
string
Description
Full formatted address of the delivery location.
Name
receiver.delivery_address.latitude
Type
float
Description
Latitude coordinate of the delivery address.
Name
receiver.delivery_address.longitude
Type
float
Description
Longitude coordinate of the delivery address.
Name
receiver.delivery_address.geocode_status
Type
string
Description
Status of the geocoding process for the delivery address.
Name
receiver.drop_off_instructions
Type
string
Description
Special instructions for delivery at the receiver's location.
Name
latest_status
Type
object
Description
Object containing the latest status of the shipment.
Name
latest_status.primary_status
Type
object
Description
Object containing the primary status of the shipment.
Name
latest_status.primary_status.status
Type
string
Description
Current primary status of the shipment.
Name
latest_status.primary_status.slug
Type
string
Description
Slug identifier for the primary status.
Name
latest_status.primary_status.code
Type
integer
Description
Code representing the primary status.
Name
latest_status.secondary_status
Type
object
Description
Object containing the secondary status of the shipment (if applicable).
Name
services
Type
array
Description
Array of objects detailing the services used for the shipment.
Name
services[].carrier_slug
Type
string
Description
Slug identifier for the carrier.
Name
services[].carrier_id
Type
integer
Description
Unique identifier for the carrier.
Name
services[].carrier_name
Type
string
Description
Name of the carrier.
Name
services[].carrier_contact_number
Type
string
Description
Contact number for the carrier.
Name
services[].service_id
Type
integer
Description
Unique identifier for the service.
Name
services[].service_name
Type
string
Description
Name of the service.
Name
services[].service_slug
Type
string
Description
Slug identifier for the service.
Name
services[].service_full_name
Type
string
Description
Full name of the service.
Name
services[].service_sla_text
Type
string
Description
Service level agreement text (Same day, Next day, Economy etc).
Name
services[].service_transit_days
Type
integer
Description
Number of transit days for the service.
Name
services[].collection_cutoff_time
Type
string
Description
Cutoff time for collection for the service.
Name
services[].latest_delivery_time
Type
string
Description
Latest time by which the delivery is expected to be completed.
Name
parcels
Type
array
Description
Array of objects, each containing details about a parcel in the shipment.
Name
parcels[].id
Type
string
Description
Unique identifier for the parcel.
Name
parcels[].parcel_number
Type
string
Description
Unique number assigned to the parcel.
Name
parcels[].reference
Type
string
Description
Reference identifier for the parcel.
Name
parcels[].description
Type
string
Description
Description of the parcel contents.
Name
parcels[].dimensions
Type
object
Description
Object containing the dimensions of the parcel.
Name
parcels[].dimensions.length
Type
float
Description
Length of the parcel in centimeters.
Name
parcels[].dimensions.width
Type
float
Description
Width of the parcel in centimeters.
Name
parcels[].dimensions.height
Type
float
Description
Height of the parcel in centimeters.
Name
parcels[].weight
Type
float
Description
Weight of the parcel in kilograms.
Name
tracking_log
Type
array
Description
Array of objects containing tracking log entries for the shipment.
Name
tracking_log[].timestamp
Type
string
Description
Timestamp of the tracking log entry.
Name
tracking_log[].primary_status
Type
object
Description
Object containing the primary status of the tracking log entry.
Name
tracking_log[].primary_status.status
Type
string
Description
Primary status of the shipment at the time of the log entry.
Name
tracking_log[].primary_status.slug
Type
string
Description
Slug identifier for the primary status.
Name
tracking_log[].primary_status.code
Type
integer
Description
Code representing the primary status.
Name
tracking_log[].secondary_status
Type
object
Description
Object containing the secondary status of the tracking log entry (if applicable).
Name
tracking_log[].comments
Type
string
Description
Comments or additional information related to the tracking log entry.
Name
tracking_log[].location
Type
string
Description
Location associated with the tracking log entry.
Name
est_delivery
Type
object
Description
Object containing estimated delivery details.
Name
est_delivery.est_delivery_date
Type
string
Description
Estimated delivery date.
Name
est_delivery.est_delivery_time
Type
string
Description
Estimated delivery time.
Name
est_delivery.est_delivery_text
Type
string
Description
Formatted string describing the estimated delivery date and time.
Name
labels
Type
object
Description
Object containing URLs for different label formats.
Name
labels.a4_page
Type
string
Description
URL for the A4 page label format.
Name
labels.10_by_10
Type
string
Description
URL for the 10x10cm label format.
Name
labels.10_by_15
Type
string
Description
URL for the 10x15cm label format.
Name
tracking_link
Type
object
Description
Object containing tracking links for the shipment.
Name
tracking_link.receiver
Type
string
Description
URL for the receiver's tracking link.
Name
tracking_link.sender
Type
string
Description
URL for the sender's tracking link.

Request

POST

/v1/shipments

{
  "sender": {
    "name": "Ishmael Evans",
    "contact": "0817553597",
    "email": "ishmael@usecarter.com",
    "collection_address": {
      "address1": "Unit 22",
      "address2": "26 Washington Rd",
      "suburb": "Claremont",
      "city": "Cape Town",
      "province": "Western Cape",
      "postal_code": "7780",
      "country": "South Africa",
      "full_address": "Unit 22, 26 Washington Rd, Claremont, Cape Town, 7780, South Africa",
      "latitude": -33.9706,
      "longitude": 18.4649
    },
    "pickup_instructions": "Call when arrived"
  },
  "receiver": {
    "name": "Jane Smith",
    "contact": "0787654321",
    "email": "janesmith@example.com",
    "delivery_address": {
      "address1": "Tech Solutions Inc., Tech Park, Suite 500",
      "address2": "12 Clyde Road",
      "suburb": "Green Point",
      "city": "Cape Town",
      "province": "Western Cape",
      "postal_code": "8005",
      "country": "South Africa",
      "full_address": "Tech Solutions Inc., Tech Park, Suite 500, 12 Clyde Road, Green Point, Cape Town, 8005, South Africa",
      "latitude": -33.9095,
      "longitude": 18.4155
    },
    "drop_off_instructions": "Please ring the bell twice"
  },
  "parcels": [
    {
      "reference": "Parcel-REF-1",
      "description": "Books",
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 10
      },
      "weight": 5
    },
    {
      "reference": "Parcel-REF-2",
      "description": "Clothes",
      "dimensions": {
        "length": 40,
        "width": 25,
        "height": 15
      },
      "weight": 7
    }
  ],
  "shipment_title": "Order #1234",
  "shipment_type": "outbound",
  "carrier_service": "dpd-econ",
  "purchase_label": true,
  "collection_date": "2025-02-14",
  "collection_time": "12:30:00"
}

Response

200

Created draft

{
  "id": 1339657,
  "waybill_number": "",
  "created_at": "2025-02-14T06:20:26Z",
  "last_updated_at": "",
  "shipment_title": "Order #1234",
  "shipment_type": "outbound",
  "label_purchased": false,
  "collection_date": "",
  "billing": [],
  "sender": {
    "name": "Ishmael Evans",
    "contact": "0817553597",
    "email": "ishmael@usecarter.com",
    "collection_address": {
      "address1": "26 Washington Rd",
      "address2": "",
      "suburb": "Claremont",
      "city": "Cape Town",
      "province": "Western Cape",
      "postal_code": "7780",
      "country": "South Africa",
      "full_address": "26 Washington Rd, Claremont, Cape Town, 7780, South Africa",
      "latitude": 40.7128,
      "longitude": -74.0060,
      "geocode_status": "partially_matched"
    },
    "pickup_instructions": "Call when arrived"
  },
  "receiver": {
    "name": "Jane Smith",
    "contact": "0787654321",
    "email": "janesmith@example.com",
    "delivery_address": {
      "address1": "12 Clyde Road",
      "address2": "",
      "suburb": "Green Point",
      "city": "Cape Town",
      "province": "Western Cape",
      "postal_code": "8005",
      "country": "South Africa",
      "full_address": "12 Clyde Road, Green Point, Cape Town, 8005, South Africa",
      "latitude": 34.0522,
      "longitude": -118.2437,
      "geocode_status": "matched"
    },
    "drop_off_instructions": "Ring the doorbell twice"
  },
  "latest_status": {
    "primary_status": {
      "status": "pending",
      "slug": "pending",
      "code": 1
    },
    "secondary_status": null
  },
  "services": [
    {
      "service_type": "shipment",
      "carrier_slug": "fw",
      "carrier_id": 4,
      "carrier_name": "Fastway",
      "service_id": 18,
      "service_name": "BROWN",
      "service_slug": "fw-brown",
      "service_full_name": "Local Parcel",
      "service_sla_text": "Same day",
      "service_transit_days": 0,
      "collection_cutoff_time": "14:00",
      "latest_delivery_time": "18:00"
    }
  ],
  "parcels": [
    {
      "id": "12345_1",
      "parcel_number": "",
      "reference": "Parcel-REF-1",
      "description": "Books",
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 10
      },
      "weight": 5
    },
    {
      "id": "12345_2",
      "parcel_number": "",
      "reference": "Parcel-REF-2",
      "description": "Clothes",
      "dimensions": {
        "length": 40,
        "width": 25,
        "height": 15
      },
      "weight": 7
    }
  ],
  "tracking_log": [],
  "labels": {},
  "tracking_link": {}
}

Response

200

Created purchased

{
  "id": 1339657,
  "waybill_number": "CTR492459759",
  "created_at": "2025-02-14T06:20:26Z",
  "last_updated_at": "2025-04-08T10:00:00Z",
  "shipment_title": "Order #1234",
  "shipment_type": "outbound",
  "label_purchased": true,
  "collection_date": "2025-02-14T10:00:00Z",
  "billing": [
    {
      "transaction_id": 123456,
      "timestamp": "2025-02-14T06:20:26Z",
      "type": "invoice",
      "description": "Shipment purchased",
      "transaction_ex_vat": 55,
      "transaction_vat": 8.25,
      "transaction_inc_vat": 63.25,
      "transaction_status": "wallet_debited"
    }
  ],
  "sender": {
    "name": "Ishmael Evans",
    "contact": "0817553597",
    "email": "ishmael@usecarter.com",
    "collection_address": [
      {
        "address1": "Unit 12",
        "address2": "26 Washington Rd",
        "suburb": "Claremont",
        "city": "Cape Town",
        "province": "Western Cape",
        "postal_code": "7780",
        "country": "South Africa",
        "full_address": "Unit 12, 26 Washington Rd, Claremont, Cape Town, 7780, South Africa",
        "latitude": -33.9706,
        "longitude": 18.4649,
        "geocode_status": "partially_matched"
      }
    ],
    "pickup_instructions": "Call when arrived"
  },
  "receiver": {
    "name": "Jane Smith",
    "contact": "0787654321",
    "email": "janesmith@example.com",
    "delivery_address": {
      "address1": "Tech Solutions Inc., Tech Park, Suite 500",
      "address2": "12 Clyde Road",
      "suburb": "Green Point",
      "city": "Cape Town",
      "province": "Western Cape",
      "postal_code": "8005",
      "country": "South Africa",
      "full_address": "Tech Solutions Inc., Tech Park, Suite 500, 12 Clyde Road, Green Point, Cape Town, 8005, South Africa",
      "latitude": -33.9095,
      "longitude": 18.4155,
      "geocode_status": "fully_matched"
    },
    "drop_off_instructions": "Ring the doorbell twice"
  },
  "latest_status": {
    "primary_status": {
      "status": "Collection approved",
      "slug": "collection_approved",
      "code": 3
    },
    "secondary_status": null
  },
  "services": [
    {
      "service_type": "shipment",
      "carrier_slug": "fw",
      "carrier_id": 4,
      "carrier_name": "Fastway",
      "carrier_contact_number": "0812345678",
      "service_id": 18,
      "service_name": "BROWN",
      "service_slug": "fw-brown",
      "service_full_name": "Local Parcel",
      "service_sla_text": "Same day",
      "service_transit_days": 0,
      "collection_cutoff_time": "12:30",
      "latest_delivery_time": "17:30"
    }
  ],
  "parcels": [
    {
      "id": 40329,
      "parcel_number": "CTR492459759_1",
      "reference": "Parcel-REF-1",
      "description": "Books",
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 10
      },
      "weight": 5
    },
    {
      "id": 40330,
      "parcel_number": "CTR492459759_2",
      "reference": "Parcel-REF-2",
      "description": "Clothes",
      "dimensions": {
        "length": 40,
        "width": 25,
        "height": 15
      },
      "weight": 7
    }
  ],
  "tracking_log": [
    {
      "timestamp": "2025-04-06T22:48:00Z",
      "primary_status": {
        "status": "Pending",
        "slug": "pending",
        "code": 1
      },
      "secondary_status": null,
      "comments": "Created by admin user",
      "location": ""
    },
    {
      "timestamp": "2025-04-06T22:51:00Z",
      "primary_status": {
        "status": "Collection requested",
        "slug": "collection_requested",
        "code": 2
      },
      "secondary_status": null,
      "comments": "For collection on Mon, 07 Apr",
      "location": ""
    },
    {
      "timestamp": "2025-04-06T22:51:00Z",
      "primary_status": {
        "status": "Collection approved",
        "slug": "collection_approved",
        "code": 3
      },
      "secondary_status": null,
      "comments": "Carrier collecting on Mon, 07 Apr",
      "location": ""
    }
  ],
  "est_delivery": {
    "est_delivery_date": "2025-04-07",
    "est_delivery_time": "17:30:00",
    "est_delivery_text": "Monday, 7th April before 5:30 PM"
  },
  "labels": {
    "a4_page": "https://evership.app/label/a4/CTR492459759",
    "10_by_10": "https://evership.app/label/10x10/CTR492459759",
    "10_by_15": "https://evership.app/label/10x15/CTR492459759"
  },
  "tracking_link": {
    "receiver": "https://ship.evership.app/gs7fh7",
    "sender": "https://ship.evership.app/5rlyg6"
  }
}

POSTapi.evership.app/v1/purchase-shipment

Purchase Shipment

Use this endpoint to purchase an existing shipment (or batch of shipments) that was previously created. The shipment must already have a valid rate associated with it. Once purchased, a label and tracking number will be returned.

Request fields

Name
shipment_ids
Type
array
Description
List of shipment IDs to purchase.
Name
shipment_ids[]
Type
string
Description
Must be a valid Evership shipment ID (e.g., shp_xxxx) in a pending state.
Name
metadata
Type
object
Description
Optional object to append metadata to all shipments.

Response Fields

Name
status
Type
string
Description
Response status: success or error.
Name
purchased_shipments
Type
array
Description
Array of successfully purchased shipment objects.
Name
purchased_shipments[].id
Type
string
Description
Unique ID of the purchased shipment.
Name
purchased_shipments[].state
Type
string
Description
Shipment state, should be purchased.
Name
purchased_shipments[].label_url
Type
string
Description
URL to download the shipping label.
Name
purchased_shipments[].tracking_number
Type
string
Description
Carrier-provided tracking number.
Name
purchased_shipments[].provider
Type
string
Description
Shipping carrier used (e.g. The Courier Guy, Aramex).
Name
purchased_shipments[].service
Type
string
Description
Shipping service used (e.g. Express, Overnight).
Name
purchased_shipments[].rate.amount
Type
float
Description
Cost of the shipment.
Name
purchased_shipments[].rate.currency
Type
string
Description
Currency code for the amount, e.g. ZAR.

Request

POST

/v1/purchase-shipment

{
  "shipment_ids": [
    "shp_01HF5TC8X63C3MFX3D0WTTVRHN",
    "shp_01HF5TD2PRJ5R3T0E0KXJQ0T9X"
  ]
}

Response

200

Success

{
  "status": "success",
  "purchased_shipments": [
    {
      "id": "shp_01HF5TC8X63C3MFX3D0WTTVRHN",
      "state": "purchased",
      "label_url": "https://labels.evership.app/label_01.pdf",
      "tracking_number": "TGC123456789",
      "provider": "The Courier Guy",
      "service": "Express",
      "rate": {
        "amount": 89.99,
        "currency": "ZAR"
      }
    },
    {
      "id": "shp_01HF5TD2PRJ5R3T0E0KXJQ0T9X",
      "state": "purchased",
      "label_url": "https://labels.evership.app/label_02.pdf",
      "tracking_number": "RMX987654321",
      "provider": "Aramex",
      "service": "Overnight",
      "rate": {
        "amount": 109.99,
        "currency": "ZAR"
      }
    }
  ]
}

PUTapi.evership.app/v1/shipments/{shipment_id}

Edit Shipment

Use this endpoint to update an existing shipment that is still in a pending state.

You can update the collection address, delivery address, parcel dimensions/quantities, and metadata fields. This is useful if your customer updated their delivery information or you need to fix a mistake before purchasing the shipment.

Once a shipment is purchased via /purchase-shipment, it can no longer be updated and will return a 409 Conflict error.

Request fields

Name
collection_address.line1
Type
string
Description
Street line 1 of collection address
Name
collection_address.line2
Type
string
Description
Street line 2
Name
collection_address.city
Type
string
Description
City
Name
collection_address.postal_code
Type
string
Description
Postal code
Name
collection_address.state
Type
string
Description
Province or state
Name
collection_address.country
Type
string
Description
ISO 3166-1 alpha-2 country code
Name
delivery_address.line1
Type
string
Description
Street line 1 of delivery address
Name
delivery_address.line2
Type
string
Description
Street line 2
Name
delivery_address.city
Type
string
Description
City
Name
delivery_address.postal_code
Type
string
Description
Postal code
Name
delivery_address.state
Type
string
Description
Province or state
Name
delivery_address.country
Type
string
Description
ISO 3166-1 alpha-2 country code
Name
parcels[].quantity
Type
integer
Description
Number of identical parcels
Name
parcels[].weight
Type
float
Description
Weight in kg
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
metadata.order_number
Type
string
Description
Order number reference
Name
metadata.customer_name
Type
string
Description
Customer name
Name
metadata.customer_phone
Type
string
Description
Phone number
Name
metadata.customer_email
Type
string
Description
Email address

Response Fields

Name
status
Type
string
Description
Response status, e.g. success or error
Name
shipment.id
Type
string
Description
Unique ID of the shipment
Name
shipment.state
Type
string
Description
Should be pending
Name
shipment.collection_address
Type
object
Description
Updated collection address object
Name
shipment.delivery_address
Type
object
Description
Updated delivery address object
Name
shipment.parcels
Type
array
Description
Updated parcel list
Name
shipment.metadata
Type
object
Description
Updated metadata object
Name
shipment.metadata.order_number
Type
string
Description
Order reference number
Name
shipment.metadata.customer_name
Type
string
Description
Customer full name
Name
shipment.metadata.customer_email
Type
string
Description
Customer email address

Request

PUT

/v1/shipments/{shipment_id}

{
  "collection_address": {
    "line1": "Unit 3",
    "line2": "Brickfield Park",
    "city": "Cape Town",
    "postal_code": "7925",
    "state": "Western Cape",
    "country": "ZA"
  },
  "delivery_address": {
    "line1": "75 Harrington Street",
    "line2": "",
    "city": "Cape Town",
    "postal_code": "8001",
    "state": "Western Cape",
    "country": "ZA"
  },
  "parcels": [
    {
      "quantity": 1,
      "weight": 2,
      "length": 12,
      "width": 12,
      "height": 12
    }
  ],
  "metadata": {
    "order_number": "EV-555",
    "customer_name": "James Smith",
    "customer_email": "james@example.com"
  }
}

Response

200

Success

{
  "status": "success",
  "shipment": {
    "id": "shp_01HF5TC8X63C3MFX3D0WTTVRHN",
    "state": "pending",
    "collection_address": {
      "line1": "Unit 3",
      "line2": "Brickfield Park",
      "city": "Cape Town",
      "postal_code": "7925",
      "state": "Western Cape",
      "country": "ZA"
    },
    "delivery_address": {
      "line1": "75 Harrington Street",
      "line2": "",
      "city": "Cape Town",
      "postal_code": "8001",
      "state": "Western Cape",
      "country": "ZA"
    },
    "parcels": [
      {
        "quantity": 1,
        "weight": 2,
        "length": 12,
        "width": 12,
        "height": 12
      }
    ],
    "metadata": {
      "order_number": "EV-555",
      "customer_name": "James Smith",
      "customer_email": "james@example.com"
    }
  }
}

GETapi.evership.app/v1/list-shipments

List Shipments

Use this endpoint to return a paginated list of shipments associated with your account. You can filter by state, a date range (created_from and created_to), or search by order_number or tracking_number.

By default, 25 shipments are returned per page. You can override the limit parameter and paginate using cursor.

Request fields

Name
state
Type
string
Description
Filter shipments by state (pending, purchased, cancelled)
Name
created_from
Type
string
Description
Filter shipments created after this ISO 8601 timestamp
Name
created_to
Type
string
Description
Filter shipments created before this ISO 8601 timestamp
Name
order_number
Type
string
Description
Search by metadata.order_number
Name
tracking_number
Type
string
Description
Search by tracking_number
Name
limit
Type
integer
Description
Number of shipments per page (default 25, max 100)
Name
cursor
Type
string
Description
Used to paginate to the next page

Response Fields

Name
status
Type
string
Description
Status of the response, e.g. success
Name
shipments
Type
array
Description
Array of shipment records matching the query
Name
shipments[].id
Type
string
Description
Unique ID of the shipment
Name
shipments[].state
Type
string
Description
Shipment state (pending, purchased, cancelled)
Name
shipments[].tracking_number
Type
string
Description
Carrier tracking number (if purchased)
Name
shipments[].label_url
Type
string
Description
Label download URL (if purchased)
Name
shipments[].collection_address
Type
object
Description
Address object where the parcel is collected
Name
shipments[].delivery_address
Type
object
Description
Address object where the parcel is delivered
Name
shipments[].parcels
Type
array
Description
Array of parcel data (quantity, size, weight)
Name
shipments[].metadata.order_number
Type
string
Description
Order number from metadata
Name
shipments[].metadata.customer_name
Type
string
Description
Name of the customer
Name
shipments[].metadata.customer_email
Type
string
Description
Email of the customer
Name
pagination.limit
Type
integer
Description
Limit set in the request
Name
pagination.cursor
Type
string
Description
Cursor token used for pagination (send as query param in next request)

Request

GET https://api.example.com/list-shipments?page=1&results_per_page=25&status=pending&payment_status=paid&shipment_type=outbound&carrier=fw&collection_region=Western%20Cape&delivery_region=Eastern%20Cape&created_date_range_start=2025-02-01&created_date_range_end=2025-02-14&collection_date_range_start=2025-02-10&collection_date_range_end=2025-02-15&last_updated_range_start=2025-02-12&last_updated_range_end=2025-02-16&geo_coded_status=unmatched

Response

200

Success

{
  "status": "success",
  "shipments": [
    {
      "id": "shp_01HF5TC8X63C3MFX3D0WTTVRHN",
      "state": "purchased",
      "tracking_number": "TGC123456789",
      "label_url": "https://labels.evership.app/label_01.pdf",
      "collection_address": {
        "line1": "Unit 3",
        "line2": "Black River Park",
        "city": "Cape Town",
        "postal_code": "7925",
        "state": "Western Cape",
        "country": "ZA"
      },
      "delivery_address": {
        "line1": "113 Loop St",
        "line2": "",
        "city": "Cape Town City Centre",
        "city": "Cape Town",
        "province": "Western Cape",
        "postal_code": "8000",
        "country": "South Africa",
        "full_address": "113 Loop St, Cape Town City Centre, Cape Town, Western Cape, 8000, South Africa",
        "latitude": -33.9242692,
        "longitude": 18.4187029,
        "geocode_status": "partially_matched"
      },
      "parcels": [
        {
          "quantity": 1,
          "weight": 1,
          "height": 10,
          "width": 10,
          "length": 10
        }
      ],
      "metadata": {
        "order_number": "EV123456",
        "customer_name": "Sarah Smith",
        "customer_email": "sarah@example.com"
      }
    },
    {
      "id": "shp_01HF5TD2PRJ5R3T0E0KXJQ0T9X",
      "state": "pending",
      "tracking_number": null,
      "label_url": null,
      "collection_address": {
        "line1": "Unit 12",
        "line2": "Brickfield 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": 2,
          "height": 12,
          "width": 12,
          "length": 12
        }
      ],
      "metadata": {
        "order_number": "EV555",
        "customer_name": "James Smith",
        "customer_email": "james@example.com"
      }
    }
  ],
  "pagination": {
    "limit": 25,
    "cursor": "eyJpZCI6InNocl8wMUhGNT..."
  }
}

GETapi.evership.app/v1/shipments/{shipment_id}

Retrieve Shipments

This API is different from List shipments API, here you can only fetch the details of a single shipment and not multiple shipments in a list.

Using this "Retrieve shipment" API you can retrieve a single shipment record by passing the shipment's shipment_id and the response will return full details of the shipment, including the tracking log and shipping labels. Both purchased and un-purchased shipments can be retrieved using this "Retrieve shipment" API

Request fields

Name
shipment_id
Type
string
Description
Unique ID for the shipment record that is being retrieved

Response Fields

Name
status
Type
string
Description
Status of the response, e.g. success
Name
shipments
Type
array
Description
Array of shipment records matching the query
Name
shipments[].id
Type
string
Description
Unique ID of the shipment
Name
shipments[].state
Type
string
Description
Shipment state (pending, purchased, cancelled)
Name
shipments[].tracking_number
Type
string
Description
Carrier tracking number (if purchased)
Name
shipments[].label_url
Type
string
Description
Label download URL (if purchased)
Name
shipments[].collection_address
Type
object
Description
Address object where the parcel is collected
Name
shipments[].delivery_address
Type
object
Description
Address object where the parcel is delivered
Name
shipments[].parcels
Type
array
Description
Array of parcel data (quantity, size, weight)
Name
shipments[].metadata.order_number
Type
string
Description
Order number from metadata
Name
shipments[].metadata.customer_name
Type
string
Description
Name of the customer
Name
shipments[].metadata.customer_email
Type
string
Description
Email of the customer
Name
pagination.limit
Type
integer
Description
Limit set in the request
Name
pagination.cursor
Type
string
Description
Cursor token used for pagination (send as query param in next request)

Request

GET https://api.evership.app/shipments/{shipment_id}

Response

200

Success

{
    "shipment_id": "4rUA2",
    "waybill_number": "",
    "created_at": "2025-06-20T17:29:27Z",
    "last_updated_at": "2025-06-20T17:29:28Z",
    "shipment_title": "Create title",
    "shipment_type": "outbound",
    "payment_status": "pending",
    "label_purchased": false,
    "collection_date": null,
    "billing": [],
    "sender": {
        "name": "Create Sender",
        "contact": "081 000 0001",
        "email": null,
        "collection_address": {
            "address_1": "101 Florida Road",
            "address_2": "Apartment 4B",
            "suburb": "Morningside",
            "city": "Durban",
            "province": "KwaZulu-Natal",
            "postal_code": "4001",
            "country": "South Africa",
            "full_address": "101 Florida Road, Apartment 4B, Morningside, Durban, KwaZulu-Natal, 4001, South Africa",
            "latitude": -33.9373392,
            "longitude": 18.4330704,
            "geocode_status": "fully_matched"
        },
        "pickup_instructions": "Create sender instructions"
    },
    "receiver": {
        "name": "Create Receiver",
        "contact": "070 000 0001",
        "email": null,
        "delivery_address": {
            "address_1": "113 Loop St",
            "address_2": "Unit 12",
            "suburb": "Cape Town City Centre",
            "city": "Cape Town",
            "province": "Western Cape",
            "postal_code": "8000",
            "country": "South Africa",
            "full_address": "113 Loop St, Unit 12, Cape Town City Centre, Cape Town, Western Cape, 8000, South Africa",
            "latitude": -33.9242692,
            "longitude": 18.4187029,
            "geocode_status": "fully_matched"
        },
        "drop_off_instructions": "Create receiver instructions"
    },
    "latest_status": {
        "primary_status": {
            "status": "pending",
            "slug": "pending",
            "code": 1
        },
        "secondary_status": null
    },
    "services": [
        {
            "service_type": "shipment",
            "carrier_slug": "dpdl",
            "carrier_id": 3,
            "carrier_name": "DPD Laser",
            "service_id": 15,
            "service_name": "ECON",
            "service_slug": "dpd-econ",
            "service_full_name": "ECONOMY",
            "service_sla_text": "2 - 3 day",
            "service_transit_days": 3,
            "collection_cutoff_time": "14:00",
            "latest_delivery_time": "17:30"
        }
    ],
    "parcels": [
        {
            "id": "4rUwD",
            "parcel_number": null,
            "reference": "CREATE-REF",
            "description": "Create description",
            "dimensions": {
                "length": 1,
                "width": 1,
                "height": 1
            },
            "weight": 1
        }
    ],
    "tracking_log": [],
    "est_delivery": {},
    "labels": {},
    "tracking_link": {}
}

POSTapi.evership.app/v1/cancel-shipment/{shipment_id}

Cancel Shipments

This "Cancel shipment" API allows you to cancel a single shipment that has been purchased but not yet collected by the carrier (status = requested or approved) by passing the shipment_id of the shipment you want to cancel.

If you try to cancel a shipment with status = pending, an error message will be returned because the shipment has not been purchased yet. If you try to cancel a shipment where the status is not requested or approved, an error message will be returned because the shipment has already been collected by the carrier.

Request Fields

Name
shipment_id
Type
string
Description
The unique shipment_id of the shipment to cancel.

Response Fields

Name
status
Type
string
Description
Status of the response, e.g. "success" or "error".
Name
shipment
Type
object
Description
The cancelled shipment record.
Name
shipment.id
Type
string
Description
Unique ID of the shipment.
Name
shipment.state
Type
string
Description
Shipment state (pending, purchased, cancelled).
Name
shipment.tracking_number
Type
string
Description
Carrier tracking number (if purchased).
Name
shipment.label_url
Type
string
Description
Label download URL (if purchased).
Name
shipment.collection_address
Type
object
Description
Address object where the parcel is collected.
Name
shipment.delivery_address
Type
object
Description
Address object where the parcel is delivered.
Name
shipment.parcels
Type
array
Description
Array of parcel data (quantity, size, weight).
Name
shipment.metadata.order_number
Type
string
Description
Order number from metadata.
Name
shipment.metadata.customer_name
Type
string
Description
Name of the customer.
Name
shipment.metadata.customer_email
Type
string
Description
Email of the customer.

Request

POST https://www.api.evership.app/v1/cancel-shipment/{shipment_id}

Response

200

Success

{
  "id": 1339657,
  "cancellation_status": "success",
  "status": {
    "primary": {
      "status": "cancelled",
      "code": "12"
    },
    "secondary": {
      "status": "cancelled_user",
      "code": "12A"
    }
  },
  "cancellation_timestamp": "2025-03-09T12:00:00+10:30",
  "message": "The shipment has been cancelled successfully."
}

DELETEapi.evership.app/v1/shipments/{shipment_id}

Delete Shipments

This "Delete shipments" API will allow you to delete either a single shipment or batch of shipments that have the pending status, and have not been purchased yet or have not been cancelled. If the shipment has been purchased or cancelled, it cannot be deleted and we will return an error response.

Request Fields

Name
shipment_ids
Type
string
Description
Comma-separated list of shipment IDs to be deleted. Each ID uniquely identifies a shipment to be deleted from the system.

Response Fields

Name
status
Type
string
Description
Status of the response, e.g. "success" or "error".
Name
shipment
Type
object
Description
The cancelled shipment record.
Name
shipment.id
Type
string
Description
Unique ID of the shipment.
Name
shipment.state
Type
string
Description
Shipment state (pending, purchased, cancelled).
Name
shipment.tracking_number
Type
string
Description
Carrier tracking number (if purchased).
Name
shipment.label_url
Type
string
Description
Label download URL (if purchased).
Name
shipment.collection_address
Type
object
Description
Address object where the parcel is collected.
Name
shipment.delivery_address
Type
object
Description
Address object where the parcel is delivered.
Name
shipment.parcels
Type
array
Description
Array of parcel data (quantity, size, weight).
Name
shipment.metadata.order_number
Type
string
Description
Order number from metadata.
Name
shipment.metadata.customer_name
Type
string
Description
Name of the customer.
Name
shipment.metadata.customer_email
Type
string
Description
Email of the customer.

Request

DELETE https://www.api.evership.app/v1/shipments?shipment_ids=12345,12346,12347

Response

200

Success

{
  "summary": {
    "total": 4,
    "deleted": 1,
    "failed": 3
  },
  "results": [
    {
      "shipment_id": "12345",
      "status": "deleted"
    },
    {
      "shipment_id": "12346",
      "status": "not_found",
      "error_message": "This shipment was not found"
    },
    {
      "shipment_id": "12348",
      "status": "cannot_delete_purchased",
      "error_message": "This shipment cannot be deleted as it has been purchased"
    },
    {
      "shipment_id": "12349",
      "status": "cannot_delete_cancelled",
      "error_message": "This shipment cannot be deleted as it has been cancelled"
    }
  ]
}