REST API

API Documentation

Integrate shipping labels into your application with our powerful REST API. Get real-time rates, create labels, and track shipments programmatically.

Authentication

All API requests require authentication using your API key and secret. Include these headers in every request:

headers

X-API-Key: your_api_key
X-API-Secret: your_api_secret

Security Notice

Keep your API secret secure. Never expose it in client-side code or public repositories.

Example Request

bash

curl -X GET https://uspostage.io/api/v1/account/balance \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Account Balance

Check your crypto wallet balances and transaction history. The API uses your crypto wallet (BTC, LTC, LTCT) for payments.

GET

/api/v1/account/balance

Get crypto wallet balances and transactions

Query Parameters

Parameter	Type	Required	Description
includeTransactions	`boolean`	Optional	Include transaction history
currency	`string`	Optional	Filter transactions by currency (BTC, LTC, LTCT)
limit	`number`	Optional	Number of transactions (default: 20, max: 100)

Example Request

bash

curl -X GET "https://uspostage.io/api/v1/account/balance?includeTransactions=true&limit=10" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response

json

{
  "success": true,
  "data": {
    "balances": [
      { "currency": "BTC", "balance": 0.00125000 },
      { "currency": "LTC", "balance": 0.50000000 },
      { "currency": "LTCT", "balance": 0.00000000 }
    ],
    "supportedCurrencies": ["BTC", "LTC", "LTCT"],
    "transactions": [
      {
        "id": "txn_abc123",
        "currency": "BTC",
        "type": "deposit",
        "amount": 0.00100000,
        "balanceAfter": 0.00125000,
        "description": "Deposit via CoinPayments",
        "createdAt": "2024-01-10T12:00:00Z"
      },
      {
        "id": "txn_def456",
        "currency": "BTC",
        "type": "label_purchase",
        "amount": -0.00015000,
        "balanceAfter": 0.00025000,
        "description": "API labels purchase for order USP-12345678",
        "createdAt": "2024-01-09T15:30:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 25,
      "hasMore": true
    }
  }
}

Add Funds

To add funds to your wallet, visit the My Wallet page and deposit using BTC, LTC, or LTCT (testnet).

Address Verification

Verify and standardize shipping addresses to ensure deliverability.

POST

/api/v1/shipping/verify-address

Verify and correct a shipping address

Request Body

Parameter	Type	Required	Description
address	`Address`	Required	Address to verify
strict	`boolean`	Optional	Enable strict verification mode

Example Request

bash

curl -X POST https://uspostage.io/api/v1/shipping/verify-address \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "address": {
      "name": "John Doe",
      "street1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    }
  }'

Response

json

{
  "success": true,
  "data": {
    "verified": true,
    "addressId": "adr_abc123",
    "verifiedAddress": {
      "name": "JOHN DOE",
      "street1": "123 MAIN ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip": "94102-1234",
      "country": "US"
    },
    "verification": {
      "success": true,
      "errors": []
    }
  }
}

Shipping Rates

Get real-time shipping rates from multiple carriers including USPS, UPS, FedEx, and DHL.

POST

/api/v1/shipping/rates

Calculate shipping rates for a package

Request Body

Parameter	Type	Required	Description
fromAddress	`Address`	Required	Sender address object
toAddress	`Address`	Required	Recipient address object
packageDetails	`Package`	Required	Package dimensions and weight
carriers	`string[]`	Optional	Filter by specific carriers (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	Optional	Required for international shipments

Address Object

Parameter	Type	Required	Description
name	`string`	Required	Full name
company	`string`	Optional	Company name
street1	`string`	Required	Street address line 1
street2	`string`	Optional	Street address line 2
city	`string`	Required	City
state	`string`	Required	State/province code
zip	`string`	Required	ZIP/postal code
country	`string`	Required	Country code (US, CA, etc.)
phone	`string`	Optional	Phone number
email	`string`	Optional	Email address

Package Object

Parameter	Type	Required	Description
length	`number`	Required	Length in inches
width	`number`	Required	Width in inches
height	`number`	Required	Height in inches
weight	`number`	Required	Weight in ounces

CustomsInfo Object

International Shipments

Required when shipping internationally (when fromAddress.country differs from toAddress.country).

Parameter	Type	Required	Description
contents_type	`string`	Required	Type of contents: documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	Optional	Required when contents_type is 'other'
customs_certify	`boolean`	Required	Must be true - certifies accuracy of declaration
customs_signer	`string`	Required	Name of person certifying the customs declaration
eel_pfc	`string`	Required	Export exemption code (use 'NOEEI 30.37(a)' for shipments under $2,500)
non_delivery_option	`string`	Required	What to do if undeliverable: 'return' or 'abandon'
restriction_type	`string`	Required	Restriction type: 'none', 'other', 'quarantine', or 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	Optional	Required when restriction_type is not 'none'
customs_items	`CustomsItem[]`	Required	Array of items being shipped (1-100 items)

CustomsItem Object

Parameter	Type	Required	Description
description	`string`	Required	Detailed description of the item
quantity	`number`	Required	Number of items (minimum: 1)
value	`number`	Required	Value in USD (must be greater than 0)
weight	`number`	Required	Weight in ounces (must be greater than 0)
origin_country	`string`	Required	2-letter country code (e.g., 'US', 'CN')
hs_tariff_number	`string`	Required	6-10 digit HS tariff code for the item

Example Request

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001",
      "country": "US"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    }
  }'

Response

json

{
  "success": true,
  "data": {
    "shipmentId": "shp_abc123",
    "rates": [
      {
        "id": "rate_xyz789",
        "carrier": "USPS",
        "service": "Priority Mail",
        "rate": 8.95,
        "currency": "USD",
        "delivery_days": 2,
        "delivery_date": "2024-01-15"
      },
      {
        "id": "rate_def456",
        "carrier": "UPS",
        "service": "Ground",
        "rate": 12.50,
        "currency": "USD",
        "delivery_days": 5,
        "delivery_date": "2024-01-18"
      }
    ]
  }
}

International Shipping Example

For international shipments, include the customsInfo object with item declarations:

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US",
      "phone": "4155551234"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Queen St W",
      "city": "Toronto",
      "state": "ON",
      "zip": "M5V 2A8",
      "country": "CA",
      "phone": "4165551234"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    },
    "customsInfo": {
      "contents_type": "merchandise",
      "customs_certify": true,
      "customs_signer": "John Doe",
      "eel_pfc": "NOEEI 30.37(a)",
      "non_delivery_option": "return",
      "restriction_type": "none",
      "customs_items": [
        {
          "description": "Cotton T-Shirt",
          "quantity": 2,
          "value": 25.00,
          "weight": 8,
          "origin_country": "US",
          "hs_tariff_number": "6109100010"
        }
      ]
    }
  }'

Create Order

Create and manage shipping orders. Orders contain one or more shipping label items.

GET

/api/v1/orders

List all orders

POST

/api/v1/orders

Create a new order

GET

/api/v1/orders/{id}

Get order details

List Orders - Query Parameters

Parameter	Type	Required	Description
limit	`number`	Optional	Number of results (default: 50, max: 100)
offset	`number`	Optional	Pagination offset

Create Order - Request Body

Parameter	Type	Required	Description
items	`OrderItem[]`	Required	Array of order items
email	`string`	Optional	Customer email
externalReference	`string`	Optional	Your reference ID

OrderItem Object

Simplified API

Only shipmentId and rateId are required. Addresses, package details, and customs info are automatically extracted from the shipment.

Parameter	Type	Required	Description
shipmentId	`string`	Required	Shipment ID from the rates endpoint
rateId	`string`	Required	Rate ID from the rates endpoint

Example: Create Order

bash

curl -X POST https://uspostage.io/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "items": [
      {
        "shipmentId": "shp_abc123",
        "rateId": "rate_xyz789"
      }
    ],
    "externalReference": "ORDER-12345"
  }'

Response

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "trackingId": "USP-12345678",
    "totalAmount": 8.95,
    "paymentStatus": "pending",
    "items": [
      {
        "orderItemId": "item_xyz789",
        "rateId": "rate_xyz789"
      }
    ]
  }
}

Purchase Labels

Purchase shipping labels for all items in an order. Labels are purchased using your crypto wallet balance (BTC, LTC, or LTCT).

POST

/api/v1/labels/purchase

Purchase shipping labels for an order

Request Body

Crypto Payment

The API will convert the USD label cost to crypto at current rates. You must have sufficient balance (including 10% buffer for price fluctuations).

Parameter	Type	Required	Description
orderId	`string`	Required	Order ID to purchase labels for
currency	`string`	Optional	Crypto currency to pay with (BTC, LTC, LTCT). If not specified, auto-selects the first currency with sufficient balance.

Example Request

bash

curl -X POST https://uspostage.io/api/v1/labels/purchase \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "orderId": "ord_abc123",
    "currency": "BTC"
  }'

Response

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "externalReference": "ORDER-12345",
    "totalLabels": 2,
    "successCount": 2,
    "failCount": 0,
    "labels": [
      {
        "orderItemId": "item_xyz789",
        "success": true,
        "trackingCode": "9400111899223456789012",
        "labelUrl": "https://easypost.com/labels/lbl_abc123.pdf",
        "carrier": "USPS",
        "service": "Priority Mail",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_abc123.pdf",
          "png": "https://easypost.com/labels/lbl_abc123.png"
        }
      },
      {
        "orderItemId": "item_def456",
        "success": true,
        "trackingCode": "9400111899223456789013",
        "labelUrl": "https://easypost.com/labels/lbl_def456.pdf",
        "carrier": "FedEx",
        "service": "Ground",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_def456.pdf"
        }
      }
    ]
  }
}

402 Insufficient Balance

If your wallet balance is too low, the API returns a 402 status with the required crypto amount.

Insufficient Balance Response

json

{
  "success": false,
  "error": "Insufficient balance",
  "message": "Need 0.00011000 BTC (includes 10% buffer), have 0.00005000",
  "currency": "BTC",
  "required": 0.00011000,
  "requiredUsd": 5.50,
  "available": 0.00005000,
  "balanceEndpoint": "/api/v1/account/balance"
}

Tracking

Track shipments using the tracking code from purchased labels.

GET

/api/v1/tracking/{code}

Get tracking information

Path Parameters

Parameter	Type	Required	Description
code	`string`	Required	Tracking code

Example Request

bash

curl -X GET https://uspostage.io/api/v1/tracking/9400111899223456789012 \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response

json

{
  "success": true,
  "data": {
    "trackingCode": "9400111899223456789012",
    "carrier": "USPS",
    "status": "in_transit",
    "statusDetail": "In Transit to Next Facility",
    "estDeliveryDate": "2024-01-15T00:00:00Z",
    "publicUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012",
    "trackingDetails": [
      {
        "status": "in_transit",
        "message": "In Transit to Next Facility",
        "datetime": "2024-01-12T14:30:00Z",
        "location": "San Francisco, CA"
      },
      {
        "status": "accepted",
        "message": "Accepted at USPS Origin Facility",
        "datetime": "2024-01-11T09:15:00Z",
        "location": "San Francisco, CA"
      }
    ],
    "updatedAt": "2024-01-12T14:30:00Z"
  }
}

Webhooks

Receive real-time notifications when events occur, such as label creation or tracking updates.

GET

/api/v1/webhooks

List registered webhooks

POST

/api/v1/webhooks

GET

/api/v1/webhooks/{id}

Get webhook details

DELETE

/api/v1/webhooks/{id}

Delete a webhook

Available Events

label.created

When a label is purchased successfully

label.failed

When label generation fails

Register Webhook - Request Body

Parameter	Type	Required	Description
webhookUrl	`string`	Required	URL to receive webhook events
events	`string[]`	Required	Array of event types to subscribe to

Example: Register Webhook

bash

curl -X POST https://uspostage.io/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"]
  }'

Response

json

{
  "success": true,
  "data": {
    "id": "whk_abc123",
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"],
    "secret": "whsec_abc123xyz789..."
  }
}

Webhook Signature Verification

Each webhook includes a signature header for verification. Verify the signature using HMAC-SHA256:

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Webhook Payload Example

json

{
  "event": "label.created",
  "timestamp": "2024-01-12T14:30:00Z",
  "data": {
    "orderId": "ord_abc123",
    "orderItemId": "item_xyz789",
    "externalReference": "ORDER-12345",
    "label": {
      "trackingCode": "9400111899223456789012",
      "carrier": "USPS",
      "service": "Priority Mail",
      "labelUrl": "https://uspostage.io/labels/lbl_abc123.pdf"
    }
  }
}

REST API

API Documentation

Integrate shipping labels into your application with our powerful REST API. Get real-time rates, create labels, and track shipments programmatically.

Authentication

All API requests require authentication using your API key and secret. Include these headers in every request:

headers

X-API-Key: your_api_key
X-API-Secret: your_api_secret

Security Notice

Keep your API secret secure. Never expose it in client-side code or public repositories.

Example Request

bash

curl -X GET https://uspostage.io/api/v1/account/balance \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Account Balance

Check your crypto wallet balances and transaction history. The API uses your crypto wallet (BTC, LTC, LTCT) for payments.

GET

/api/v1/account/balance

Get crypto wallet balances and transactions

Query Parameters

Parameter	Type	Required	Description
includeTransactions	`boolean`	Optional	Include transaction history
currency	`string`	Optional	Filter transactions by currency (BTC, LTC, LTCT)
limit	`number`	Optional	Number of transactions (default: 20, max: 100)

Example Request

bash

curl -X GET "https://uspostage.io/api/v1/account/balance?includeTransactions=true&limit=10" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response

json

{
  "success": true,
  "data": {
    "balances": [
      { "currency": "BTC", "balance": 0.00125000 },
      { "currency": "LTC", "balance": 0.50000000 },
      { "currency": "LTCT", "balance": 0.00000000 }
    ],
    "supportedCurrencies": ["BTC", "LTC", "LTCT"],
    "transactions": [
      {
        "id": "txn_abc123",
        "currency": "BTC",
        "type": "deposit",
        "amount": 0.00100000,
        "balanceAfter": 0.00125000,
        "description": "Deposit via CoinPayments",
        "createdAt": "2024-01-10T12:00:00Z"
      },
      {
        "id": "txn_def456",
        "currency": "BTC",
        "type": "label_purchase",
        "amount": -0.00015000,
        "balanceAfter": 0.00025000,
        "description": "API labels purchase for order USP-12345678",
        "createdAt": "2024-01-09T15:30:00Z"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "total": 25,
      "hasMore": true
    }
  }
}

Add Funds

To add funds to your wallet, visit the My Wallet page and deposit using BTC, LTC, or LTCT (testnet).

Address Verification

Verify and standardize shipping addresses to ensure deliverability.

POST

/api/v1/shipping/verify-address

Verify and correct a shipping address

Request Body

Parameter	Type	Required	Description
address	`Address`	Required	Address to verify
strict	`boolean`	Optional	Enable strict verification mode

Example Request

bash

curl -X POST https://uspostage.io/api/v1/shipping/verify-address \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "address": {
      "name": "John Doe",
      "street1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    }
  }'

Response

json

{
  "success": true,
  "data": {
    "verified": true,
    "addressId": "adr_abc123",
    "verifiedAddress": {
      "name": "JOHN DOE",
      "street1": "123 MAIN ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip": "94102-1234",
      "country": "US"
    },
    "verification": {
      "success": true,
      "errors": []
    }
  }
}

Shipping Rates

Get real-time shipping rates from multiple carriers including USPS, UPS, FedEx, and DHL.

POST

/api/v1/shipping/rates

Calculate shipping rates for a package

Request Body

Parameter	Type	Required	Description
fromAddress	`Address`	Required	Sender address object
toAddress	`Address`	Required	Recipient address object
packageDetails	`Package`	Required	Package dimensions and weight
carriers	`string[]`	Optional	Filter by specific carriers (USPS, UPS, FEDEX, DHL)
customsInfo	`CustomsInfo`	Optional	Required for international shipments

Address Object

Parameter	Type	Required	Description
name	`string`	Required	Full name
company	`string`	Optional	Company name
street1	`string`	Required	Street address line 1
street2	`string`	Optional	Street address line 2
city	`string`	Required	City
state	`string`	Required	State/province code
zip	`string`	Required	ZIP/postal code
country	`string`	Required	Country code (US, CA, etc.)
phone	`string`	Optional	Phone number
email	`string`	Optional	Email address

Package Object

Parameter	Type	Required	Description
length	`number`	Required	Length in inches
width	`number`	Required	Width in inches
height	`number`	Required	Height in inches
weight	`number`	Required	Weight in ounces

CustomsInfo Object

International Shipments

Required when shipping internationally (when fromAddress.country differs from toAddress.country).

Parameter	Type	Required	Description
contents_type	`string`	Required	Type of contents: documents, gift, merchandise, returned_goods, sample, dangerous_goods, humanitarian_donation, other
contents_explanation	`string`	Optional	Required when contents_type is 'other'
customs_certify	`boolean`	Required	Must be true - certifies accuracy of declaration
customs_signer	`string`	Required	Name of person certifying the customs declaration
eel_pfc	`string`	Required	Export exemption code (use 'NOEEI 30.37(a)' for shipments under $2,500)
non_delivery_option	`string`	Required	What to do if undeliverable: 'return' or 'abandon'
restriction_type	`string`	Required	Restriction type: 'none', 'other', 'quarantine', or 'sanitary_phytosanitary_inspection'
restriction_comments	`string`	Optional	Required when restriction_type is not 'none'
customs_items	`CustomsItem[]`	Required	Array of items being shipped (1-100 items)

CustomsItem Object

Parameter	Type	Required	Description
description	`string`	Required	Detailed description of the item
quantity	`number`	Required	Number of items (minimum: 1)
value	`number`	Required	Value in USD (must be greater than 0)
weight	`number`	Required	Weight in ounces (must be greater than 0)
origin_country	`string`	Required	2-letter country code (e.g., 'US', 'CN')
hs_tariff_number	`string`	Required	6-10 digit HS tariff code for the item

Example Request

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001",
      "country": "US"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    }
  }'

Response

json

{
  "success": true,
  "data": {
    "shipmentId": "shp_abc123",
    "rates": [
      {
        "id": "rate_xyz789",
        "carrier": "USPS",
        "service": "Priority Mail",
        "rate": 8.95,
        "currency": "USD",
        "delivery_days": 2,
        "delivery_date": "2024-01-15"
      },
      {
        "id": "rate_def456",
        "carrier": "UPS",
        "service": "Ground",
        "rate": 12.50,
        "currency": "USD",
        "delivery_days": 5,
        "delivery_date": "2024-01-18"
      }
    ]
  }
}

International Shipping Example

For international shipments, include the customsInfo object with item declarations:

bash

curl -X POST https://uspostage.io/api/v1/shipping/rates \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "fromAddress": {
      "name": "John Doe",
      "street1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94102",
      "country": "US",
      "phone": "4155551234"
    },
    "toAddress": {
      "name": "Jane Smith",
      "street1": "456 Queen St W",
      "city": "Toronto",
      "state": "ON",
      "zip": "M5V 2A8",
      "country": "CA",
      "phone": "4165551234"
    },
    "packageDetails": {
      "length": 10,
      "width": 8,
      "height": 4,
      "weight": 16
    },
    "customsInfo": {
      "contents_type": "merchandise",
      "customs_certify": true,
      "customs_signer": "John Doe",
      "eel_pfc": "NOEEI 30.37(a)",
      "non_delivery_option": "return",
      "restriction_type": "none",
      "customs_items": [
        {
          "description": "Cotton T-Shirt",
          "quantity": 2,
          "value": 25.00,
          "weight": 8,
          "origin_country": "US",
          "hs_tariff_number": "6109100010"
        }
      ]
    }
  }'

Create Order

Create and manage shipping orders. Orders contain one or more shipping label items.

GET

/api/v1/orders

List all orders

POST

/api/v1/orders

Create a new order

GET

/api/v1/orders/{id}

Get order details

List Orders - Query Parameters

Parameter	Type	Required	Description
limit	`number`	Optional	Number of results (default: 50, max: 100)
offset	`number`	Optional	Pagination offset

Create Order - Request Body

Parameter	Type	Required	Description
items	`OrderItem[]`	Required	Array of order items
email	`string`	Optional	Customer email
externalReference	`string`	Optional	Your reference ID

OrderItem Object

Simplified API

Only shipmentId and rateId are required. Addresses, package details, and customs info are automatically extracted from the shipment.

Parameter	Type	Required	Description
shipmentId	`string`	Required	Shipment ID from the rates endpoint
rateId	`string`	Required	Rate ID from the rates endpoint

Example: Create Order

bash

curl -X POST https://uspostage.io/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "items": [
      {
        "shipmentId": "shp_abc123",
        "rateId": "rate_xyz789"
      }
    ],
    "externalReference": "ORDER-12345"
  }'

Response

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "trackingId": "USP-12345678",
    "totalAmount": 8.95,
    "paymentStatus": "pending",
    "items": [
      {
        "orderItemId": "item_xyz789",
        "rateId": "rate_xyz789"
      }
    ]
  }
}

Purchase Labels

Purchase shipping labels for all items in an order. Labels are purchased using your crypto wallet balance (BTC, LTC, or LTCT).

POST

/api/v1/labels/purchase

Purchase shipping labels for an order

Request Body

Crypto Payment

The API will convert the USD label cost to crypto at current rates. You must have sufficient balance (including 10% buffer for price fluctuations).

Parameter	Type	Required	Description
orderId	`string`	Required	Order ID to purchase labels for
currency	`string`	Optional	Crypto currency to pay with (BTC, LTC, LTCT). If not specified, auto-selects the first currency with sufficient balance.

Example Request

bash

curl -X POST https://uspostage.io/api/v1/labels/purchase \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "orderId": "ord_abc123",
    "currency": "BTC"
  }'

Response

json

{
  "success": true,
  "data": {
    "orderId": "ord_abc123",
    "externalReference": "ORDER-12345",
    "totalLabels": 2,
    "successCount": 2,
    "failCount": 0,
    "labels": [
      {
        "orderItemId": "item_xyz789",
        "success": true,
        "trackingCode": "9400111899223456789012",
        "labelUrl": "https://easypost.com/labels/lbl_abc123.pdf",
        "carrier": "USPS",
        "service": "Priority Mail",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_abc123.pdf",
          "png": "https://easypost.com/labels/lbl_abc123.png"
        }
      },
      {
        "orderItemId": "item_def456",
        "success": true,
        "trackingCode": "9400111899223456789013",
        "labelUrl": "https://easypost.com/labels/lbl_def456.pdf",
        "carrier": "FedEx",
        "service": "Ground",
        "labelFormats": {
          "pdf": "https://easypost.com/labels/lbl_def456.pdf"
        }
      }
    ]
  }
}

402 Insufficient Balance

If your wallet balance is too low, the API returns a 402 status with the required crypto amount.

Insufficient Balance Response

json

{
  "success": false,
  "error": "Insufficient balance",
  "message": "Need 0.00011000 BTC (includes 10% buffer), have 0.00005000",
  "currency": "BTC",
  "required": 0.00011000,
  "requiredUsd": 5.50,
  "available": 0.00005000,
  "balanceEndpoint": "/api/v1/account/balance"
}

Tracking

Track shipments using the tracking code from purchased labels.

GET

/api/v1/tracking/{code}

Get tracking information

Path Parameters

Parameter	Type	Required	Description
code	`string`	Required	Tracking code

Example Request

bash

curl -X GET https://uspostage.io/api/v1/tracking/9400111899223456789012 \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret"

Response

json

{
  "success": true,
  "data": {
    "trackingCode": "9400111899223456789012",
    "carrier": "USPS",
    "status": "in_transit",
    "statusDetail": "In Transit to Next Facility",
    "estDeliveryDate": "2024-01-15T00:00:00Z",
    "publicUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012",
    "trackingDetails": [
      {
        "status": "in_transit",
        "message": "In Transit to Next Facility",
        "datetime": "2024-01-12T14:30:00Z",
        "location": "San Francisco, CA"
      },
      {
        "status": "accepted",
        "message": "Accepted at USPS Origin Facility",
        "datetime": "2024-01-11T09:15:00Z",
        "location": "San Francisco, CA"
      }
    ],
    "updatedAt": "2024-01-12T14:30:00Z"
  }
}

Webhooks

Receive real-time notifications when events occur, such as label creation or tracking updates.

GET

/api/v1/webhooks

List registered webhooks

POST

/api/v1/webhooks

GET

/api/v1/webhooks/{id}

Get webhook details

DELETE

/api/v1/webhooks/{id}

Delete a webhook

Available Events

label.created

When a label is purchased successfully

label.failed

When label generation fails

Register Webhook - Request Body

Parameter	Type	Required	Description
webhookUrl	`string`	Required	URL to receive webhook events
events	`string[]`	Required	Array of event types to subscribe to

Example: Register Webhook

bash

curl -X POST https://uspostage.io/api/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -H "X-API-Secret: your_api_secret" \
  -d '{
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"]
  }'

Response

json

{
  "success": true,
  "data": {
    "id": "whk_abc123",
    "webhookUrl": "https://yoursite.com/webhooks/uspostage",
    "events": ["label.created", "label.failed"],
    "secret": "whsec_abc123xyz789..."
  }
}

Webhook Signature Verification

Each webhook includes a signature header for verification. Verify the signature using HMAC-SHA256:

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Webhook Payload Example

json

{
  "event": "label.created",
  "timestamp": "2024-01-12T14:30:00Z",
  "data": {
    "orderId": "ord_abc123",
    "orderItemId": "item_xyz789",
    "externalReference": "ORDER-12345",
    "label": {
      "trackingCode": "9400111899223456789012",
      "carrier": "USPS",
      "service": "Priority Mail",
      "labelUrl": "https://uspostage.io/labels/lbl_abc123.pdf"
    }
  }
}

API Documentation

Authentication

Example Request

Account Balance

Query Parameters

Example Request

Response

Address Verification

Request Body

Example Request

Response

Shipping Rates

Request Body

Address Object

Package Object

CustomsInfo Object

CustomsItem Object

Example Request

Response

International Shipping Example

Create Order

List Orders - Query Parameters

Create Order - Request Body

OrderItem Object

Example: Create Order

Response

Purchase Labels

Request Body

Example Request

Response

Insufficient Balance Response

Tracking

Path Parameters

Example Request

Response

Webhooks

Available Events

Register Webhook - Request Body

Example: Register Webhook

Response

Webhook Signature Verification

Webhook Payload Example

Shopping Cart

Your cart is empty

API Documentation

Authentication

Example Request

Account Balance

Query Parameters

Example Request

Response

Address Verification

Request Body

Example Request

Response

Shipping Rates

Request Body

Address Object

Package Object

CustomsInfo Object

CustomsItem Object

Example Request

Response

International Shipping Example

Create Order

List Orders - Query Parameters

Create Order - Request Body

OrderItem Object

Example: Create Order

Response

Purchase Labels

Request Body

Example Request

Response

Insufficient Balance Response

Tracking

Path Parameters

Example Request

Response

Webhooks