Getting Started

This guide takes a ShipPack developer from identity registration through a safe sandbox shipment and into the production-access review process.

Dashboard operations use your ShipPack user session. Server-to-server shipment operations use an application secret key. Keeping those two authentication contexts separate is essential.

Before You Begin

You will need:

A verified email address and a strong password.
A backend capable of protecting application secret keys.
A public HTTPS endpoint if you plan to receive webhooks.
A clear production use case before requesting live access.

Existing ShipPack users

If your email already belongs to a customer, driver, company, entity, vendor, or supplier profile, register with the existing password and verify the emailed OTP. Developer access is attached to the same user identity; a duplicate user is not created.

Developer identity model

Developer is a first-class ShipPack profile and is not represented as a customer account. A first-time developer receives an identity whose primary and profile types are developer. For an eligible existing user, developer is added to the same user's profile_types collection.

Register a Developer Profile

http

POST https://dev.api.theshippack.com/api/v1/auth/register
X-App-Type: developer
Content-Type: application/json

Registration payload

JSON

{
  "first_name": "Ada",
  "last_name": "Lovelace",
  "email": "developer@example.com",
  "password": "StrongPassword123!",
  "password_confirmation": "StrongPassword123!",
  "country_code": "NG",
  "accepted_terms": true
}

Phone numbers are optional

Omit phone_number for an email-only developer account. If supplied, it must be globally unique across all ShipPack identities. Admin and support-agent identities cannot be combined with public developer registration.

Verify Developer Access

Verify the emailed OTP using the same app header.

http

POST https://dev.api.theshippack.com/api/v1/auth/verify
X-App-Type: developer

After a new registration or eligible existing-user profile attachment, ShipPack automatically provisions one developer_accounts row for the identity. Applications, credentials, shipments, and webhook endpoints belong to that developer account.

Sign In to the Dashboard

Subsequent sessions use the normal login payload with the developer app header.

http

POST https://dev.api.theshippack.com/api/v1/auth/login
X-App-Type: developer
Content-Type: application/json

JSON

{
  "email": "developer@example.com",
  "password": "StrongPassword123!",
  "device_name": "Developer Dashboard"
}

Use the returned Sanctum user token for dashboard endpoints:

http

Authorization: Bearer USER_ACCESS_TOKEN
X-App-Type: developer

Create an Application and Sandbox Key

Create an integration application, then create a sandbox key that belongs to it.

http

POST /developer/applications
POST /developer/applications/{applicationId}/api-keys

API key payload

JSON

{
  "name": "Backend sandbox key",
  "environment": "sandbox",
  "expiresAt": null
}

Copy the secret immediately

The complete secret is returned only at creation. ShipPack stores its hash and metadata, so a lost secret must be replaced or rotated rather than retrieved.

Understand the Environments

Both environments use the same API base URL; the credential determines behavior.

https://dev.api.theshippack.com/api/v1/developer

Environment	Key prefix	References	Behavior
Sandbox	sk_test_	SPTEST / TRKTEST	Simulated; no charge or driver
Production	sk_live_	Operational references	Approval required; wallet submission only in MVP

Sandbox is isolated

Sandbox creates no operational shipment, charges no wallet, card, or payment provider, and assigns no driver. Sandbox lifecycle changes occur only through the simulation endpoint.

Load Shipment Catalogs

Use the application key to load the credential context and valid shipment catalog options.

http

GET /developer/credentials
GET /developer/package-sizes
GET /developer/delivery-types
GET /developer/delivery-options?origins=LAT,LNG&destinations=LAT,LNG

Use returned packageSizeId and deliveryTypeId values when creating a shipment.

Create a Sandbox Shipment

http

POST /developer/shipments

Request body

JSON

{
  "pickup": "Lekki Phase 1, Lagos, Nigeria",
  "pickupLat": 6.4488,
  "pickupLng": 3.472,
  "pickupCountry": "NG",
  "dropoffCountry": "NG",
  "destinationDetails": {
    "dropoff": "Wuse 2, Abuja, Nigeria",
    "dropoffLat": 9.0765,
    "dropoffLng": 7.4983,
    "recipient": {
      "name": "Adebayo Test",
      "phoneNumber": "+2348012345678"
    }
  },
  "shipmentMode": "LAND",
  "shipperMode": "AUTO",
  "packageSizeId": "PACKAGE_SIZE_ID",
  "deliveryTypeId": "DELIVERY_TYPE_ID",
  "packageDescription": "Documents and clothes",
  "attachments": [],
  "submit": false
}

Set submit to false to save without payment submission. Test references start with SPTEST and tracking IDs start with TRKTEST.

Simulate the Shipment Lifecycle

http

POST /developer/shipments/{shipmentId}/simulate

Request body

JSON

{
  "status": "ASSIGNED"
}

Valid sandbox sequence

PENDING
ASSIGNED
PICKED_UP
IN_TRANSIT
OUT_FOR_DELIVERY
DELIVERED

Each non-terminal status may also transition to FAILED.

Register a Sandbox Webhook

http

POST /developer/applications/{applicationId}/webhooks

Request body

JSON

{
  "environment": "sandbox",
  "url": "https://example.com/webhooks/shippack",
  "description": "Shipment lifecycle handler",
  "events": [
    "shipment.created",
    "shipment.assigned",
    "shipment.picked_up",
    "shipment.in_transit",
    "shipment.out_for_delivery",
    "shipment.delivered",
    "shipment.cancelled",
    "shipment.failed"
  ]
}

Webhook URL requirements

The callback must use HTTPS and cannot point to localhost, private, reserved, or locally resolving addresses. DNS is checked again immediately before every delivery.

Request Production Access

Submit a meaningful operational reason from the application. An administrator must approve it before a production key can be created.

http

POST /developer/applications/{applicationId}/production-access

Request body

JSON

{
  "reason": "We will create deliveries for paid ecommerce orders from our backend checkout workflow."
}

After approval, create an API key with environment set to production.
Register a production webhook endpoint for the lifecycle events your application consumes.
Production keys begin with sk_live_.
Production callers cannot select a ShipPack user ID; user-service generates the internal identity from the application owner.
Caller-supplied prices are discarded.
The current MVP accepts paymentMethod: wallet when submit is true.
Application shipment mappings prevent cross-application access.

What would you like to explore

Personal details

Getting Started

Before You Begin

Register a Developer Profile

Verify Developer Access

Create an Application and Sandbox Key

Understand the Environments

Load Shipment Catalogs

Create a Sandbox Shipment

Simulate the Shipment Lifecycle

Register a Sandbox Webhook

Request Production Access