PackageSave API

The PackageSave API uses JWT tokens for authentication. You can obtain your API token from your team's account settings page.

Using your API token

Include your token in the Authorization header on every request:

Authorization Header

Authorization: Bearer YOUR_API_TOKEN

Buy your first label in five steps. Each step links to the full endpoint reference below.

1. Get your API token

Copy it from your account settings page and send it on every request in the Authorization header.

2. Create an order

Post the recipient + packages to POST /api/v1/orders. Rate fetching starts automatically in the background. Save the returned id (the order number).

3. Poll for rates

Poll GET /api/v1/orders/:id/shipping_rates every few seconds until status is "ready". A "failed" status tells you why no rates could be fetched.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://www.packagesave.com/api/v1/orders/PS-8JBH6B/shipping_rates"

4. Purchase a label

Pick a rate id and post it to POST /api/v1/orders/:id/purchase. A 402 means the purchase couldn't be paid for: branch on its code field.

curl -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"shipping_rate_id": 789}' \
  "https://www.packagesave.com/api/v1/orders/PS-8JBH6B/purchase"

5. Download the label

Poll GET /api/v1/orders/:id until label_available is true, then fetch the PDF from GET /api/v1/orders/:id/label.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://www.packagesave.com/api/v1/orders/PS-8JBH6B/label" -o label.pdf

Next steps

• List and track your shipments: filter by platform, delivery status, or purchase window.
• Reconcile shipments with your weekly statements: tie every charged dollar back to an order.
• Ship internationally: attach customs data at order creation.

An AI assistant such as Claude can turn a spreadsheet of customers and packages into draft shipments on PackageSave and report the UPS cost for each customer, without ever being able to buy a label.

The skill runs in Claude Code on your own computer, where the token stays in your terminal. The hosted chat in the Claude apps is not supported, because it cannot see that token.

Three steps

1. Generate the draft-only token on your account settings page.
2. Download and install the skill in Claude Code.
3. Give the assistant your spreadsheet and your packing rules.

1. Generate the draft-only token

On your account settings page, click Generate under Draft-only token for AI assistants. Copy the token right away: it is shown once and is valid for 30 days.

Never give an assistant your full API token. To stop every draft-only token at once, click Revoke draft-only tokens on the same page; your main API token keeps working.

2. Download and install the skill

Two files, SKILL.md and scripts/quote_drafts.py, already pointed at https://www.packagesave.com. No token inside.

Install

Unzip it into ~/.claude/skills/, so the folder is ~/.claude/skills/shipping-quotes/. Then paste these lines into a terminal and press Enter. On macOS and Linux the terminal waits without a prompt; on Windows it asks for the token. Paste the token (it is hidden as you type), press Enter, and Claude Code starts in that same terminal. The script reads the token from this environment variable, never from the command line or the chat.

read -rs API_DRAFT_TOKEN && export API_DRAFT_TOKEN
claude

$env:API_DRAFT_TOKEN = Read-Host -MaskInput "Draft token"
claude

3. Give the assistant your spreadsheet

Give it your spreadsheet and your packing rules; it first checks that GET /api/v1/current reports "token_scope": "drafts" (a full token reports null), the same check you can run yourself:

curl -H "Authorization: Bearer YOUR_DRAFT_TOKEN" \
     "https://www.packagesave.com/api/v1/current"

Afterwards: clean up the drafts

Open the Draft filter on your dashboard, select the drafts you no longer need and choose Delete (up to 200 at a time).

Buying a label (POST /api/v1/orders/:id/purchase) needs a card on file, unless your team is invoiced manually or is on a funds balance. Teams are billed in one of three ways:

• Weekly billing (default): labels are charged to your card on your weekly statement. No balance is required up front, and a card must be on file.
• Funds balance: your team must hold enough account credit to cover a label's estimated total (including tax) before purchase. Add funds on the Payments page in the web app.
• Manual billing: arranged with us directly. Labels still appear on a statement, and no card is required, so a purchase never returns payment_method_required.

Read your team's mode and balance from GET /api/v1/current:

When a balance-funded team has insufficient balance, the purchase endpoint returns 402 Payment Required with a machine-readable code and the exact shortfall, so you can top up the right amount. See the purchase endpoint error responses.

To reconcile what was billed against your shipments, see Shipments & invoices.

An international order (ship-from and ship-to in different countries) needs customs data before a label can be purchased. The commercial invoice is generated automatically from this data at label creation. The flow is the same as a domestic order, with customs attached up front:

• 1. Create with customs: POST /api/v1/orders accepts a top-level customs_line_items array plus the order-level fields below. Customs can't be edited via the API after creation, so send it complete.
• 2. Poll rates: GET /api/v1/orders/:id/shipping_rates, exactly as for domestic orders.
• 3. Purchase: POST /api/v1/orders/:id/purchase validates customs synchronously (see the pre-flight checks below) before creating the label.

Customs line items

One entry per distinct product in the shipment. Each line item takes:

A maximum of 100 line items per order, and a maximum of 50 packages (both are refused with a 422 rather than truncated). Total declared customs value (sum of unit_value × quantity) is capped at $50,000 per international shipment: a higher total is rejected with 422 at create and at purchase.

Order-level customs fields

All optional: sensible defaults apply when omitted:

Recipient tax ID

Some destinations ask for the recipient's tax ID on the customs entry (for example, a US EIN/SSN/ITIN on US-bound formal entries, or South Korea's PCCC on personal imports). Pass it on the order's shipping_address: tax_id (max 17 characters; values longer than 15 print on the commercial invoice but are not sent in UPS's structured tax field) plus an optional tax_id_type qualifier. When the type is omitted, a country-appropriate default is inferred. It prints on the commercial invoice. A recipient that holds two identifiers (an EU business with both an EORI and a VAT number) also takes secondary_tax_id plus a required secondary_tax_id_type (a different type from the main one); both IDs print on the commercial invoice.

Purchase pre-flight checks

POST /api/v1/orders/:id/purchase validates international orders synchronously and returns 422 with a machine-readable code instead of failing in the background:

Each returns a 422 body you can branch on:

{
  "error": "Customs information is incomplete. Each customs line item needs a specific description (not a generic term like 'clothing' or 'merchandise'), a valid HS code, country of origin, unit value, and quantity. Update the order with complete customs_line_items before purchasing.",
  "code": "customs_info_incomplete"
}

Example: Canada→US order with customs

curl -X POST https://www.packagesave.com/api/v1/orders \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com" },
    "shipping_address": {
      "line1": "350 5th Ave", "city": "New York", "state": "NY",
      "postal_code": "10118", "country": "US",
      "email": "jane@example.com", "phone": "+1 212 555 0100"
    },
    "packages": [{ "weight": 1.2, "length": 30, "width": 20, "height": 10, "value": 120 }],
    "customs_line_items": [
      {
        "customs_description": "Cotton t-shirt",
        "harmonized_code": "6109.10",
        "country_of_origin": "CA",
        "unit_value": 30.00,
        "quantity": 4,
        "merchant_product_id": "TSHIRT-BLK-M"
      }
    ],
    "reason_for_export": "SALE",
    "customs_comments": "Order 1042 from our web store"
  }'

The response echoes everything back so you can verify what will print on the commercial invoice (abbreviated):

{
  "order": {
    "id": "PS-8JBH6B",
    "status": "pending",
    "reason_for_export": "SALE",
    "customs_currency": "USD",
    "customs_declaration_statement": null,
    "customs_comments": "Order 1042 from our web store",
    "consignee_type": "consumer",
    "customs_line_items": [
      {
        "id": 501,
        "customs_description": "Cotton t-shirt",
        "harmonized_code": "6109.10",
        "country_of_origin": "CA",
        "unit_value": "30.0",
        "quantity": 4,
        "position": 0,
        "merchant_product_id": "TSHIRT-BLK-M",
        "manufacturer_product_id": null,
        "standardized_product_id": null
      }
    ]
  }
}

Errors return a JSON body with a human-readable error message. Where a client may need to branch, a stable machine-readable code is included: branch on code, never on the message text.

Every response from this API is JSON, whatever your Accept header says. An error never comes back as an HTML page.

Every rate limit

Each pool is counted per team (the provisioning pool, which runs before any team exists, is counted per source address). Spending one pool never affects another.

Creating orders with a full token is not throttled: bulk creation is a core use of this API. A draft-only token is limited to 20 creates a minute and 500 open drafts. Regenerating your token from the account page is limited to 5 per 10 minutes.

Every machine code

The full set, so you can write one handler and cover the API. Codes are stable: a message may be reworded, a code will not.

Auth and account

Payments

Request shape

Order and shipment validation

Customs

Rate limits

Idempotency

Webhooks

A failed void carries one more shape: alongside the error sentence, the body may include a code naming the failure category (for example route for a label UPS will never void) and a headline, the short plain-language sentence we show merchants. Use them to tell "UPS will not void this" from "try again in a moment"; both keys are omitted when UPS gave us nothing to translate.

Register an HTTPS URL and we POST a signed JSON event to it every time one of your shipments moves. That is the alternative to polling GET /api/v1/orders/:id, and it is the only way to learn about the things that happen after a request has already returned 200: rates arriving, a background purchase failing, a scan on the way to delivery.

A team can have up to 5 endpoints. Each one carries its own signing secret and its own list of event types, so you can send purchase events to your order system and delivery events somewhere else. Add and manage them from the API below, or from the Webhooks section of your account page.

Four steps to a working receiver

1. Register an HTTPS endpoint and store the signing secret from that one response.
2. Verify the signature on every POST before you trust the body.
3. Answer 2xx within 10 seconds: queue the work, then reply.
4. Deduplicate on X-Webhook-Event-Id, because an event can arrive more than once.

Events #

Subscribe to the types you want. ping is not subscribable: it is the test event, and it is always delivered to the endpoint you send it to.

The envelope #

Every event has the same shape. data.order is the same object GET /api/v1/orders/:id returns, captured at the moment the event happened: a redelivery days later sends that same snapshot, not a fresh read.

{
  "id": "evt_9f1c2b7a4d6e8f0a1b2c3d4e",
  "type": "order.tracking_updated",
  "created_at": "2026-09-07T14:22:31Z",
  "api_version": "v1",
  "data": {
    "previous_delivery_status": "label_created",
    "delivery_status": "in_transit",
    "order": {
      "id": "PS-A1B2C3",
      "status": "purchased",
      "delivery_status": "in_transit",
      "tracking_numbers": ["1Z0JA0670300123456"]
    }
  }
}

Headers #

Verifying the signature #

Sign the exact raw body you received, before any JSON parsing or re-encoding. Compare in constant time, and reject a timestamp more than 5 minutes old so a captured request cannot be replayed at you later.

require "openssl"

SECRET    = ENV.fetch("WEBHOOK_SIGNING_SECRET")
TOLERANCE = 300 # seconds

def verified?(request)
  timestamp = request.headers["X-Webhook-Timestamp"].to_s
  signature = request.headers["X-Webhook-Signature"].to_s
  body      = request.raw_post

  return false if (Time.now.to_i - timestamp.to_i).abs > TOLERANCE

  expected = "v1=" + OpenSSL::HMAC.hexdigest("SHA256", SECRET, "#{timestamp}.#{body}")
  OpenSSL.secure_compare(expected, signature)
end

const crypto = require("crypto");

const SECRET = process.env.WEBHOOK_SIGNING_SECRET;
const TOLERANCE = 300; // seconds

// rawBody must be the unparsed request body, e.g. express.raw({ type: "*/*" })
function verified(headers, rawBody) {
  const timestamp = headers["x-webhook-timestamp"] || "";
  const signature = headers["x-webhook-signature"] || "";

  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE) return false;

  const expected =
    "v1=" +
    crypto.createHmac("sha256", SECRET).update(`${timestamp}.${rawBody}`).digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Delivery and retries #

• Answer with any 2xx within 10 seconds. Do the work afterwards: queue the event and reply, rather than replying when the work is done.
• An event can arrive more than once. Deduplicate on X-Webhook-Event-Id and treat a repeat as a no-op.
• We do not follow redirects. A 3xx is recorded as a failed delivery.
• HTTPS on port 443 only. We refuse a URL that resolves to a private or loopback address, at registration and again before every send.
• Answer 410 Gone and we turn the endpoint off immediately.

A 408, a 429, any 5xx, a timeout or a connection error is retried 8 times: after 30 seconds, then 2 minutes, 10 minutes, 30 minutes, 1 hour, 2 hours, 6 hours and 12 hours. That is about 21 hours of retrying. Any other 4xx is not retried, because the same request would fail the same way.

Testing your receiver #

Send a ping to an endpoint and we deliver a real, signed event to it with the same headers as everything else. Use it to check your signature verification before any shipment depends on it.

curl -X POST https://www.packagesave.com/api/v1/webhook_endpoints/42/ping \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# 202 Accepted
{ "ping": { "event_id": "evt_1a2b3c", "webhook_endpoint_id": 42, "queued": true } }

curl -X POST https://www.packagesave.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_endpoint": {
      "url": "https://hooks.example.com/shipping-events",
      "description": "Order system",
      "events": ["order.purchased", "order.tracking_updated", "order.delivered"]
    }
  }'

# 201 Created
{
  "webhook_endpoint": {
    "id": 42,
    "url": "https://hooks.example.com/shipping-events",
    "events": ["order.purchased", "order.tracking_updated", "order.delivered"],
    "enabled": true,
    "signing_secret": "whsec_kQ2f...",
    "consecutive_failures": 0,
    "last_delivered_at": null
  }
}

{
  "deliveries": [
    {
      "id": 9001,
      "event_id": "evt_9f1c2b7a4d6e8f0a1b2c3d4e",
      "event_type": "order.tracking_updated",
      "attempt": 2,
      "status": "delivered",
      "response_status": 200,
      "duration_ms": 143,
      "delivered_at": "2026-09-07T14:24:03Z"
    }
  ]
}

Errors #

Send an Idempotency-Key header on a write and a retry is safe: for 24 hours the same key on the same body returns the same answer, run once. That is what a request which times out leaves you needing, because a timeout tells you nothing about whether the write happened.

The header is optional. Without it nothing changes, so your existing integration keeps working exactly as it does today.

Where it applies #

Sending a key #

Mint one key per logical request (a UUID is ideal) and re-send that same key on every retry of it. A key may be 1-255 characters of letters, digits and the symbols _ - : .

curl -X POST https://www.packagesave.com/api/v1/orders \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ "customer": { "email": "buyer@example.com" } }'

What you get back #

A replay is the stored response byte for byte, with one header added:

HTTP/1.1 201 Created
Content-Type: application/json
Idempotent-Replayed: true
X-Request-Id: 6f1c0b2a-3d4e-4f50-9a1b-2c3d4e5f6071

{ "order": { "id": "PS-8JBH6B", "status": "pending" } }

A 409 carries Retry-After: 2: wait, then retry the same key. It resolves to the stored response once the first attempt finishes.

Keys are scoped to your team and expire 24 hours after their first use. After that the same key string is free to use again.

Every response carries an X-Request-Id header, and every error body repeats it as request_id. Quote it to support and we can find the exact request in our logs. Log it beside your own request record and one string ties both sides of an integration together.

{
  "error": "status must be one of: pending, processing, created, purchased, completed, failed, voided, cancelled",
  "code": "invalid_filter",
  "request_id": "4b1a9f2c-0f2e-4f0a-9b0d-7c2a1f4c5d6e"
}

Sending your own X-Request-Id header is supported: we echo the value you sent instead of generating one, so your trace id and ours are the same string.

Everything on this page also exists as a machine-readable OpenAPI 3.1 document: every endpoint, every request body, every response schema, every machine code, the webhook event envelope and the Idempotency-Key header. It is served without authentication, so your tooling can fetch it before you hold a token.

The URL #

https://www.packagesave.com/api/v1/openapi.json

Import it #

Import the URL into Postman or Insomnia to get a ready-made collection: every endpoint, its parameters and its example bodies, without copying anything from this page. Generate a client in your own language with openapi-generator, pointing it at the same URL.

# Save it
curl https://www.packagesave.com/api/v1/openapi.json -o openapi.json

# Or generate a client straight from the URL
npx @openapitools/openapi-generator-cli generate \
  -i https://www.packagesave.com/api/v1/openapi.json \
  -g typescript-fetch \
  -o ./client

Dated entries, newest first: what the API gained, and when.

2026-10-06, Draft-only tokens and the AI skill #

• A draft-only token is made when you click Generate on the account settings page, shown once, and valid for 30 days. Revoke draft-only tokens ends them all without touching your main API token.
• The AI skill lists your sender addresses itself (--list-senders), talks only to the host it was downloaded from, never follows a redirect, and stops on an expired token or the draft limit instead of retrying.

2026-10-06, Draft-only token limits #

• A draft-only token can create 20 orders a minute. The next one answers 429 rate_limited with Retry-After: 60.
• A draft-only token stops at 500 open drafts created through the API: the next create answers 422 with the new code draft_limit_reached. Delete drafts, then try again.
• A full token is unchanged: its creates are not limited.

2026-10-06, Re-quotes #

• POST /api/v1/orders/:id/refresh_shipping_rates is accepted only for a pending draft. Any other status answers 422 with the new code order_not_refreshable, and the order keeps its rates.

2026-10-05, AI assistants #

• A draft-only token on the account settings page, for AI assistants: it can create and quote draft shipments and never buy, void or download labels.
• token_scope on GET /api/v1/current: "drafts" for a draft-only token, null for a full one.
• A new 403 code, insufficient_scope, when a draft-only token calls an endpoint outside its scope.
• A new expired status on GET /api/v1/orders/:id/shipping_rates when the stored rates are no longer current. It used to answer pending forever; call refresh_shipping_rates once and poll again.
• Account page: the two tokens sit side by side, masked by default with Show, and this section is a three-step guide.

2026-09-07, platform round #

• Outbound webhooks: signed, retried events for rates, purchase, void and every delivery-status change, with a delivery log and replay.
• Idempotency-Key on order create and purchase, so a retried request replays its stored response instead of shipping twice.
• X-Request-Id on every response, and Retry-After on every 429.
• A tracking endpoint: GET /api/v1/orders/:id/tracking returns the stored scan history.
• Package signature and unit options on create (delivery_confirmation, unit_of_measurement, unit_value, and the package-level customs fields), plus return_label.
• This OpenAPI document, at https://www.packagesave.com/api/v1/openapi.json.

2026-09-07, hardening round #

• Every response is JSON, whatever your Accept header says, including errors raised before a controller runs.
• Clearer 422s for malformed shapes: a wrong-typed filter, a non-object customer, a non-array packages each name what went wrong instead of failing opaquely.
• GET /api/v1/shipping_addresses/:id documented (it always existed, but was absent from this page).
• Rate-limit pools keyed per account, so two integrators behind one egress address no longer throttle each other.

Returns information about the current authenticated team, plus its primary sender address.

Wrapping: this response nests everything under a team_current root key. Across the API, a list is wrapped in a plural key (orders, invoices, shipping_addresses, customers) beside a pagination object, and a single order, customer or invoice is wrapped in its singular key (order, customer, invoice). The two shipping-address reads are the exception: a single address is returned bare, with no wrapper key.

Response

{
  "team_current": {
    "id": 1,
    "name": "Acme Corp",
    "wallet_required": false,
    "account_credit": {
      "CAD": "50.00"
    },
    "auto_topup_enabled": true,
    "token_scope": null,
    "address": {
      "id": 1,
      "name": "Headquarters",
      "line1": "123 Main St",
      "line2": null,
      "line3": null,
      "city": "Toronto",
      "state": "ON",
      "postal_code": "M5H 2N2",
      "country": "CA",
      "primary": true,
      "residential": false,
      "tax_id": null,
      "tax_id_type": null,
      "secondary_tax_id": null,
      "secondary_tax_id_type": null,
      "full_address": "123 Main St, Toronto, ON, M5H 2N2, CA"
    }
  }
}

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://www.packagesave.com/api/v1/current

Returns a paginated list of customers for the authenticated team.

Parameters

Response

{
  "customers": [
    {
      "id": 1,
      "first_name": "John",
      "last_name": "Doe",
      "company_name": "Acme Inc",
      "email": "john@acme.com",
      "phone_number": "+1-555-0123",
      "name": "John Doe",
      "created_at": "2023-01-15T10:30:00Z",
      "updated_at": "2023-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total_count": 45,
    "total_pages": 3
  }
}

Example Requests

Basic listing

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://www.packagesave.com/api/v1/customers"

With pagination

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://www.packagesave.com/api/v1/customers?page=2&per_page=10"

With search

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://www.packagesave.com/api/v1/customers?q=john@acme.com"

Returns sender addresses for the authenticated team. Use these addresses when creating orders via the API.

Parameters

Response

{
  "shipping_addresses": [
    {
      "id": 1,
      "name": "Warehouse",
      "line1": "123 Main St",
      "line2": null,
      "line3": null,
      "city": "Toronto",
      "state": "ON",
      "postal_code": "M5H 2N2",
      "country": "CA",
      "primary": true,
      "residential": false,
      "tax_id": null,
      "tax_id_type": null,
      "secondary_tax_id": null,
      "secondary_tax_id_type": null,
      "full_address": "123 Main St, Toronto, ON, M5H 2N2, CA"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total_count": 3,
    "total_pages": 1
  }
}

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://www.packagesave.com/api/v1/shipping_addresses"

Fetches one of your team's addresses by id. Use it to re-read a sender address you saved earlier, or to look up any address the API has handed you an id for. Returns 404 for an unknown id or another team's address.

Response

A single address comes back on its own, with no wrapper key:

{
  "id": 1,
  "name": "Warehouse",
  "line1": "123 Main St",
  "line2": null,
  "line3": null,
  "city": "Toronto",
  "state": "ON",
  "postal_code": "M5H 2N2",
  "country": "CA",
  "primary": true,
  "residential": false,
  "tax_id": null,
  "tax_id_type": null,
  "secondary_tax_id": null,
  "secondary_tax_id_type": null,
  "full_address": "123 Main St, Toronto, ON, M5H 2N2, CA"
}

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://www.packagesave.com/api/v1/shipping_addresses/1"

Creates a new sender address for the team.

Request Body

Response

201 Created with the saved address on its own, no wrapper key. Keep the id: it is what ship_from_address_id takes when you create an order. A validation failure returns 422 with an errors object keyed by field.

{
  "id": 42,
  "name": "Warehouse",
  "line1": "123 Main St",
  "line2": null,
  "line3": null,
  "city": "Toronto",
  "state": "ON",
  "postal_code": "M5H 2N2",
  "country": "CA",
  "primary": true,
  "residential": false,
  "tax_id": null,
  "tax_id_type": null,
  "secondary_tax_id": null,
  "secondary_tax_id_type": null,
  "full_address": "123 Main St, Toronto, ON, M5H 2N2, CA"
}

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_address": {
      "name": "Warehouse",
      "line1": "123 Main St",
      "city": "Toronto",
      "state": "ON",
      "postal_code": "M5H 2N2",
      "country": "CA",
      "primary": true
    }
  }' \
  "https://www.packagesave.com/api/v1/shipping_addresses"

Lists your team's orders, newest purchase first (draft orders sort by creation time). Paginated; filterable by lifecycle status, delivery status, sales platform, purchase window, and free-text search. Archived orders are excluded, and so is every member of a multi-piece shipment: those are folded into their lead order, which carries all of the tracking numbers.

Parameters

An unknown filter value returns 422 with code: "invalid_filter" and a message listing the accepted values: filters are never silently ignored.

Response

Each order carries the full order object (same shape as GET /api/v1/orders/:id), including the correlation fields: source, the five channel ids (shopify_order_id, ebay_order_id, amazon_order_id, walmart_order_id, best_buy_order_id), shopify_order_name, purchased_at, delivery_status, total (the final charge including tax), tracking_numbers (one per package), alternate_tracking_numbers (the return leg, once UPS assigns one), and invoice_id (the weekly statement the label charge was billed on; null until the weekly billing run). Abbreviated:

{
  "orders": [
    {
      "id": "PS-8JBH6B",
      "order_number": "PS-8JBH6B",
      "status": "purchased",
      "delivery_status": "in_transit",
      "purchased_at": "2026-07-08T14:03:22Z",
      "total": "27.61",
      "currency": "CAD",
      "source": "shopify",
      "shopify_order_id": "5723201847311",
      "ebay_order_id": null,
      "amazon_order_id": null,
      "walmart_order_id": null,
      "best_buy_order_id": null,
      "shopify_order_name": "#1042",
      "tracking_number": "1Z0JA0676704591639",
      "tracking_numbers": ["1Z0JA0676704591639"],
      "alternate_tracking_numbers": [],
      "invoice_id": 2187
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total_count": 134,
    "total_pages": 7
  }
}

Example Requests

# Shopify shipments purchased since July 1
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.packagesave.com/api/v1/orders?source=shopify&purchased_after=2026-07-01"

# Find an order by tracking number
curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.packagesave.com/api/v1/orders?q=1Z0JA0676704591639"

Creates a new order with customer and shipping information. Automatically enqueues a background job to fetch shipping rates.

Request Body

* Required within each customs_line_items entry; the array itself is needed only for international orders.

Response

id is the order number (a string): use it as :id in every order URL below.

{
  "order": {
    "id": "PS-8JBH6B",
    "order_number": "PS-8JBH6B",
    "status": "pending",
    "tracking_number": null,
    "shipment_id_number": null,
    "rated_price": null,
    "currency": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "last_rated_at": null,
    "residential_delivery": false,
    "label_available": false,
    "label_count": 0,
    "voided_at": null,
    "failed_reason": null,
    "failed_at": null,
    "failure_details": null,
    "reason_for_export": "SALE",
    "customs_currency": "CAD",
    "customs_declaration_statement": null,
    "customs_comments": null,
    "consignee_type": "consumer",
    "direct_delivery_only": false,
    "merchant_reference": "SO-4521",
    "customs_line_items": [],
    "global_checkout": null,
    "purchased_at": null,
    "delivery_status": null,
    "total": null,
    "source": "manual",
    "shopify_order_id": null,
    "ebay_order_id": null,
    "amazon_order_id": null,
    "walmart_order_id": null,
    "best_buy_order_id": null,
    "shopify_order_name": null,
    "tracking_numbers": [],
    "alternate_tracking_numbers": [],
    "invoice_id": null,
    "customer": {
      "id": 456,
      "first_name": "John",
      "last_name": "Doe",
      "company_name": "Acme Corp",
      "email": "john@example.com",
      "phone_number": "+1-555-0123",
      "name": "John Doe",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "ship_to_address": {
      "id": 789,
      "name": "John Doe",
      "line1": "123 Main St",
      "line2": "Suite 100",
      "line3": null,
      "city": "Toronto",
      "state": "ON",
      "postal_code": "M5V 3A8",
      "country": "CA",
      "primary": false,
      "residential": false,
      "tax_id": null,
      "tax_id_type": null,
      "secondary_tax_id": null,
      "secondary_tax_id_type": null,
      "full_address": "123 Main St, Suite 100, Toronto, ON, M5V 3A8, CA"
    },
    "packages": [
      {
        "id": 101,
        "weight": "2.5",
        "length": "30.0",
        "width": "20.0",
        "height": "15.0",
        "value": "100.0",
        "description": "Test description",
        "unit_of_measurement": "metric",
        "has_label": false,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      },
      {
        "id": 102,
        "weight": "1.2",
        "length": "25.0",
        "width": "15.0",
        "height": "10.0",
        "value": "50.0",
        "description": "Test description",
        "unit_of_measurement": "metric",
        "has_label": false,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone_number": "+1-555-0123",
      "company_name": "Acme Corp"
    },
    "shipping_address": {
      "name": "John Doe",
      "line1": "123 Main St",
      "line2": "Suite 100",
      "line3": null,
      "city": "Toronto",
      "state": "ON",
      "postal_code": "M5V 3A8",
      "country": "CA",
      "residential": false
    },
    "packages": [
      {
        "weight": 2.5,
        "length": 30,
        "width": 20,
        "height": 15,
        "value": 100.00
      },
      {
        "weight": 1.2,
        "length": 25,
        "width": 15,
        "height": 10,
        "value": 50.00
      }
    ]
  }' \
  "https://www.packagesave.com/api/v1/orders"

Shipping internationally? See the full example with customs_line_items in International & customs.

Retrieves details for a specific order including customer, shipping address, and packages.

URL Parameters

Response

{
  "order": {
    "id": "PS-8JBH6B",
    "order_number": "PS-8JBH6B",
    "status": "purchased",
    "tracking_number": "1Z999AA1234567890",
    "shipment_id_number": "SHP-2024-0123",
    "rated_price": "27.50",
    "currency": "CAD",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T11:45:00Z",
    "last_rated_at": "2024-01-15T10:31:00Z",
    "residential_delivery": false,
    "label_available": true,
    "label_count": 2,
    "voided_at": null,
    "failed_reason": null,
    "failed_at": null,
    "failure_details": null,
    "reason_for_export": "SALE",
    "customs_currency": "CAD",
    "customs_declaration_statement": null,
    "customs_comments": null,
    "consignee_type": "consumer",
    "direct_delivery_only": false,
    "merchant_reference": "SO-4521",
    "customs_line_items": [],
    "global_checkout": null,
    "purchased_at": "2024-01-15T11:45:00Z",
    "delivery_status": "in_transit",
    "total": "31.08",
    "source": "manual",
    "shopify_order_id": null,
    "ebay_order_id": null,
    "amazon_order_id": null,
    "walmart_order_id": null,
    "best_buy_order_id": null,
    "shopify_order_name": null,
    "tracking_numbers": ["1Z999AA1234567890", "1Z999AA1234567891"],
    "alternate_tracking_numbers": [],
    "invoice_id": 2187,
    "customer": {
      "id": 456,
      "first_name": "John",
      "last_name": "Doe",
      "company_name": "Acme Corp",
      "email": "john@example.com",
      "phone_number": "+1-555-0123",
      "name": "John Doe",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "ship_to_address": {
      "id": 789,
      "name": "John Doe",
      "line1": "123 Main St",
      "line2": "Suite 100",
      "line3": null,
      "city": "Toronto",
      "state": "ON",
      "postal_code": "M5V 3A8",
      "country": "CA",
      "primary": false,
      "residential": false,
      "tax_id": null,
      "tax_id_type": null,
      "secondary_tax_id": null,
      "secondary_tax_id_type": null,
      "full_address": "123 Main St, Suite 100, Toronto, ON, M5V 3A8, CA"
    },
    "packages": [
      {
        "id": 101,
        "weight": "2.5",
        "length": "30.0",
        "width": "20.0",
        "height": "15.0",
        "value": "100.0",
        "description": "Test description",
        "unit_of_measurement": "metric",
        "has_label": true,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      },
      {
        "id": 102,
        "weight": "1.2",
        "length": "25.0",
        "width": "15.0",
        "height": "10.0",
        "value": "50.0",
        "description": "Test description",
        "unit_of_measurement": "metric",
        "has_label": true,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
}

Response Fields

Global Checkout (guaranteed duties)

When your buyer prepays guaranteed duties through UPS Global Checkout at Shopify checkout, we capture the quote on import and attach it to the label at purchase. Every order response carries a read-only global_checkout object: null on orders without a quote. It is not writable: the quote is captured from the Shopify order, and the outcome is recorded from UPS's own ship response.

A quoted order that hasn't shipped yet reports the quote with the outcome fields still null:

"global_checkout": {
  "quote_id": "lc-767870b6a9ad41f092c888ed144d3979",
  "attached": null,
  "guarantee_applied": null,
  "skip_reason": null,
  "at": null
}

After the label ships with the guarantee confirmed:

"global_checkout": {
  "quote_id": "lc-767870b6a9ad41f092c888ed144d3979",
  "attached": true,
  "guarantee_applied": true,
  "skip_reason": null,
  "at": "2026-08-14T15:04:05Z"
}

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://www.packagesave.com/api/v1/orders/123"

Retrieves available shipping rates for an order. Returns "pending" status if rates are still being calculated. Returns "expired" when the stored rates are no longer current: call refresh_shipping_rates once, then poll again.

Rates are quoted from every UPS account that can ship the lane (the same accounts the web app compares), and the list shows one row per service level: the cheapest option for that service, sorted cheapest first. Purchasing a rate ships on the account that quoted it.

Response (Ready)

Rates expire: check expires_at and refresh if the rate you want has lapsed. marked_up_price is the price your team pays; retail_price is the carrier's published price for comparison. residential_charge is the residential surcharge already included in that price, and is_return_rate marks a UPS return-service label, which caps declared value at $1,000 and can't carry prepaid duties.

{
  "status": "ready",
  "shipping_rates": [
    {
      "id": 789,
      "service_code": "03",
      "service_name": "Ground",
      "service_description": "UPS Standard",
      "retail_price": "38.90",
      "marked_up_price": "27.50",
      "currency": "CAD",
      "expires_at": "2024-01-16T10:31:00Z",
      "residential_charge": "0.0",
      "transit_days": 3,
      "is_return_rate": false,
      "created_at": "2024-01-15T10:31:00Z"
    }
  ]
}

Shipment protection (protection)

When a shipment carries an InsureShield® Shipping Protection election (made on the web, on an enabled account), each rate also carries protection: insureshield when that rate's label is protected by InsureShield® Shipping Protection, ups_declared_value when the label carries UPS declared value instead, or none when the election was declined and the label ships with UPS's standard liability only. A rate that ships on our US account carries UPS declared value regardless of the election and adds a protection_note saying so. Both keys are omitted when no election exists.

{
  "status": "ready",
  "shipping_rates": [
    {
      "id": 789,
      "service_code": "03",
      "service_name": "Ground",
      "marked_up_price": "27.50",
      "currency": "CAD",
      "is_return_rate": false,
      "protection": "insureshield"
    },
    {
      "id": 790,
      "service_code": "11",
      "service_name": "Standard",
      "marked_up_price": "24.10",
      "currency": "CAD",
      "is_return_rate": false,
      "protection": "ups_declared_value",
      "protection_note": "UPS declared value applies on this rate: it ships on our US account."
    }
  ]
}

Hidden rates (notes)

Some orders can't ship on a UPS return-service rate: a Canadian DDP forward import, a Direct Delivery Only shipment, an order carrying a Global Checkout duties guarantee, or an Export DDP shipment whose duties are billed to your own UPS account. When a forward rate is available, those return-service rates are left out of the listing and the purchase endpoint rejects them. The response then carries a notes array saying how many rates were left out and why, so a shorter list is never a mystery. The key is omitted when nothing was hidden, and a return-only quote is returned in full so you are never left without a buyable rate. Canadian DDP forward imports are the exception: return-service rates are never offered there, so the listing comes back empty with a note (POST /orders/:id/refresh_shipping_rates re-quotes).

{
  "status": "ready",
  "shipping_rates": [ ... ],
  "notes": [
    "1 UPS return-service rate hidden: this order's UPS Global Checkout duties guarantee only applies to forward shipments."
  ]
}

Response (Pending)

{
  "status": "pending",
  "message": "Shipping rates are being calculated"
}

Response (Failed)

If the last rate fetch failed and produced no rates (for example, an undeliverable PO Box address), the endpoint reports the failure instead of staying "pending" forever. Fix the order details, then POST /api/v1/orders/:id/refresh_shipping_rates to try again.

{
  "status": "failed",
  "error": "UPS can't deliver to PO Box addresses."
}

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://www.packagesave.com/api/v1/orders/123/shipping_rates"

Invalidates existing shipping rates and re-enqueues the rate fetching job. Use this when order details have changed.

Response

{
  "status": "success",
  "message": "Shipping rates refresh initiated"
}

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.packagesave.com/api/v1/orders/123/refresh_shipping_rates"

Purchases a shipping label for the order using the selected shipping rate. Enqueues a background job to create the shipment.

Request Body

Response

order is the full order object (same shape as GET /api/v1/orders/:id), abbreviated here:

{
  "status": "success",
  "message": "Order purchase initiated",
  "order": {
    "id": "PS-8JBH6B",
    "order_number": "PS-8JBH6B",
    "status": "processing",
    "rated_price": "27.50",
    "currency": "CAD"
  }
}

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"shipping_rate_id": 789}' \
  "https://www.packagesave.com/api/v1/orders/123/purchase"

Error Responses

A 402 Payment Required means the purchase couldn't be paid for. Branch on the code field rather than the human-readable error message:

Purchase also runs the pre-flight checks a label needs before UPS sees it: a real package size (package_dimensions_required), a sender phone on an international shipment (shipper_phone_required), a contactable recipient for an Access Point (access_point_contact_info_incomplete), declared values on a return label (return_declared_values_required), retired UPS Letter packaging (letter_packaging_retired), and a usable shipping_rate_id (invalid_shipping_rate_id). Each is a 422; every code on the API is listed in Errors & rate limits.

An insufficient balance returns the shortfall so you can top up the exact amount:

{
  "error": "Insufficient balance for this label — it needs about $42.10 CAD including tax and your balance is $30.00 CAD. Add at least $12.10 CAD on the Payments page to continue. Unspent funds are refundable anytime (less card-processing fees).",
  "code": "insufficient_prepaid_balance",
  "estimated_total": "42.10",
  "available": "30.00",
  "shortfall": "12.10",
  "currency": "CAD"
}

Downloads the shipping label for a purchased order. Returns PDF by default (recommended for printing), or PNG/base64 for programmatic access.

Query Parameters

Response Formats

PDF (default)

Returns a PDF with all labels (one page per package) at your team's label size: or the label_size you pass. Best for thermal printers.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://www.packagesave.com/api/v1/orders/123/label" \
     -o label.pdf

PNG

Returns a single label as PNG image. Use package_index for multi-package orders.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://www.packagesave.com/api/v1/orders/123/label?label_format=png" \
     -o label.png

Base64 JSON

Returns raw base64 data for each package. Useful for direct thermal printer integration.

{
  "labels": [
    {
      "package_index": 0,
      "tracking_number": "1Z999AA1234567890",
      "image_format": "gif",
      "image_data": "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7..."
    }
  ]
}

Error Responses

// 404: no label available yet
{ "error": "No label available. Order may still be processing." }

// 404: invalid package index
{ "error": "Package index 2 not found. Order has 1 package(s) (valid indices: 0-0)." }

// 422: invalid label_format
{ "error": "Invalid label_format. Use 'pdf', 'png', or 'base64'." }

// 500: the stored label bytes could not be decoded
{ "error": "The stored label image could not be read.", "code": "label_unreadable" }

// 500: the multi-page PDF could not be built
{ "error": "Failed to generate label PDF" }

The full scan history for a shipment: every carrier activity, the per-piece breakdown of a multi-package shipment, and when the status last changed. GET /api/v1/orders/:id gives you the current delivery_status; this gives you how it got there.

Served from the scan history we already hold, refreshed by our own polling. It never calls the carrier on your behalf, so it is safe to poll: 240 requests per minute.

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.packagesave.com/api/v1/orders/PS-8JBH6B/tracking"

Response

{
  "tracking": {
    "order_id": "PS-8JBH6B",
    "delivery_status": "delivered",
    "delivery_status_updated_at": "2026-09-05T18:04:11.000Z",
    "latest_activity_at": "2026-09-05T14:02:00Z",
    "tracking_numbers": ["1Z0JA0670000000001", "1Z0JA0670000000002"],
    "alternate_tracking_numbers": [],
    "packages": [
      {
        "tracking_number": "1Z0JA0670000000001",
        "status": "delivered",
        "description": "Delivered",
        "timestamp": "2026-09-05T14:02:00Z",
        "primary": true
      },
      {
        "tracking_number": "1Z0JA0670000000002",
        "status": "delivered",
        "description": "Delivered",
        "timestamp": "2026-09-05T13:47:00Z"
      }
    ],
    "activities": [
      {
        "at": "2026-09-05T14:02:00Z",
        "status_code": "011",
        "description": "Delivered",
        "location": "Toronto, ON, CA"
      },
      {
        "at": "2026-09-05T06:11:00Z",
        "status_code": "OT",
        "description": "Out For Delivery Today",
        "location": "Mississauga, ON, CA"
      }
    ]
  }
}

Fields

Voids a purchased shipment. If UPS confirms the void, the shipping charge is credited back to your account balance and the order status becomes "voided".

URL Parameters

Requirements

• The order is in purchased status
• It hasn't been voided already
• It isn't a member of a multi-piece shipment: void the lead order instead, which voids every piece
• The package isn't sitting at a UPS Access Point
• The package isn't delivered or returned

Anything short of those five is refused before we call UPS, with a message naming the reason. Everything else is attempted: UPS is the authority on whether a label can still be voided, and an in-transit tracking state is often a scan we can still cancel behind.

Response (Success)

order is the full order object, abbreviated here:

{
  "status": "success",
  "message": "Shipment has been successfully voided",
  "order": {
    "id": "PS-8JBH6B",
    "order_number": "PS-8JBH6B",
    "status": "voided",
    "tracking_number": "1Z999AA1234567890",
    "shipment_id_number": "1Z999AA1234567890",
    "voided_at": "2024-01-15T12:00:00Z",
    "label_available": false
  }
}

Response (Retryable: 503)

If UPS is still processing the freshly created label, the void can't complete yet. Retry after the indicated delay:

{
  "error": "UPS is still processing this label. Retry in 15 minutes.",
  "retryable": true,
  "retry_after_seconds": 900
}

Response (Error)

{
  "error": "Failed to void shipment. Please try again or contact support."
}

Response (UPS Already Has the Package: 422)

Once UPS has scanned the package, the label can't be voided. This answer is final, so don't retry it:

{
  "error": "UPS already has this package, so the label can't be voided.",
  "code": "route",
  "headline": "UPS already has this package, so the label can't be voided.",
  "retryable": false
}

What Happens When Voiding

• The shipment is cancelled with UPS (only after UPS confirms the void)
• Shipping label files are deleted; tracking numbers are kept for reference
• A negative balance transaction credits the order value back to your account balance
• Order status is updated to "voided" and the voided_at timestamp is set

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://www.packagesave.com/api/v1/orders/123/void_shipment"

Lists your team's weekly statements, newest first: the same set shown on the Payments → Statements page in the web app. Read-only: there are no billing mutations in the API.

Parameters

Response Fields

Response

{
  "invoices": [
    {
      "id": 2187,
      "statement_number": "#276",
      "status": "paid",
      "currency": "CAD",
      "total_amount": "213.47",
      "amount_billed_before_credit": "238.47",
      "credit_applied_total": "25.0",
      "start_date": "2026-06-28",
      "invoice_date": "2026-07-04",
      "paid_at": "2026-07-05T04:12:09Z",
      "memo": null,
      "created_at": "2026-07-05T04:05:11Z",
      "updated_at": "2026-07-05T04:12:09Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total_count": 41,
    "total_pages": 3
  }
}

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://www.packagesave.com/api/v1/invoices?per_page=50"

A single statement with its per-transaction line_items, oldest first. Every line follows the ledger sign: type: "charge" for positive amounts (label purchases, adjustments) and type: "credit" for negative amounts (void refunds, account credits, applied funds). Lines that belong to an order carry its order_number and tracking_number for the reverse join; other lines (credits, rollovers) carry null.

URL Parameters

Response

{
  "invoice": {
    "id": 2187,
    "statement_number": "#276",
    "status": "paid",
    "currency": "CAD",
    "total_amount": "213.47",
    "amount_billed_before_credit": "238.47",
    "credit_applied_total": "25.0",
    "start_date": "2026-06-28",
    "invoice_date": "2026-07-04",
    "paid_at": "2026-07-05T04:12:09Z",
    "memo": null,
    "created_at": "2026-07-05T04:05:11Z",
    "updated_at": "2026-07-05T04:12:09Z",
    "line_items": [
      {
        "id": 90411,
        "amount": "27.61",
        "currency": "CAD",
        "type": "charge",
        "description": "Shipping label purchase - Order #12536",
        "order_number": "PS-8JBH6B",
        "tracking_number": "1Z0JA0676704591639",
        "created_at": "2026-06-30T18:22:41Z"
      },
      {
        "id": 90502,
        "amount": "-19.84",
        "currency": "CAD",
        "type": "credit",
        "description": "Shipping label void refund - Order #12401",
        "order_number": "PS-3KDPQR",
        "tracking_number": "1Z0JA0676704580021",
        "created_at": "2026-07-02T09:15:03Z"
      }
    ]
  }
}

Returns 404 for an unknown id or another team's invoice. The detail endpoint resolves every invoice_id an order reports: including invoices the statements list hides (bookkeeping entries).

Example Request

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     "https://www.packagesave.com/api/v1/invoices/2187"

Reconciling shipments against your weekly statements (across sales platforms) takes three calls:

• 1. List shipments by platform: GET /api/v1/orders?source=shopify (or ebay / manual). Each order carries its platform ids (shopify_order_id, shopify_order_name, ebay_order_id) so you can match it to your store's records.
• 2. Read each order's invoice_id: the weekly statement its label charge was billed on. null means the charge hasn't been swept onto a statement yet: a statement closes on the Saturday week boundary and is generated the following Sunday at 12:05am Eastern, and invoice_id fills in then.
• 3. Pull the statement: GET /api/v1/invoices/:id. Its line_items carry order_number for the reverse join, so you can tie every charged dollar back to a shipment.