Pigee Shipping Partner API

Quickstart

From account creation to your first live shipment in under an hour. Follow these five steps:

1. Create a free Pigee account at account.pigeepost.com and select Shipping Partner as your account type.
2. Go to Dashboard → Developer → API Keys and generate a live key and a test key.
3. Choose your payment mode: Pigee Pay or Pigee Account Balance.
4. Configure your service fee in Dashboard → Fees.
5. Import the Postman collection for staging development.

Authentication

Every request must include your API key in the Authorization header as a Bearer token. Keys are scoped to your partner account and carry your fee configuration and payment mode.

Authorization: Bearer pgk_live_YOUR_API_KEY_HERE

Key types

Environments & Base URLs

The sandbox is a full 1:1 mirror of production. Switch environments by swapping your key prefix, or use the explicit sandbox URL for clarity.

SDKs & Libraries

Official SDKs wrap the REST API with typed models, automatic retries and sandbox helpers.

Validate API Key

Call this endpoint to confirm your API key is active and correctly configured before going live.

POST /api/v1/store/valid
Authorization: Bearer pgk_live_…
Content-Type: application/json

{
  "store_type": 2,
  "api_key": "pgk_live_YOUR_KEY"
}

{
  "valid": true,
  "account": {
    "id": "acc_7H4K",
    "type": "shipping_partner",
    "payment_mode": "pigee_pay",
    "service_fee_pct": 8.5,
    "balance_gbp": 240.00
  }
}

Get Shipping Rates

Fetch live carrier rates for a shipment. Returns all available services sorted by price, including transit time, insured value support and landed cost.

{
  "shop_url": "https://your-store.com",
  "currency": "GBP",
  "parcel": {
    "type": "Box",
    "boxsize": 4
  },
  "weight": { "value": 4, "units": "kg" },
  "dimension": {
    "length": 40,
    "width": 30,
    "height": 20,
    "units": "cms"
  },
  "address": {
    "pickup": {
      "address_line1": "10 High Street",
      "town": "London",
      "post_code": "SW1A 1AA",
      "country": "United Kingdom"
    },
    "destination": {
      "address_line1": "123 Ocean Drive",
      "town": "Miami",
      "post_code": "33101",
      "country": "United States"
    }
  }
}

{
  "rates": [
    {
      "carrier_request_id": "cr_abc123",
      "carrier_id": "dhl",
      "pigee_carrier_id": "DHL_EXPRESS_WORLDWIDE",
      "method_title": "DHL Express Worldwide",
      "price": 125.50,
      "currency": "GBP",
      "transit_days": 2,
      "insurance_available": true,
      "customs_included": true
    }
  ],
  "currency": "GBP",
  "request_id": "req_7H4K2026"
}

Request parameters

Create Order

Create a Pigee order using a carrier_request_id from the rates endpoint. Pigee generates the label, commercial invoice and, if using Pigee Pay, a hosted payment link.

{
  "order_from": "api",
  "shop_url": "https://your-store.com",
  "order_id": "ORDER-10001",
  "currency": "GBP",
  "items": [
    {
      "name": "Vintage leather jacket",
      "quantity": 1,
      "value": 600.00,
      "currency": "GBP",
      "hs_code": "4203100090"
    }
  ],
  "shippingData": {
    "method_title": "DHL Express Worldwide",
    "cost": 125.50,
    "currency": "GBP",
    "meta_data": {
      "carrier_request_id": "cr_abc123",
      "carrier_id": "dhl",
      "pigee_carrier_id": "DHL_EXPRESS_WORLDWIDE"
    }
  }
}

{
  "order_id": "po_78910",
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "status": "pending_payment",
  "payment_url": "https://pay.pigee.com/c/abc123",
  "label_url": null,
  "tracking_number": null
}

Fulfil Order

Send final fulfilment details once payment is confirmed. Pigee generates the shipping label, books the carrier and returns a tracking number.

{
  "order_id": "po_78910",
  "status": "processing",
  "shop_id": "https://your-store.com",
  "currency": "GBP",
  "total": 725.50,
  "shipping_total": 125.50
}

{
  "order_id": "po_78910",
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "status": "booked",
  "label_url": "https://labels.pigeepost.com/PGE-7H4K-2026-0042.pdf",
  "tracking_number": "1234567890",
  "carrier": "DHL",
  "estimated_delivery": "2026-05-08"
}

Tracking

Retrieve live tracking events for any shipment created via the API.

{
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "tracking_number": "1234567890",
  "carrier": "DHL",
  "status": "in_transit",
  "estimated_delivery": "2026-05-08",
  "events": [
    {
      "timestamp": "2026-05-06T08:14:00Z",
      "status": "in_transit",
      "location": "DHL Hub, Leipzig",
      "description": "Shipment in transit"
    }
  ]
}

Payment Modes

Pigee supports two payment modes. The active mode is set in your partner dashboard and applies to all orders.

Service Fees

As a Shipping Partner you can add your own fee on top of Pigee’s base carrier rates. Fees are configured in your dashboard and applied automatically before rates are returned.

• Percentage fee: Applied as a percentage of the base carrier cost.
• Fixed fee: A flat amount added per shipment.
• Per-lane overrides: Override the global fee for specific origin/destination pairs.

Settlements & FX

Pigee Pay collects from end-customers in 135+ currencies and settles to your bank account in your local currency.

• Settlement cycle is typically T+2 business days after shipment delivery confirmation.
• Withdraw from your Pigee balance via the dashboard.
• Detailed transaction logs are available under Finance → Settlements.
• Invoices for settled transactions are auto-generated and available as PDF.

Webhooks

Pigee pushes real-time events to your HTTPS endpoint as JSON POST requests. Configure your webhook URL in Dashboard → Developer → Webhooks.

{
  "event": "parcel.delivered",
  "created_at": "2026-05-08T14:22:07Z",
  "api_version": "v1",
  "data": {
    "pigee_order_id": "PGE-7H4K-2026-0042",
    "order_id": "ORDER-10001",
    "carrier": "DHL",
    "tracking_number": "1234567890",
    "delivered_at": "2026-05-08T14:18:00Z"
  }
}

Webhook Event Reference

Webhook Signatures

Every webhook request includes a X-Pigee-Signature header, an HMAC-SHA256 digest of the raw request body. Always verify this before processing.

// Node.js
const crypto = require('crypto');

function verifyPigeeWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

Errors

All errors return JSON with an error object containing a machine-readable code and a human-readable message.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your Pigee partner balance is not sufficient to create this shipment.",
    "request_id": "req_7H4K2026"
  }
}

Rate Limits

Rate limits are applied per API key and scale with your account tier.

When a rate limit is hit, the API returns HTTP 429 with a Retry-After header.

Data Types & Conventions

• Dates & times - ISO 8601 UTC, e.g. 2026-05-06T14:22:07Z
• Currencies - ISO 4217 three-letter codes, e.g. GBP, USD, NGN
• Monetary values - number with two decimal places, always paired with a currency field
• Country names - English full names, e.g. "United Kingdom", "United States"
• Phone numbers - E.164 format recommended, e.g. +447700900123
• Weights - kg or lbs specified per request
• IDs - Pigee-generated IDs use prefix format, e.g. po_78910, cr_abc123

Carrier IDs Reference

Use pigee_carrier_id values from the rates response when creating orders.

Changelog

v1.3 - May 2026

• Added insurance_available and customs_included flags to rates response.
• Webhook signature verification now uses HMAC-SHA256.
• New error code RATE_EXPIRED.
• Tracking endpoint added: GET /api/v1/tracking/{pigee_order_id}.

v1.2 - February 2026

• Added per-lane service fee overrides in dashboard.
• Pigee Pay payment links now include an expires_at field.
• New webhook events added for customs and settlements.

v1.1 - October 2025

• Initial Postman collection published.
• Sandbox environment launched.
• Account Balance payment mode released.

v1.0 - June 2025

• Initial public release: Validate, Get Rates, Create Order, Fulfil Order.