API Documentation

Shipping API Documentation (v1.0)

Overview

Our API allows you to automate your entire shipping process with USPS through our platform. Connect your store, and we'll handle label creation, tracking, and manifesting in bulk. You focus on selling; we focus on shipping.

1. Authentication

To use our API, you need an API key. Get it from your account dashboard.

  • Header: Authorization: Bearer <your_api_key>
  • All requests must use HTTPS.

2. Endpoints & Core Methods

2.1. Create Shipments (Bulk)

This is the main method. Send us a batch of orders, and we'll return USPS labels and tracking numbers.

  • URL: POST https://api.yourcompany.com/v1/shipments/bulk
  • Content-Type: application/json

Request Body Example:

{
  "shipments": [
    {
      "internal_id": "order_12345",
      "service": "USPS_FCPS",
      "to_address": {
        "name": "Jane Doe",
        "street1": "123 Main St",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345",
        "country": "US"
      },
      "parcel": {
        "weight_oz": 12,
        "length_in": 10,
        "width_in": 5,
        "height_in": 3
      }
    }
  ]
}

Successful Response (200 OK):

{
  "results": [
    {
      "internal_id": "order_12345",
      "success": true,
      "tracking_number": "9405511899223456789012",
      "label_url": "https://api.yourcompany.com/labels/order_12345.pdf",
      "cost": 3.89
    }
  ]
}
2.2. Get Shipment Status

Pull tracking status for any shipment we've processed.

  • URL: GET https://api.yourcompany.com/v1/tracking/<tracking_number>
  • Response: Returns the latest USPS tracking events.

3. USPS Service Codes

Specify these in the service field. These are our supported services for your typical goods:

  • USPS_FCPS - First-Class Package Service: For packages under 16 oz. Best for apparel, small items.
  • USPS_PM - Priority Mail: For heavier packages (over 1 lb) or faster delivery. Best for larger bundles.
  • USPS_FCPS_INTERNATIONAL - First Class Package International: Your low-cost option for global shipping of small goods.

Why we use these: They offer the best rates for lightweight, high-volume parcels. This is how we save you 50%+ compared to standard carrier rates.

4. How It Works: The Flow

  1. You send us orders via the POST /bulk endpoint as soon as you're ready to fulfill.
  2. We talk to USPS. Our system validates addresses, buys postage, and gets tracking numbers using the official USPS API in large batches. This is how we get you commercial pricing.
  3. We send you back the labels and tracking numbers. You can automatically webhook them back to your store to update your customers.

5. Webhooks (Recommended)

Set up a webhook endpoint in your store. We will push tracking events to you in real-time as USPS provides them.

  • Event: tracking.updated
  • Payload: Includes the tracking number and full status (e.g., "ACCEPTED", "OUT FOR DELIVERY", "DELIVERED").

Why This Exists

This API is built for one reason: to give you the volume discount and automation of a giant corporation without the complexity. You can't get these USPS rates easily on your own at scale. We handle the USPS integration; you get a simple, powerful API.

Need Help?

Contact our integration team: integration@yourcompany.com