Shippea Partner API Documentation
Shippea
Shippea Partner API

Developer Documentation

A premium, production-ready partner API for authentication, pricing discovery, shipment creation, tracking and cancellations — designed for fast integration and clear debugging.

Overview

This API allows any third-party application to authenticate, fetch regions/services with prices, create customer accounts, create shipments from detailed sender/receiver/items data, read tracking details, and cancel shipments when status allows.

Authentication

Bearer token (client credentials flow).

Content Type

application/json

Timezone

Server default timezone

Version

v2/partner

POST

/auth/token

Exchange client_id and client_secret for an access token. Use this token in all protected endpoints.

Public endpoint • No bearer token required

Request Body

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

Success Response (200)

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

cURL Example

curl --request POST '{{ url('/api/v2/partner/auth/token') }}' \
    --header 'Content-Type: application/json' \
    --data '{
        "client_id": "your_client_id",
        "client_secret": "your_client_secret"
    }'
GET

/regions

Returns all active regions available for service coverage.

Requires header: Authorization: Bearer <token>

Request

GET {{ url('/api/v2/partner/regions') }}

Success Response (200)

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

cURL Example

curl --request GET '{{ url('/api/v2/partner/regions') }}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'
GET

/services

Returns available services and prices by region. Add weight to filter by weight range.

Required query: region_id • Optional query: weight

Request

GET {{ url('/api/v2/partner/services') }}?region_id=1&weight=2.5

Success Response (200)

{
  "success": true,
  "data": [
    {
      "id": 12,
      "region_id": 1,
      "rate_name": "Door-to-Door",
      "rate_type": "Door-to-Door",
      "min_weight": "0.00",
      "max_weight": "5.00",
      "price": "4.99",
      "return_charge": "0.00",
      "weight_unit": "lb"
    }
  ]
}

cURL Example

curl --request GET '{{ url('/api/v2/partner/services') }}?region_id=1&weight=2.5' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'
POST

/customers

Creates a customer account for shipment ownership. If email already exists, returns existing customer info.

Request Body

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

Success Response (201)

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

cURL Example

curl --request POST '{{ url('/api/v2/partner/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"
    }'
POST

/shipments

Creates a shipment from items_information, sender_details, and receiver_details.

Required: sender_details, receiver_details, items_information, and either service_id or service_name.

Request Body

{
  
  "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
        },
        {
            "title": "T-Shirt",
            "sku": "TS-202",
            "quantity": 2,
            "weight": 0.5,
            "length": 10,
            "width": 6,
            "height": 2,
            "package_type": "Bag",
            "declared_value": 10
        }
    ]
}
  ]
}

Success Response (201)

{
  "success": true,
  "message": "Shipment created successfully.",
  "data": {
    "shipment_id": 991,
    "tracking_number": "4001234",
    "status": "pending_payment",
    "total_price": 4.99,
    "currency": "USD"
  }
}

cURL Example

curl --request POST '{{ url('/api/v2/partner/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"},
        "receiver_details": {"address":"Street 123","city":"Panamá","country":"Panama","province_code":"PA-8"},
        "items_information": [{"title":"Shoes","quantity":1,"weight":1.2}]
    }'
GET

/shipments/{trackingNumber}

Fetch shipment status and details using tracking number.

Request

GET {{ url('/api/v2/partner/shipments/4001234') }}

Success Response (200)

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

cURL Example

curl --request GET '{{ url('/api/v2/partner/shipments/4001234') }}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'
DELETE

/shipments/{trackingNumber}

Cancels a shipment when the current status allows cancellation according to business rules.

Request

DELETE {{ url('/api/v2/partner/shipments/4001234') }}

Success Response (200)

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

cURL Example

curl --request DELETE '{{ url('/api/v2/partner/shipments/4001234') }}' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json'

Error Response Format

All validation and processing failures return JSON with success: false and a human-readable message.

Example Error (401)

{
  "success": false,
  "message": "Invalid client credentials."
}

Common Status Codes

  • 200 Success
  • 201 Resource created
  • 401 Unauthorized credentials/token
  • 403 Invalid token scope
  • 404 Resource not found
  • 422 Validation failed
  • 500 Internal server error