API reference

Rates, shipments, labels, tracking and webhooks for Nigerian shipping, through one API.

Authentication. Send your secret key as Authorization: Bearer <key>. Keys are for servers: never put one in a browser or an app. The key decides the environment: evp_test_… keys use the sandbox (test carriers, no money, nothing real is shipped); evp_live_… keys use production (real carriers, paid from your EviPostal wallet) once production access is enabled for your business.

Errors share one shape: { "error": { "code", "message", "request_id", "fields"?, "docs_url" } }. Quote request_id (also in the X-Request-Id header) when you contact support.

Idempotency. Send an Idempotency-Key header (1–255 of A-Z a-z 0-9 _ . : -) on mutations; it is required on POST /shipments. The same key and body replays the first result with Idempotent-Replayed: true for 24 hours; the same key with a different body is 422 idempotency_key_reused.

Rate limits are per application and environment; every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and a 429 adds Retry-After.

Versioning. v1 only grows: new optional fields, new response fields, new enum values in open enums (shipment status, tracking event type) and new event types. Ignore fields and event types you do not know.

Webhooks are signed with EviPostal-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>. During the 24 hours after a secret rotation a second v1= entry is signed with the previous secret: accept the request if any v1 matches. Reject it when |now − t| > 300 seconds (replay protection). Failed deliveries are retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h. Production endpoints also receive the events of shipments your store books in the EviPostal dashboard or POS (created_through: "dashboard").

Sandbox scenarios. Start to.line1 with: MOCK-NO-SERVICE — No rates: rates is empty and messages has no_service. MOCK-INVALID-ADDRESS — No rates: messages has invalid_address. MOCK-TIMEOUT — The test carrier does not answer: 503 carrier_unavailable (takes the carrier timeout). MOCK-BOOK-FAIL — Booking refused: 422 booking_failed. Nothing charged. MOCK-BOOK-TIMEOUT — 202 with status booking; EviPostal confirms it later and sends shipment.booked. MOCK-BOOK-LOST — 202 with status booking; EviPostal finds no booking and sends shipment.booking_failed. MOCK-NO-FUNDS — 402 insufficient_funds, as a production key with an empty wallet would get. MOCK-LABEL-LATER — The label stays pending at first: GET label answers 409 label_not_ready. MOCK-DELAYED — The timeline reports a delay: shipment.delayed. MOCK-PICKUP-FAIL — The carrier cannot collect it: shipment.exception with status delivery_issue.

Base URLhttps://api.evipostal.com/v1· version v1

Account

Your API key.

get/v1/me

Check your API key

Returns the environment, scopes and application of the key you sent. Use it to test that your key works. Any valid key may call it.

Scope: None needed
Idempotency-Key header: Not used

Answers

200The key you sent.
401authentication_required invalid_api_key api_key_revoked
403application_disabled production_access_required
429rate_limited
500internal_error

Fields in the answer

Check your API key answer
Field	Type	Details
`object`Required	"api_key"	—
`environment`Required	enum	One of: sandbox, production
`key`Required	string	—
`scopes`Required	array of enum	Each one of: rates:read, shipments:read, shipments:write, labels:read, tracking:read, webhooks:read, webhooks:write
`application`Required	object	—
`application.name`Required	string	—
`business`Required	object	—
`business.name`Required	string	—
`api_version`Required	"v1"	—

curl "https://api.evipostal.com/v1/me" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY"

200 answer

{
  "object": "api_key",
  "environment": "sandbox",
  "key": "evp_test_7Qm2…x9Ka",
  "scopes": [
    "rates:read",
    "shipments:read",
    "shipments:write",
    "labels:read",
    "tracking:read",
    "webhooks:read",
    "webhooks:write"
  ],
  "application": {
    "name": "Order sync"
  },
  "business": {
    "name": "Ada Stores"
  },
  "api_version": "v1"
}

Rates

Quotes from the carriers available to your key.

post/v1/rates

Get rates

Quotes a parcel with every carrier available to your key: the sandbox uses test carriers only. Each rate has an id you book with POST /shipments before expires_at. amount is what booking the rate costs your business. Nothing is charged here. When no rate comes back, messages says why. Rate requests have their own, lower rate limit.

Scope: rates:read
Idempotency-Key header: Optional, recommended

Parameters

Get rates parameters
Field	Type	Details
`Idempotency-Key`Optional	header · string	Makes a retry safe: the same key and body replays the first result for 24 hours. Pattern ^[A-Za-z0-9_.:-]{1,255}$

Request body

Get rates request body
Field	Type	Details
`from`Required	object	—
`from.name`Required	string	1–120 characters
`from.phone`Required	string	Pattern ^\+?[0-9][0-9 ()-]{6,19}$
`from.email`Optional	string	Up to 254 characters · An email address
`from.company`Optional	string	Up to 120 characters
`from.line1`Required	string	1–200 characters
`from.line2`Optional	string	Up to 200 characters
`from.city`Required	string	1–80 characters
`from.state`Required	string	1–80 characters
`from.postal_code`Optional	string	Up to 16 characters
`from.country`Optional	string	Pattern ^[A-Z]{2}$ · Default "NG"
`from.landmark`Optional	string	Up to 200 characters
`to`Required	object	—
`to.name`Required	string	1–120 characters
`to.phone`Required	string	Pattern ^\+?[0-9][0-9 ()-]{6,19}$
`to.email`Optional	string	Up to 254 characters · An email address
`to.company`Optional	string	Up to 120 characters
`to.line1`Required	string	1–200 characters
`to.line2`Optional	string	Up to 200 characters
`to.city`Required	string	1–80 characters
`to.state`Required	string	1–80 characters
`to.postal_code`Optional	string	Up to 16 characters
`to.country`Optional	string	Pattern ^[A-Z]{2}$ · Default "NG"
`to.landmark`Optional	string	Up to 200 characters
`parcels`Required	array of object	1–5 items
`parcels[].package_type`Optional	enum	One of: box, envelope, soft_pack · Default "box"
`parcels[].weight_grams`Required	integer	1–1,000,000
`parcels[].length_cm`Required	integer	1–500
`parcels[].width_cm`Required	integer	1–500
`parcels[].height_cm`Required	integer	1–500
`parcels[].description`Required	string	1–200 characters
`parcels[].declared_value`Required	integer	0–100,000,000,000
`currency`Optional	"NGN"	Default "NGN"
`reference`Optional	string	Up to 64 characters
`metadata`Optional	object of string	—

Answers

200Rates, cheapest first.
400invalid_request validation_failed
401authentication_required invalid_api_key api_key_revoked
403application_disabled production_access_required insufficient_scope
409conflict idempotency_key_in_use
413request_too_large
422idempotency_key_reused
429rate_limited
500internal_error
503carrier_unavailable

Fields in the answer

Get rates answer
Field	Type	Details
`object`Required	"rate_list"	—
`environment`Required	enum	One of: sandbox, production
`reference`Required	string or null	—
`metadata`Required	object of string	—
`rates`Required	array of object	—
`rates[].id`Required	string	—
`rates[].object`Required	"rate"	—
`rates[].carrier`Required	object	—
`rates[].carrier.code`Required	string	—
`rates[].carrier.name`Required	string	—
`rates[].service`Required	object	—
`rates[].service.code`Required	string	—
`rates[].service.name`Required	string	—
`rates[].service.description`Required	string or null	—
`rates[].amount`Required	integer	0–9,007,199,254,740,991
`rates[].currency`Required	string	—
`rates[].charges`Required	array of object	—
`rates[].charges[].type`Required	enum	One of: base, insurance, tax, fuel, discount, other
`rates[].charges[].label`Required	string	—
`rates[].charges[].amount`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`rates[].includes_insurance`Required	boolean	—
`rates[].estimated_delivery`Required	object	—
`rates[].estimated_delivery.at`Required	string (date-time) or null	—
`rates[].estimated_delivery.transit_days`Required	integer or null	0–9,007,199,254,740,991
`rates[].estimated_delivery.text`Required	string	—
`rates[].chargeable_weight_grams`Required	integer or null	0–9,007,199,254,740,991
`rates[].notices`Required	array of object	—
`rates[].notices[].level`Required	enum	One of: info, warning
`rates[].notices[].message`Required	string	—
`rates[].test`Required	boolean	—
`rates[].created_at`Required	string (date-time)	—
`rates[].expires_at`Required	string (date-time)	—
`messages`Required	array of object	—
`messages[].code`Required	enum	One of: no_service, invalid_address, carrier_unavailable, rates_incomplete
`messages[].message`Required	string	—
`created_at`Required	string (date-time)	—

curl -X POST "https://api.evipostal.com/v1/rates" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "from": {
    "name": "Ada Stores",
    "phone": "+2348012345678",
    "email": "orders@example.com",
    "line1": "12 Allen Avenue",
    "city": "Ikeja",
    "state": "Lagos",
    "country": "NG"
  },
  "to": {
    "name": "Tunde Bello",
    "phone": "+2348098765432",
    "email": "tunde@example.com",
    "line1": "5 Aminu Kano Crescent",
    "city": "Wuse",
    "state": "FCT",
    "country": "NG",
    "landmark": "Opposite the pharmacy"
  },
  "parcels": [
    {
      "package_type": "box",
      "weight_grams": 1500,
      "length_cm": 30,
      "width_cm": 20,
      "height_cm": 15,
      "description": "Shoes",
      "declared_value": 2500000
    }
  ],
  "reference": "ORDER-1042",
  "metadata": {
    "order_id": "1042"
  }
}'

200 answer

{
  "object": "rate_list",
  "environment": "sandbox",
  "reference": "ORDER-1042",
  "metadata": {
    "order_id": "1042"
  },
  "rates": [
    {
      "id": "rate_4pT9xQ2mLk8vNc3Rb7Wd1Hs5",
      "object": "rate",
      "carrier": {
        "code": "MOCK_STANDARD",
        "name": "Mock Standard (test)"
      },
      "service": {
        "code": "STANDARD",
        "name": "Standard",
        "description": "Regular door-to-door delivery"
      },
      "amount": 410000,
      "currency": "NGN",
      "charges": [
        {
          "type": "base",
          "label": "Shipping",
          "amount": 410000
        }
      ],
      "includes_insurance": false,
      "estimated_delivery": {
        "at": "2026-10-01T17:00:00.000Z",
        "transit_days": 3,
        "text": "3 business days"
      },
      "chargeable_weight_grams": 1800,
      "notices": [
        {
          "level": "info",
          "message": "Test rate — not a real carrier price"
        }
      ],
      "test": true,
      "created_at": "2026-09-28T09:15:00.000Z",
      "expires_at": "2026-09-28T09:45:00.000Z"
    }
  ],
  "messages": [],
  "created_at": "2026-09-28T09:15:00.000Z"
}

Shipments

Book, list, cancel and get labels.

get/v1/shipments

List shipments

The shipments this application booked in this environment, newest first. Pass next_cursor as cursor for the next page. With a production key, created_through=any also lists the shipments your store booked in the EviPostal dashboard or POS (created_through: "dashboard").

Scope: shipments:read
Idempotency-Key header: Not used

Parameters

List shipments parameters
Field	Type	Details
`limit`Optional	query · integer	1–100 · Default 20
`cursor`Optional	query · string	1–200 characters
`status`Optional	query · enum	One of: booking, booked, failed, picked_up, in_transit, out_for_delivery, delivered, delayed, delivery_issue, cancelled
`reference`Optional	query · string	Up to 64 characters
`tracking_number`Optional	query · string	Up to 64 characters
`created_after`Optional	query · string (date-time)	—
`created_before`Optional	query · string (date-time)	—
`created_through`Optional	query · enum	One of: api, any

Answers

200A page of shipments.
400validation_failed
401authentication_required invalid_api_key api_key_revoked
403application_disabled production_access_required insufficient_scope
429rate_limited
500internal_error

Fields in the answer

List shipments answer
Field	Type	Details
`object`Required	"list"	—
`has_more`Required	boolean	—
`next_cursor`Required	string or null	—
`data`Required	array of object	—
`data[].id`Required	string	—
`data[].object`Required	"shipment"	—
`data[].environment`Required	enum	One of: sandbox, production
`data[].status`Required	enum	One of: booking, booked, failed, picked_up, in_transit, out_for_delivery, delivered, delayed, delivery_issue, cancelled
`data[].status_detail`Required	string	—
`data[].status_updated_at`Required	string (date-time)	—
`data[].tracking_number`Required	string or null	—
`data[].reference`Required	string or null	—
`data[].metadata`Required	object of string	—
`data[].carrier`Required	object	—
`data[].carrier.code`Required	string	—
`data[].carrier.name`Required	string	—
`data[].service`Required	object	—
`data[].service.code`Required	string	—
`data[].service.name`Required	string	—
`data[].amount`Required	integer	0–9,007,199,254,740,991
`data[].currency`Required	string	—
`data[].from`Required	object	—
`data[].from.city`Required	string	—
`data[].from.state`Required	string	—
`data[].from.country`Required	string	—
`data[].to`Required	object	—
`data[].to.city`Required	string	—
`data[].to.state`Required	string	—
`data[].to.country`Required	string	—
`data[].parcels`Required	array of object	—
`data[].parcels[].package_type`Required	enum	One of: box, envelope, soft_pack
`data[].parcels[].weight_grams`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`data[].parcels[].length_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`data[].parcels[].width_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`data[].parcels[].height_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`data[].label`Required	object	—
`data[].label.status`Required	enum	One of: ready, pending, failed, unavailable
`data[].label.url`Required	string or null	—
`data[].label.format`Required	"pdf"	—
`data[].estimated_delivery_at`Required	string (date-time) or null	—
`data[].booked_at`Required	string (date-time) or null	—
`data[].cancelled_at`Required	string (date-time) or null	—
`data[].test`Required	boolean	—
`data[].created_at`Required	string (date-time)	—
`data[].created_through`Required	enum	One of: api, dashboard · Default "api"

curl "https://api.evipostal.com/v1/shipments?limit=20&status=in_transit" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY"

200 answer

{
  "object": "list",
  "data": [
    {
      "id": "shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As",
      "object": "shipment",
      "environment": "sandbox",
      "status": "booked",
      "status_detail": "Booked with Mock Standard (test)",
      "status_updated_at": "2026-09-28T09:15:02.000Z",
      "tracking_number": "EVM-3F9A1C2B7D",
      "reference": "ORDER-1042",
      "metadata": {
        "order_id": "1042"
      },
      "carrier": {
        "code": "MOCK_STANDARD",
        "name": "Mock Standard (test)"
      },
      "service": {
        "code": "STANDARD",
        "name": "Standard"
      },
      "amount": 410000,
      "currency": "NGN",
      "from": {
        "city": "Ikeja",
        "state": "Lagos",
        "country": "NG"
      },
      "to": {
        "city": "Wuse",
        "state": "FCT",
        "country": "NG"
      },
      "parcels": [
        {
          "package_type": "box",
          "weight_grams": 1500,
          "length_cm": 30,
          "width_cm": 20,
          "height_cm": 15
        }
      ],
      "label": {
        "status": "ready",
        "url": "https://api.evipostal.com/v1/shipments/shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As/label",
        "format": "pdf"
      },
      "estimated_delivery_at": "2026-10-01T17:00:00.000Z",
      "booked_at": "2026-09-28T09:15:02.000Z",
      "cancelled_at": null,
      "test": true,
      "created_at": "2026-09-28T09:15:00.000Z",
      "created_through": "api"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

post/v1/shipments

Book a shipment

Books a rate from POST /rates. An Idempotency-Key header is required: retrying with the same key never books twice. In production the rate amount is paid from your EviPostal wallet; the sandbox moves no money. 201 means booked; 202 means EviPostal is still confirming with the carrier (status booking) and a shipment.booked or shipment.booking_failed event follows.

Scope: shipments:write
Idempotency-Key header: Required

Parameters

Book a shipment parameters
Field	Type	Details
`Idempotency-Key`Required	header · string	Required. The same key and body replays the first result for 24 hours; it never books twice. Pattern ^[A-Za-z0-9_.:-]{1,255}$

Request body

Book a shipment request body
Field	Type	Details
`rate_id`Required	string	At least 1 characters
`reference`Optional	string	Up to 64 characters
`metadata`Optional	object of string	—

Answers

201Booked.
202Being confirmed with the carrier (booking).
400invalid_request validation_failed idempotency_key_required
401authentication_required invalid_api_key api_key_revoked
402insufficient_funds
403application_disabled production_access_required insufficient_scope
404not_found
409rate_expired conflict idempotency_key_in_use
413request_too_large
422booking_failed idempotency_key_reused
429rate_limited
500internal_error

Fields in the answer

Book a shipment answer
Field	Type	Details
`id`Required	string	—
`object`Required	"shipment"	—
`environment`Required	enum	One of: sandbox, production
`status`Required	enum	One of: booking, booked, failed, picked_up, in_transit, out_for_delivery, delivered, delayed, delivery_issue, cancelled
`status_detail`Required	string	—
`status_updated_at`Required	string (date-time)	—
`tracking_number`Required	string or null	—
`reference`Required	string or null	—
`metadata`Required	object of string	—
`carrier`Required	object	—
`carrier.code`Required	string	—
`carrier.name`Required	string	—
`service`Required	object	—
`service.code`Required	string	—
`service.name`Required	string	—
`amount`Required	integer	0–9,007,199,254,740,991
`currency`Required	string	—
`from`Required	object	—
`from.city`Required	string	—
`from.state`Required	string	—
`from.country`Required	string	—
`to`Required	object	—
`to.city`Required	string	—
`to.state`Required	string	—
`to.country`Required	string	—
`parcels`Required	array of object	—
`parcels[].package_type`Required	enum	One of: box, envelope, soft_pack
`parcels[].weight_grams`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`parcels[].length_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`parcels[].width_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`parcels[].height_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`label`Required	object	—
`label.status`Required	enum	One of: ready, pending, failed, unavailable
`label.url`Required	string or null	—
`label.format`Required	"pdf"	—
`estimated_delivery_at`Required	string (date-time) or null	—
`booked_at`Required	string (date-time) or null	—
`cancelled_at`Required	string (date-time) or null	—
`test`Required	boolean	—
`created_at`Required	string (date-time)	—
`created_through`Required	enum	One of: api, dashboard · Default "api"

curl -X POST "https://api.evipostal.com/v1/shipments" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "rate_id": "rate_4pT9xQ2mLk8vNc3Rb7Wd1Hs5",
  "reference": "ORDER-1042",
  "metadata": {
    "order_id": "1042"
  }
}'

201 answer

{
  "id": "shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As",
  "object": "shipment",
  "environment": "sandbox",
  "status": "booked",
  "status_detail": "Booked with Mock Standard (test)",
  "status_updated_at": "2026-09-28T09:15:02.000Z",
  "tracking_number": "EVM-3F9A1C2B7D",
  "reference": "ORDER-1042",
  "metadata": {
    "order_id": "1042"
  },
  "carrier": {
    "code": "MOCK_STANDARD",
    "name": "Mock Standard (test)"
  },
  "service": {
    "code": "STANDARD",
    "name": "Standard"
  },
  "amount": 410000,
  "currency": "NGN",
  "from": {
    "city": "Ikeja",
    "state": "Lagos",
    "country": "NG"
  },
  "to": {
    "city": "Wuse",
    "state": "FCT",
    "country": "NG"
  },
  "parcels": [
    {
      "package_type": "box",
      "weight_grams": 1500,
      "length_cm": 30,
      "width_cm": 20,
      "height_cm": 15
    }
  ],
  "label": {
    "status": "ready",
    "url": "https://api.evipostal.com/v1/shipments/shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As/label",
    "format": "pdf"
  },
  "estimated_delivery_at": "2026-10-01T17:00:00.000Z",
  "booked_at": "2026-09-28T09:15:02.000Z",
  "cancelled_at": null,
  "test": true,
  "created_at": "2026-09-28T09:15:00.000Z",
  "created_through": "api"
}

get/v1/shipments/{id}

Get a shipment

One shipment of this application and environment. A production key can also read a shipment its store booked in the EviPostal dashboard or POS, for example one named in a webhook event.

Scope: shipments:read
Idempotency-Key header: Not used

Parameters

Get a shipment parameters
Field	Type	Details
`id`Required	path · string	The shipment id (`shp_…`).

Answers

200The shipment.
401authentication_required invalid_api_key api_key_revoked
403application_disabled production_access_required insufficient_scope
404not_found
429rate_limited
500internal_error

Fields in the answer

Get a shipment answer
Field	Type	Details
`id`Required	string	—
`object`Required	"shipment"	—
`environment`Required	enum	One of: sandbox, production
`status`Required	enum	One of: booking, booked, failed, picked_up, in_transit, out_for_delivery, delivered, delayed, delivery_issue, cancelled
`status_detail`Required	string	—
`status_updated_at`Required	string (date-time)	—
`tracking_number`Required	string or null	—
`reference`Required	string or null	—
`metadata`Required	object of string	—
`carrier`Required	object	—
`carrier.code`Required	string	—
`carrier.name`Required	string	—
`service`Required	object	—
`service.code`Required	string	—
`service.name`Required	string	—
`amount`Required	integer	0–9,007,199,254,740,991
`currency`Required	string	—
`from`Required	object	—
`from.city`Required	string	—
`from.state`Required	string	—
`from.country`Required	string	—
`to`Required	object	—
`to.city`Required	string	—
`to.state`Required	string	—
`to.country`Required	string	—
`parcels`Required	array of object	—
`parcels[].package_type`Required	enum	One of: box, envelope, soft_pack
`parcels[].weight_grams`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`parcels[].length_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`parcels[].width_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`parcels[].height_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`label`Required	object	—
`label.status`Required	enum	One of: ready, pending, failed, unavailable
`label.url`Required	string or null	—
`label.format`Required	"pdf"	—
`estimated_delivery_at`Required	string (date-time) or null	—
`booked_at`Required	string (date-time) or null	—
`cancelled_at`Required	string (date-time) or null	—
`test`Required	boolean	—
`created_at`Required	string (date-time)	—
`created_through`Required	enum	One of: api, dashboard · Default "api"

curl "https://api.evipostal.com/v1/shipments/shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY"

200 answer

{
  "id": "shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As",
  "object": "shipment",
  "environment": "sandbox",
  "status": "booked",
  "status_detail": "Booked with Mock Standard (test)",
  "status_updated_at": "2026-09-28T09:15:02.000Z",
  "tracking_number": "EVM-3F9A1C2B7D",
  "reference": "ORDER-1042",
  "metadata": {
    "order_id": "1042"
  },
  "carrier": {
    "code": "MOCK_STANDARD",
    "name": "Mock Standard (test)"
  },
  "service": {
    "code": "STANDARD",
    "name": "Standard"
  },
  "amount": 410000,
  "currency": "NGN",
  "from": {
    "city": "Ikeja",
    "state": "Lagos",
    "country": "NG"
  },
  "to": {
    "city": "Wuse",
    "state": "FCT",
    "country": "NG"
  },
  "parcels": [
    {
      "package_type": "box",
      "weight_grams": 1500,
      "length_cm": 30,
      "width_cm": 20,
      "height_cm": 15
    }
  ],
  "label": {
    "status": "ready",
    "url": "https://api.evipostal.com/v1/shipments/shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As/label",
    "format": "pdf"
  },
  "estimated_delivery_at": "2026-10-01T17:00:00.000Z",
  "booked_at": "2026-09-28T09:15:02.000Z",
  "cancelled_at": null,
  "test": true,
  "created_at": "2026-09-28T09:15:00.000Z",
  "created_through": "api"
}

post/v1/shipments/{id}/cancel

Cancel a shipment

Cancels a booked shipment before the carrier picks it up. Production charges go back to your wallet. No request body. A shipment booked in the EviPostal dashboard or POS is cancelled there, not through the API (409 conflict).

Scope: shipments:write
Idempotency-Key header: Optional, recommended

Parameters

Cancel a shipment parameters
Field	Type	Details
`id`Required	path · string	The shipment id (`shp_…`).
`Idempotency-Key`Optional	header · string	Makes a retry safe: the same key and body replays the first result for 24 hours. Pattern ^[A-Za-z0-9_.:-]{1,255}$

Answers

200Cancelled.
401authentication_required invalid_api_key api_key_revoked
403application_disabled production_access_required insufficient_scope
404not_found
409conflict idempotency_key_in_use
422unsupported_operation idempotency_key_reused
429rate_limited
500internal_error
503carrier_unavailable

Fields in the answer

Cancel a shipment answer
Field	Type	Details
`id`Required	string	—
`object`Required	"shipment"	—
`environment`Required	enum	One of: sandbox, production
`status`Required	enum	One of: booking, booked, failed, picked_up, in_transit, out_for_delivery, delivered, delayed, delivery_issue, cancelled
`status_detail`Required	string	—
`status_updated_at`Required	string (date-time)	—
`tracking_number`Required	string or null	—
`reference`Required	string or null	—
`metadata`Required	object of string	—
`carrier`Required	object	—
`carrier.code`Required	string	—
`carrier.name`Required	string	—
`service`Required	object	—
`service.code`Required	string	—
`service.name`Required	string	—
`amount`Required	integer	0–9,007,199,254,740,991
`currency`Required	string	—
`from`Required	object	—
`from.city`Required	string	—
`from.state`Required	string	—
`from.country`Required	string	—
`to`Required	object	—
`to.city`Required	string	—
`to.state`Required	string	—
`to.country`Required	string	—
`parcels`Required	array of object	—
`parcels[].package_type`Required	enum	One of: box, envelope, soft_pack
`parcels[].weight_grams`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`parcels[].length_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`parcels[].width_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`parcels[].height_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`label`Required	object	—
`label.status`Required	enum	One of: ready, pending, failed, unavailable
`label.url`Required	string or null	—
`label.format`Required	"pdf"	—
`estimated_delivery_at`Required	string (date-time) or null	—
`booked_at`Required	string (date-time) or null	—
`cancelled_at`Required	string (date-time) or null	—
`test`Required	boolean	—
`created_at`Required	string (date-time)	—
`created_through`Required	enum	One of: api, dashboard · Default "api"

curl -X POST "https://api.evipostal.com/v1/shipments/shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As/cancel" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

200 answer

{
  "id": "shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As",
  "object": "shipment",
  "environment": "sandbox",
  "status": "cancelled",
  "status_detail": "This shipment was cancelled",
  "status_updated_at": "2026-09-28T10:02:00.000Z",
  "tracking_number": "EVM-3F9A1C2B7D",
  "reference": "ORDER-1042",
  "metadata": {
    "order_id": "1042"
  },
  "carrier": {
    "code": "MOCK_STANDARD",
    "name": "Mock Standard (test)"
  },
  "service": {
    "code": "STANDARD",
    "name": "Standard"
  },
  "amount": 410000,
  "currency": "NGN",
  "from": {
    "city": "Ikeja",
    "state": "Lagos",
    "country": "NG"
  },
  "to": {
    "city": "Wuse",
    "state": "FCT",
    "country": "NG"
  },
  "parcels": [
    {
      "package_type": "box",
      "weight_grams": 1500,
      "length_cm": 30,
      "width_cm": 20,
      "height_cm": 15
    }
  ],
  "label": {
    "status": "ready",
    "url": "https://api.evipostal.com/v1/shipments/shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As/label",
    "format": "pdf"
  },
  "estimated_delivery_at": "2026-10-01T17:00:00.000Z",
  "booked_at": "2026-09-28T09:15:02.000Z",
  "cancelled_at": "2026-09-28T10:02:00.000Z",
  "test": true,
  "created_at": "2026-09-28T09:15:00.000Z",
  "created_through": "api"
}

get/v1/shipments/{id}/label

Download the label

The shipping label as a PDF. While the carrier is still preparing it the answer is 409 label_not_ready with Retry-After.

Scope: labels:read
Idempotency-Key header: Not used

Parameters

Download the label parameters
Field	Type	Details
`id`Required	path · string	The shipment id (`shp_…`).

Answers

200The label PDF.
401authentication_required invalid_api_key api_key_revoked
403application_disabled production_access_required insufficient_scope
404not_found
409conflict label_not_ready
422unsupported_operation
429rate_limited
500internal_error

curl "https://api.evipostal.com/v1/shipments/shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As/label" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY" \
  -o label.pdf

Tracking

Where a shipment is.

get/v1/shipments/{id}/tracking

Get tracking

Status and tracking history, newest first, in the same customer-safe words as the EviPostal tracking page.

Scope: tracking:read
Idempotency-Key header: Not used

Parameters

Get tracking parameters
Field	Type	Details
`id`Required	path · string	The shipment id (`shp_…`).

Answers

200Tracking.
401authentication_required invalid_api_key api_key_revoked
403application_disabled production_access_required insufficient_scope
404not_found
429rate_limited
500internal_error

Fields in the answer

Get tracking answer
Field	Type	Details
`object`Required	"tracking"	—
`environment`Required	enum	One of: sandbox, production
`shipment_id`Required	string	—
`tracking_number`Required	string or null	—
`status`Required	enum	One of: booking, booked, failed, picked_up, in_transit, out_for_delivery, delivered, delayed, delivery_issue, cancelled
`status_detail`Required	string	—
`next_step`Required	string or null	—
`status_updated_at`Required	string (date-time)	—
`estimated_delivery_at`Required	string (date-time) or null	—
`carrier`Required	object	—
`carrier.code`Required	string	—
`carrier.name`Required	string	—
`test`Required	boolean	—
`events`Required	array of object	—
`events[].type`Required	enum	One of: booked, label_ready, picked_up, in_transit, out_for_delivery, delivered, delayed, delivery_issue, cancelled, info
`events[].description`Required	string	—
`events[].location`Required	string or null	—
`events[].occurred_at`Required	string (date-time)	—

curl "https://api.evipostal.com/v1/shipments/shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As/tracking" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY"

200 answer

{
  "object": "tracking",
  "environment": "sandbox",
  "shipment_id": "shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As",
  "tracking_number": "EVM-3F9A1C2B7D",
  "status": "picked_up",
  "status_detail": "The carrier has the package",
  "next_step": "It will move to the next stop soon",
  "status_updated_at": "2026-09-28T13:40:00.000Z",
  "estimated_delivery_at": "2026-10-01T17:00:00.000Z",
  "carrier": {
    "code": "MOCK_STANDARD",
    "name": "Mock Standard (test)"
  },
  "test": true,
  "events": [
    {
      "type": "picked_up",
      "description": "Picked up by the carrier in Ikeja",
      "location": "Ikeja",
      "occurred_at": "2026-09-28T13:40:00.000Z"
    },
    {
      "type": "label_ready",
      "description": "Shipping label created",
      "location": null,
      "occurred_at": "2026-09-28T09:15:02.000Z"
    },
    {
      "type": "booked",
      "description": "Booked with Mock Standard (test) (Standard)",
      "location": null,
      "occurred_at": "2026-09-28T09:15:02.000Z"
    }
  ]
}

Webhooks

Events and the endpoints that receive them.

get/v1/events

List events

Every event of this application and environment, newest first — the same objects webhooks deliver. Use it to catch up on missed webhooks.

Scope: webhooks:read
Idempotency-Key header: Not used

Parameters

List events parameters
Field	Type	Details
`limit`Optional	query · integer	1–100 · Default 20
`cursor`Optional	query · string	1–200 characters
`type`Optional	query · enum	One of: shipment.booked, shipment.booking_failed, shipment.updated, shipment.delayed, shipment.exception, shipment.delivered, shipment.cancelled, webhook.test
`shipment_id`Optional	query · string	Up to 64 characters

Answers

200A page of events.
400validation_failed
401authentication_required invalid_api_key api_key_revoked
403application_disabled production_access_required insufficient_scope
429rate_limited
500internal_error

Fields in the answer

List events answer
Field	Type	Details
`object`Required	"list"	—
`has_more`Required	boolean	—
`next_cursor`Required	string or null	—
`data`Required	array of object	—
`data[].id`Required	string	—
`data[].object`Required	"event"	—
`data[].type`Required	enum	One of: shipment.booked, shipment.booking_failed, shipment.updated, shipment.delayed, shipment.exception, shipment.delivered, shipment.cancelled, webhook.test
`data[].api_version`Required	"v1"	—
`data[].environment`Required	enum	One of: sandbox, production
`data[].created_at`Required	string (date-time)	—
`data[].data`Required	object	—
`data[].data.shipment`Optional	object	—
`data[].data.shipment.id`Required	string	—
`data[].data.shipment.object`Required	"shipment"	—
`data[].data.shipment.environment`Required	enum	One of: sandbox, production
`data[].data.shipment.status`Required	enum	One of: booking, booked, failed, picked_up, in_transit, out_for_delivery, delivered, delayed, delivery_issue, cancelled
`data[].data.shipment.status_detail`Required	string	—
`data[].data.shipment.status_updated_at`Required	string (date-time)	—
`data[].data.shipment.tracking_number`Required	string or null	—
`data[].data.shipment.reference`Required	string or null	—
`data[].data.shipment.metadata`Required	object of string	—
`data[].data.shipment.carrier`Required	object	—
`data[].data.shipment.carrier.code`Required	string	—
`data[].data.shipment.carrier.name`Required	string	—
`data[].data.shipment.service`Required	object	—
`data[].data.shipment.service.code`Required	string	—
`data[].data.shipment.service.name`Required	string	—
`data[].data.shipment.amount`Required	integer	0–9,007,199,254,740,991
`data[].data.shipment.currency`Required	string	—
`data[].data.shipment.from`Required	object	—
`data[].data.shipment.from.city`Required	string	—
`data[].data.shipment.from.state`Required	string	—
`data[].data.shipment.from.country`Required	string	—
`data[].data.shipment.to`Required	object	—
`data[].data.shipment.to.city`Required	string	—
`data[].data.shipment.to.state`Required	string	—
`data[].data.shipment.to.country`Required	string	—
`data[].data.shipment.parcels`Required	array of object	—
`data[].data.shipment.parcels[].package_type`Required	enum	One of: box, envelope, soft_pack
`data[].data.shipment.parcels[].weight_grams`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`data[].data.shipment.parcels[].length_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`data[].data.shipment.parcels[].width_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`data[].data.shipment.parcels[].height_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`data[].data.shipment.label`Required	object	—
`data[].data.shipment.label.status`Required	enum	One of: ready, pending, failed, unavailable
`data[].data.shipment.label.url`Required	string or null	—
`data[].data.shipment.label.format`Required	"pdf"	—
`data[].data.shipment.estimated_delivery_at`Required	string (date-time) or null	—
`data[].data.shipment.booked_at`Required	string (date-time) or null	—
`data[].data.shipment.cancelled_at`Required	string (date-time) or null	—
`data[].data.shipment.test`Required	boolean	—
`data[].data.shipment.created_at`Required	string (date-time)	—
`data[].data.shipment.created_through`Required	enum	One of: api, dashboard · Default "api"
`data[].data.tracking_events`Optional	array of object	—
`data[].data.tracking_events[].type`Required	enum	One of: booked, label_ready, picked_up, in_transit, out_for_delivery, delivered, delayed, delivery_issue, cancelled, info
`data[].data.tracking_events[].description`Required	string	—
`data[].data.tracking_events[].location`Required	string or null	—
`data[].data.tracking_events[].occurred_at`Required	string (date-time)	—
`data[].data.message`Optional	string	—

curl "https://api.evipostal.com/v1/events?limit=20&type=shipment.updated" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY"

200 answer

{
  "object": "list",
  "data": [
    {
      "id": "evt_2Wq7Er4Ty9Ui3Op6As1Df8Gh5",
      "object": "event",
      "type": "shipment.updated",
      "api_version": "v1",
      "environment": "sandbox",
      "created_at": "2026-09-28T13:40:00.000Z",
      "data": {
        "shipment": {
          "id": "shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As",
          "object": "shipment",
          "environment": "sandbox",
          "status": "picked_up",
          "status_detail": "The carrier has the package",
          "status_updated_at": "2026-09-28T13:40:00.000Z",
          "tracking_number": "EVM-3F9A1C2B7D",
          "reference": "ORDER-1042",
          "metadata": {
            "order_id": "1042"
          },
          "carrier": {
            "code": "MOCK_STANDARD",
            "name": "Mock Standard (test)"
          },
          "service": {
            "code": "STANDARD",
            "name": "Standard"
          },
          "amount": 410000,
          "currency": "NGN",
          "from": {
            "city": "Ikeja",
            "state": "Lagos",
            "country": "NG"
          },
          "to": {
            "city": "Wuse",
            "state": "FCT",
            "country": "NG"
          },
          "parcels": [
            {
              "package_type": "box",
              "weight_grams": 1500,
              "length_cm": 30,
              "width_cm": 20,
              "height_cm": 15
            }
          ],
          "label": {
            "status": "ready",
            "url": "https://api.evipostal.com/v1/shipments/shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As/label",
            "format": "pdf"
          },
          "estimated_delivery_at": "2026-10-01T17:00:00.000Z",
          "booked_at": "2026-09-28T09:15:02.000Z",
          "cancelled_at": null,
          "test": true,
          "created_at": "2026-09-28T09:15:00.000Z",
          "created_through": "api"
        },
        "tracking_events": [
          {
            "type": "picked_up",
            "description": "Picked up by the carrier in Ikeja",
            "location": "Ikeja",
            "occurred_at": "2026-09-28T13:40:00.000Z"
          }
        ]
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

get/v1/events/{id}

Get an event

One event by id (evt_…).

Scope: webhooks:read
Idempotency-Key header: Not used

Parameters

Get an event parameters
Field	Type	Details
`id`Required	path · string	The event id (`evt_…`).

Answers

200The event.
401authentication_required invalid_api_key api_key_revoked
403application_disabled production_access_required insufficient_scope
404not_found
429rate_limited
500internal_error

Fields in the answer

Get an event answer
Field	Type	Details
`id`Required	string	—
`object`Required	"event"	—
`type`Required	enum	One of: shipment.booked, shipment.booking_failed, shipment.updated, shipment.delayed, shipment.exception, shipment.delivered, shipment.cancelled, webhook.test
`api_version`Required	"v1"	—
`environment`Required	enum	One of: sandbox, production
`created_at`Required	string (date-time)	—
`data`Required	object	—
`data.shipment`Optional	object	—
`data.shipment.id`Required	string	—
`data.shipment.object`Required	"shipment"	—
`data.shipment.environment`Required	enum	One of: sandbox, production
`data.shipment.status`Required	enum	One of: booking, booked, failed, picked_up, in_transit, out_for_delivery, delivered, delayed, delivery_issue, cancelled
`data.shipment.status_detail`Required	string	—
`data.shipment.status_updated_at`Required	string (date-time)	—
`data.shipment.tracking_number`Required	string or null	—
`data.shipment.reference`Required	string or null	—
`data.shipment.metadata`Required	object of string	—
`data.shipment.carrier`Required	object	—
`data.shipment.carrier.code`Required	string	—
`data.shipment.carrier.name`Required	string	—
`data.shipment.service`Required	object	—
`data.shipment.service.code`Required	string	—
`data.shipment.service.name`Required	string	—
`data.shipment.amount`Required	integer	0–9,007,199,254,740,991
`data.shipment.currency`Required	string	—
`data.shipment.from`Required	object	—
`data.shipment.from.city`Required	string	—
`data.shipment.from.state`Required	string	—
`data.shipment.from.country`Required	string	—
`data.shipment.to`Required	object	—
`data.shipment.to.city`Required	string	—
`data.shipment.to.state`Required	string	—
`data.shipment.to.country`Required	string	—
`data.shipment.parcels`Required	array of object	—
`data.shipment.parcels[].package_type`Required	enum	One of: box, envelope, soft_pack
`data.shipment.parcels[].weight_grams`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`data.shipment.parcels[].length_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`data.shipment.parcels[].width_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`data.shipment.parcels[].height_cm`Required	integer	-9,007,199,254,740,991–9,007,199,254,740,991
`data.shipment.label`Required	object	—
`data.shipment.label.status`Required	enum	One of: ready, pending, failed, unavailable
`data.shipment.label.url`Required	string or null	—
`data.shipment.label.format`Required	"pdf"	—
`data.shipment.estimated_delivery_at`Required	string (date-time) or null	—
`data.shipment.booked_at`Required	string (date-time) or null	—
`data.shipment.cancelled_at`Required	string (date-time) or null	—
`data.shipment.test`Required	boolean	—
`data.shipment.created_at`Required	string (date-time)	—
`data.shipment.created_through`Required	enum	One of: api, dashboard · Default "api"
`data.tracking_events`Optional	array of object	—
`data.tracking_events[].type`Required	enum	One of: booked, label_ready, picked_up, in_transit, out_for_delivery, delivered, delayed, delivery_issue, cancelled, info
`data.tracking_events[].description`Required	string	—
`data.tracking_events[].location`Required	string or null	—
`data.tracking_events[].occurred_at`Required	string (date-time)	—
`data.message`Optional	string	—

curl "https://api.evipostal.com/v1/events/evt_2Wq7Er4Ty9Ui3Op6As1Df8Gh5" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY"

200 answer

{
  "id": "evt_2Wq7Er4Ty9Ui3Op6As1Df8Gh5",
  "object": "event",
  "type": "shipment.updated",
  "api_version": "v1",
  "environment": "sandbox",
  "created_at": "2026-09-28T13:40:00.000Z",
  "data": {
    "shipment": {
      "id": "shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As",
      "object": "shipment",
      "environment": "sandbox",
      "status": "picked_up",
      "status_detail": "The carrier has the package",
      "status_updated_at": "2026-09-28T13:40:00.000Z",
      "tracking_number": "EVM-3F9A1C2B7D",
      "reference": "ORDER-1042",
      "metadata": {
        "order_id": "1042"
      },
      "carrier": {
        "code": "MOCK_STANDARD",
        "name": "Mock Standard (test)"
      },
      "service": {
        "code": "STANDARD",
        "name": "Standard"
      },
      "amount": 410000,
      "currency": "NGN",
      "from": {
        "city": "Ikeja",
        "state": "Lagos",
        "country": "NG"
      },
      "to": {
        "city": "Wuse",
        "state": "FCT",
        "country": "NG"
      },
      "parcels": [
        {
          "package_type": "box",
          "weight_grams": 1500,
          "length_cm": 30,
          "width_cm": 20,
          "height_cm": 15
        }
      ],
      "label": {
        "status": "ready",
        "url": "https://api.evipostal.com/v1/shipments/shp_8Jk2Lm9Qw3Er5Ty7Ui1Op4As/label",
        "format": "pdf"
      },
      "estimated_delivery_at": "2026-10-01T17:00:00.000Z",
      "booked_at": "2026-09-28T09:15:02.000Z",
      "cancelled_at": null,
      "test": true,
      "created_at": "2026-09-28T09:15:00.000Z",
      "created_through": "api"
    },
    "tracking_events": [
      {
        "type": "picked_up",
        "description": "Picked up by the carrier in Ikeja",
        "location": "Ikeja",
        "occurred_at": "2026-09-28T13:40:00.000Z"
      }
    ]
  }
}

get/v1/webhook-endpoints

List webhook endpoints

The webhook endpoints of this application and environment.

Scope: webhooks:read
Idempotency-Key header: Not used

Answers

200The endpoints.
401authentication_required invalid_api_key api_key_revoked
403application_disabled production_access_required insufficient_scope
429rate_limited
500internal_error

Fields in the answer

List webhook endpoints answer
Field	Type	Details
`object`Required	"list"	—
`has_more`Required	boolean	—
`next_cursor`Required	string or null	—
`data`Required	array of object	—
`data[].id`Required	string	—
`data[].object`Required	"webhook_endpoint"	—
`data[].environment`Required	enum	One of: sandbox, production
`data[].url`Required	string	—
`data[].description`Required	string or null	—
`data[].event_types`Required	array of enum	Each one of: shipment.booked, shipment.booking_failed, shipment.updated, shipment.delayed, shipment.exception, shipment.delivered, shipment.cancelled, webhook.test
`data[].enabled`Required	boolean	—
`data[].created_at`Required	string (date-time)	—

curl "https://api.evipostal.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY"

200 answer

{
  "object": "list",
  "data": [
    {
      "id": "we_6Zx3Cv8Bn1Mq4Wr7Te2Yu9Io0",
      "object": "webhook_endpoint",
      "environment": "sandbox",
      "url": "https://example.com/webhooks/evipostal",
      "description": "Order system",
      "event_types": [],
      "enabled": true,
      "created_at": "2026-09-28T09:15:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

post/v1/webhook-endpoints

Add a webhook endpoint

Adds an https URL that receives signed events. The response is the only time the signing secret is shown: store it. Up to 5 endpoints per application and environment. Leave event_types empty to receive every event type.

Scope: webhooks:write
Idempotency-Key header: Optional, recommended

Parameters

Add a webhook endpoint parameters
Field	Type	Details
`Idempotency-Key`Optional	header · string	Makes a retry safe: the same key and body replays the first result for 24 hours. Pattern ^[A-Za-z0-9_.:-]{1,255}$

Request body

Add a webhook endpoint request body
Field	Type	Details
`url`Required	string	Up to 2048 characters · A full URL
`description`Optional	string	Up to 200 characters
`event_types`Optional	array of enum	Each one of: shipment.booked, shipment.booking_failed, shipment.updated, shipment.delayed, shipment.exception, shipment.delivered, shipment.cancelled, webhook.test · Up to 8 items · Default []

Answers

201Created, with its signing secret.
400invalid_request validation_failed
401authentication_required invalid_api_key api_key_revoked
403application_disabled production_access_required insufficient_scope
409conflict idempotency_key_in_use
413request_too_large
422idempotency_key_reused
429rate_limited
500internal_error

Fields in the answer

Add a webhook endpoint answer
Field	Type	Details
`id`Required	string	—
`object`Required	"webhook_endpoint"	—
`environment`Required	enum	One of: sandbox, production
`url`Required	string	—
`description`Required	string or null	—
`event_types`Required	array of enum	Each one of: shipment.booked, shipment.booking_failed, shipment.updated, shipment.delayed, shipment.exception, shipment.delivered, shipment.cancelled, webhook.test
`enabled`Required	boolean	—
`created_at`Required	string (date-time)	—
`secret`Required	string	—

curl -X POST "https://api.evipostal.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhooks/evipostal",
  "description": "Order system",
  "event_types": []
}'

201 answer

{
  "id": "we_6Zx3Cv8Bn1Mq4Wr7Te2Yu9Io0",
  "object": "webhook_endpoint",
  "environment": "sandbox",
  "url": "https://example.com/webhooks/evipostal",
  "description": "Order system",
  "event_types": [],
  "enabled": true,
  "created_at": "2026-09-28T09:15:00.000Z",
  "secret": "whsec_EXAMPLEdoNotUseThisSecretValue00"
}

delete/v1/webhook-endpoints/{id}

Delete a webhook endpoint

Stops deliveries to the endpoint. Pending deliveries to it are marked failed.

Scope: webhooks:write
Idempotency-Key header: Not used

Parameters

Delete a webhook endpoint parameters
Field	Type	Details
`id`Required	path · string	The endpoint id (`we_…`).

Answers

204Deleted.
401authentication_required invalid_api_key api_key_revoked
403application_disabled production_access_required insufficient_scope
404not_found
429rate_limited
500internal_error

curl -X DELETE "https://api.evipostal.com/v1/webhook-endpoints/we_6Zx3Cv8Bn1Mq4Wr7Te2Yu9Io0" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY"

Reference

This document.

get/v1/openapi.json

This OpenAPI document

The OpenAPI 3.1 description of the EviPostal API v1. No API key needed.

Scope: None needed
Idempotency-Key header: Not used

Answers

200The OpenAPI document.
500internal_error

curl "https://api.evipostal.com/v1/openapi.json"

Webhook events

Sent to your endpoints as a POST with the event as the body. See Webhooks for signing and retries. The body is the same Event object that GET /events returns.

shipment.bookedThe carrier confirmed the booking (immediately, or after a booking status).
shipment.booking_failedA booking that was being confirmed did not happen. Nothing was charged.
shipment.updatedA new tracking update arrived (picked up, in transit, out for delivery, or a timeline note).
shipment.delayedThe carrier reported a delay.
shipment.exceptionThe carrier reported a problem: failed pickup, failed delivery or an address issue.
shipment.deliveredThe package was delivered.
shipment.cancelledThe shipment was cancelled.
webhook.testSent only when you press "Send test event" in the developer portal.