Developers

Overview

The REST API lets third-party systems create shipments, get rate quotes, track packages, download labels, and schedule pickups. Authentication is token-based. Every endpoint returns JSON.

• Base URL: https://api.livecourier.com/v1
• Auth: Bearer token + X-Tenant header
• Format: JSON request and response bodies
• Rate limit: 60 requests/minute per API user (configurable)
• Tokens: Do not expire - they remain valid until revoked (Stripe/Twilio pattern)

Documentation

Quick Start

Every request needs two headers: Authorization: Bearer <token> (identifies the API user) and X-Tenant: CLIENT_ID (identifies which tenant's data to access). Both are issued from Settings → API / Web Services inside the admin panel.

1. Get a rate quote

curl -X POST https://api.livecourier.com/v1/rates/quote \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant: CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "service_code": "DOM_NEXT_DAY",
    "sender":    { "country": "US", "zip": "10001" },
    "recipient": { "country": "US", "zip": "90210" },
    "package":   { "weight": 5, "weight_unit": "lb" }
  }'

2. Create a shipment

curl -X POST https://api.livecourier.com/v1/shipments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant: CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "service_code": "DOM_NEXT_DAY",
    "sender": {
      "company": "Acme Corp",
      "country": "US", "city": "New York", "zip": "10001",
      "address1": "123 Main St"
    },
    "recipient": {
      "company": "Beta Inc",
      "country": "US", "city": "Beverly Hills", "zip": "90210",
      "address1": "456 Oak Ave"
    },
    "package": { "weight": 5, "weight_unit": "lb" },
    "reference": "PO-12345"
  }'

Response includes the generated AWB (tracking number), status, and - if the service uses a carrier API - the carrier submission result.

3. Track a shipment

curl https://api.livecourier.com/v1/shipments/ABC123/track \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant: CLIENT_ID"

4. Download the label

curl https://api.livecourier.com/v1/shipments/ABC123/label \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant: CLIENT_ID"

Returns the shipping label as a base64-encoded PDF. Decode and save it, or send it directly to a thermal printer.

Response Format

All responses follow a consistent envelope:

{
  "ok": true,
  "data": { ... }
}

Errors use the same shape:

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed.",
    "details": { "package.weight": "Weight must be greater than 0." }
  }
}

Always check ok first. See Errors & Rate Limits for the full list of error codes.