Authentication

Use your client_id and client_secret to obtain a Bearer token. Include this token in all subsequent requests via the Authorization header. Tokens do not expire automatically — re-authenticate if you receive a 401 response.

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

{
  "success": true,
  "token_type": "Bearer",
  "access_token": "1|...",
  "message": "Access token generated successfully."
}

cURL Example

curl --request POST '{BASE_URL}/auth/token' \
    --header 'Content-Type: application/json' \
    --data '{
        "client_id": "your_client_id",
        "client_secret": "your_client_secret"
    }'

Master Data

Returns all active regions available for service coverage. Use the region id when querying services.

GET {BASE_URL}/regions

{
  "success": true,
  "data": [
    {"id": 1, "name": "Panamá", "iso_code": "PA-8"}
  ]
}

cURL Example

curl --request GET '{BASE_URL}/regions' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

Services & Prices

Returns available services and prices for a given region. Filter by weight to see only services that accept the parcel.

Request Parameters

GET {BASE_URL}/services?region_id=1&origin_region_id=2&weight=2.5

{
  "success": true,
  "data": [
    {
      "id": 12,
      "rate_name": "Door-to-Door",
      "rate_type": "Door-to-Door",
      "min_weight": 0.0,
      "max_weight": 5.0,
      "price": 4.99,
      "return_charge": 0.0,
      "weight_unit": "lb",
      "courier": {
        "id": 3,
        "name": "Shippea Express",
        "logo_url": "https://..."
      },
      "agency": {
        "id": 2,
        "name": "Agency Name",
        "region_id": 1
      }
    }
  ]
}

cURL Example

curl --request GET '{BASE_URL}/services?region_id=1&origin_region_id=2&weight=2.5' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

Customers

Creates a customer account for shipment ownership. If the email already exists, returns the existing customer information — no duplicate is created.

Request Body Fields

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "+50760000000",
  "password": "optionalStrongPassword"
}

{
  "success": true,
  "message": "Customer account created successfully.",
  "data": {
    "customer_uuid": "...",
    "email": "john@example.com"
  }
}

cURL Example

curl --request POST '{BASE_URL}/customers' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com",
        "phone": "+50760000000",
        "password": "optionalStrongPassword"
    }'

Shipments

Shipment Lifecycle

Shippea supports listing, creation, payment, tracking, label retrieval, and cancellation. In the standard flow, shipment creation debits the wallet immediately and queues label generation asynchronously.

GET {BASE_URL}/shipments?status=label_created&per_page=20

{
  "success": true,
  "data": [
    {
      "shipment_id": 991,
      "tracking_number": "4001234",
      "order_number": "ORDER-1001",
      "status": "label_created",
      "is_paid": true,
      "total_price": 4.99,
      "currency": "USD",
      "label_url": "https://...",
      "created_at": "2026-06-12 10:00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 145,
    "last_page": 8
  }
}

curl --request GET '{BASE_URL}/shipments?per_page=20' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

{
  "order_number": "ORDER-1001",
  "service_name": "Door-to-Door",
  "customer": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+50760000000"
  },
  "sender_details": {
    "name": "My Store",
    "email": "store@example.com",
    "address": "Sender Street 45",
    "city": "Panamá",
    "country": "Panama",
    "province_code": "PA-8",
    "zip": "0801",
    "phone": "+50761110000",
    "latitude": 8.9824,
    "longitude": -79.5199
  },
  "receiver_details": {
    "name": "John Doe",
    "email": "john@example.com",
    "address": "Street 123",
    "city": "Panamá",
    "country": "Panama",
    "province_code": "PA-8",
    "zip": "0801",
    "phone": "+50760000000",
    "latitude": 8.9943,
    "longitude": -79.5188
  },
  "items_information": [
    {
      "title": "Shoes",
      "sku": "SHOE-001",
      "quantity": 1,
      "weight": 1.2,
      "length": 12,
      "width": 8,
      "height": 5,
      "package_type": "Box",
      "declared_value": 35
    }
  ]
}

{
  "success": true,
  "message": "Shipment created and payment processed. Label generation has been queued.",
  "data": {
    "shipment_id": 991,
    "tracking_number": "4001234",
    "status": "label_created",
    "is_paid": true,
    "payment_method": "shippea_wallet",
    "total_price": 4.99,
    "currency": "USD",
    "wallet_balance": 195.01,
    "service": {
      "id": 12,
      "name": "Door-to-Door",
      "type": "Door-to-Door"
    },
    "calculation": {
      "total_items": 1,
      "total_weight": 1.2,
      "total_declared_value": 35,
      "base_price": 4.99,
      "return_fee": 0,
      "final_price": 4.99
    },
    "items": [
      {
        "id": 1,
        "title": "Shoes",
        "sku": "SHOE-001",
        "quantity": 1,
        "weight": 1.2
      }
    ]
  }
}

curl --request POST '{BASE_URL}/shipments' \
    --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
        "order_number": "ORDER-1001",
        "service_name": "Door-to-Door",
        "sender_details": {
            "name": "My Store",
            "address": "Sender Street 45",
            "city": "Panamá",
            "country": "Panama",
            "province_code": "PA-8",
            "latitude": 8.9824,
            "longitude": -79.5199
        },
        "receiver_details": {
            "address": "Street 123",
            "city": "Panamá",
            "country": "Panama",
            "province_code": "PA-8",
            "latitude": 8.9943,
            "longitude": -79.5188
        },
        "items_information": [{"title":"Shoes","quantity":1,"weight":1.2}]
    }'

POST {BASE_URL}/shipments/4001234/pay

{
  "success": true,
  "message": "Payment successful. Label generation has been queued.",
  "data": {
    "tracking_number": "4001234",
    "status": "label_created",
    "transaction_id": "TXN-...",
    "amount_charged": 4.99,
    "currency": "USD"
  }
}

curl --request POST '{BASE_URL}/shipments/4001234/pay' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

GET {BASE_URL}/shipments/4001234

{
  "success": true,
  "data": {
    "tracking_number": "4001234",
    "order_number": "ORDER-1001",
    "status": "in_transit",
    "is_paid": true
  }
}

curl --request GET '{BASE_URL}/shipments/4001234' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

GET {BASE_URL}/shipments/4001234/label

{
  "success": true,
  "data": {
    "tracking_number": "4001234",
    "label_url": "https://.../label.pdf",
    "combined_url": "https://.../combined.pdf"
  }
}

curl --request GET '{BASE_URL}/shipments/4001234/label' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

DELETE {BASE_URL}/shipments/4001234

{
  "success": true,
  "message": "Shipment cancelled successfully."
}

curl --request DELETE '{BASE_URL}/shipments/4001234' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

Account & Wallet

Returns the authenticated partner account profile, wallet summary, and API client details.

GET {BASE_URL}/account

{
  "success": true,
  "data": {
    "account": {
      "name": "My Company",
      "email": "partner@example.com",
      "phone": "+50760000000",
      "status": "active"
    },
    "wallet": {
      "balance": 195.01,
      "currency": "USD",
      "is_active": true
    },
    "api_client": {
      "name": "My Integration",
      "client_id": "clnt_abc123",
      "webhook_url": "https://myapp.com/webhooks",
      "last_used_at": "2026-06-12 10:00:00"
    }
  }
}

cURL Example

curl --request GET '{BASE_URL}/account' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

Wallet

Returns the current wallet balance, currency, and the last 20 transactions.

GET {BASE_URL}/wallet

{
  "success": true,
  "data": {
    "balance": 195.01,
    "currency": "USD",
    "is_active": true,
    "transactions": [
      {
        "type": "debit",
        "amount": 4.99,
        "balance": 195.01,
        "reason": "Shipment payment - 4001234",
        "reference": "SHIPMENT-4001234",
        "date": "2026-06-12 10:00:00"
      }
    ]
  }
}

cURL Example

curl --request GET '{BASE_URL}/wallet' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

Webhook

Webhook Configuration

Register a webhook URL for shipment event notifications. Verify inbound payloads by computing HMAC-SHA256(webhook_secret, raw_body) and comparing it with the X-Shippea-Signature header.

GET {BASE_URL}/webhook

{
  "success": true,
  "data": {
    "webhook_url": "https://myapp.com/webhooks",
    "webhook_secret": "shp_secret_abc..."
  }
}

{
  "webhook_url": "https://myapp.com/webhooks/shippea"
}

{
  "success": true,
  "message": "Webhook URL registered successfully.",
  "data": {
    "webhook_url": "https://myapp.com/webhooks/shippea",
    "webhook_secret": "shp_secret_abc..."
  }
}

DELETE {BASE_URL}/webhook

{
  "success": true,
  "message": "Webhook URL removed successfully."
}

Authentication

Revokes the current access token. Subsequent requests with this token return 401.

Only the token used for this request is revoked. Other active tokens for the same client are unaffected.

POST {BASE_URL}/auth/logout

{
  "success": true,
  "message": "Token revoked successfully."
}

cURL Example

curl --request POST '{BASE_URL}/auth/logout' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

Reference

Regions Reference

Panama region IDs and ISO codes to use with the region_id and origin_region_id query parameters on the /services endpoint, and the province_code fields in shipment creation. Use the /regions endpoint to retrieve live IDs.

Reference

Error Codes

All errors return success: false and a human-readable message. The HTTP status code indicates the error category.

Resources

Postman Collection

Download the Postman collection to get all v2 endpoints pre-configured with automated token-save test scripts.