Drop a shipment in, get a label back.

# Pass the key on every request
curl https://goatlabels.io/api/v1/shipments \
  -H "Authorization: Bearer $GOATLABELS_API_KEY"

curl -X POST https://goatlabels.io/api/v1/rates/quote \
  -H "Authorization: Bearer $GOATLABELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": { "postal_code": "94105", "country": "US" },
    "to":   { "postal_code": "M5H 1A1", "country": "CA" },
    "parcel": { "length": 12, "width": 9, "height": 4, "weight": 2, "weight_unit": "lb" },
    "items": [{ "description": "T-shirt", "quantity": 1, "declared_value": 25,
                "currency": "USD", "country_of_origin": "US", "hs_code": "6109.10" }]
  }'

curl -X POST https://goatlabels.io/api/v1/shipments \
  -H "Authorization: Bearer $GOATLABELS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "from": {
      "name": "Warehouse",
      "line1": "1 Market St", "city": "San Francisco",
      "state": "CA", "postal_code": "94105", "country": "US"
    },
    "to": {
      "name": "Jane Doe",
      "line1": "9 King St", "city": "Toronto",
      "state": "ON", "postal_code": "M5H 1A1", "country": "CA"
    },
    "parcel": {
      "length": 12, "width": 9, "height": 4,
      "weight": 2, "weight_unit": "lb"
    },
    "items": [{
      "description": "T-shirt", "quantity": 1,
      "declared_value": 25, "currency": "USD",
      "country_of_origin": "US", "hs_code": "6109.10"
    }],
    "reference": "ORD-1042",
    "acknowledgements": {
      "noHazardous": true,
      "noPerishable": true,
      "noProhibited": true,
      "accurateDeclaration": true,
      "carrierTermsAccepted": true,
      "version": "v1-2026-05",
      "acceptedAt": "2026-05-08T12:00:00Z"
    }
  }'

import fetch from "node-fetch";
import { randomUUID } from "node:crypto";

const res = await fetch("https://goatlabels.io/api/v1/shipments", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GOATLABELS_API_KEY}`,
    "Content-Type": "application/json",
    // A fresh UUID per *intent*. Reuse the same key on retries.
    "Idempotency-Key": randomUUID(),
  },
  body: JSON.stringify({
    from: { name: "Warehouse", line1: "1 Market St", city: "San Francisco",
            state: "CA", postal_code: "94105", country: "US" },
    to:   { name: "Jane Doe",  line1: "9 King St",   city: "Toronto",
            state: "ON", postal_code: "M5H 1A1",     country: "CA" },
    parcel: { length: 12, width: 9, height: 4, weight: 2, weight_unit: "lb" },
    items:  [{ description: "T-shirt", quantity: 1, declared_value: 25,
               currency: "USD", country_of_origin: "US", hs_code: "6109.10" }],
    reference: "ORD-1042",
    // Compliance attestation. Strongly encouraged on create;
    // REQUIRED on POST /v1/shipments/:id/purchase.
    acknowledgements: {
      noHazardous: true,
      noPerishable: true,
      noProhibited: true,
      accurateDeclaration: true,
      carrierTermsAccepted: true,
      version: "v1-2026-05",
      acceptedAt: new Date().toISOString(),
    },
  }),
});

if (!res.ok) throw new Error(`GoatLabels: ${res.status} ${await res.text()}`);
const shipment = await res.json();
console.log(shipment.id, shipment.status);

import os, uuid, requests

res = requests.post(
    "https://goatlabels.io/api/v1/shipments",
    headers={
        "Authorization": f"Bearer {os.environ['GOATLABELS_API_KEY']}",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "from": {"name": "Warehouse", "line1": "1 Market St", "city": "San Francisco",
                 "state": "CA", "postal_code": "94105", "country": "US"},
        "to":   {"name": "Jane Doe",  "line1": "9 King St",   "city": "Toronto",
                 "state": "ON", "postal_code": "M5H 1A1",     "country": "CA"},
        "parcel": {"length": 12, "width": 9, "height": 4, "weight": 2, "weight_unit": "lb"},
        "items":  [{"description": "T-shirt", "quantity": 1, "declared_value": 25,
                    "currency": "USD", "country_of_origin": "US", "hs_code": "6109.10"}],
        "reference": "ORD-1042",
        # Compliance attestation. Strongly encouraged on create;
        # REQUIRED on POST /v1/shipments/:id/purchase.
        "acknowledgements": {
            "noHazardous": True,
            "noPerishable": True,
            "noProhibited": True,
            "accurateDeclaration": True,
            "carrierTermsAccepted": True,
            "version": "v1-2026-05",
            "acceptedAt": "2026-05-08T12:00:00Z",
        },
    },
    timeout=10,
)
res.raise_for_status()
print(res.json()["id"])

curl https://goatlabels.io/api/v1/shipments/shp_… \
  -H "Authorization: Bearer $GOATLABELS_API_KEY"

# Re-select the carrier on a draft (re-quotes + updates total cost).
curl -X PATCH https://goatlabels.io/api/v1/shipments/shp_… \
  -H "Authorization: Bearer $GOATLABELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "service": "UPS Ground" }'

# Or pin an exact rate id returned by POST /v1/shipments (shipment.rates[].rate_id):
#   { "rate_id": "rate_…" }
# Or the structured courier-settings block:
#   { "courier_settings": { "courier_service_id": "…", "allow_courier_fallback": false } }

curl -X POST https://goatlabels.io/api/v1/shipments/shp_…/purchase \
  -H "Authorization: Bearer $GOATLABELS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "acknowledgements": {
      "noHazardous": true,
      "noPerishable": true,
      "noProhibited": true,
      "accurateDeclaration": true,
      "carrierTermsAccepted": true,
      "version": "v1-2026-05",
      "acceptedAt": "2026-05-08T12:00:00Z"
    }
  }'

curl -X POST https://goatlabels.io/api/v1/shipments/shp_…/void \
  -H "Authorization: Bearer $GOATLABELS_API_KEY"

# Up to 50 drafts in one call. Each entry is the SAME body as POST /v1/shipments.
# Drafts are NOT auto-rated in batch — rate each via PATCH or at purchase.
curl -X POST https://goatlabels.io/api/v1/shipments/batch \
  -H "Authorization: Bearer $GOATLABELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipments": [
      { "from": { … }, "to": { … }, "parcel": { … }, "reference": "ORD-1" },
      { "from": { … }, "to": { … }, "parcel": { … }, "reference": "ORD-2" }
    ]
  }'

{
  "object": "batch",
  "created_count": 2,
  "error_count": 0,
  "created": [ { "id": "shp_…", "object": "shipment", "status": "draft", ... } ],
  "errors": []
}

# Buy labels for up to 10 drafts. One acknowledgements block covers the batch.
# Each item is independently atomic (debit + refund-on-failure).
curl -X POST https://goatlabels.io/api/v1/shipments/batch-purchase \
  -H "Authorization: Bearer $GOATLABELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipment_ids": ["shp_a", "shp_b"],
    "acknowledgements": {
      "noHazardous": true, "noPerishable": true, "noProhibited": true,
      "accurateDeclaration": true, "carrierTermsAccepted": true,
      "version": "v1-2026-05", "acceptedAt": "2026-05-08T12:00:00Z"
    }
  }'

{
  "object": "batch_purchase",
  "purchased_count": 1,
  "failed_count": 1,
  "results": [
    { "shipment_id": "shp_a", "ok": true,  "status": 200, "response": { ... } },
    { "shipment_id": "shp_b", "ok": false, "status": 402, "response": { "error": { ... } } }
  ]
}

curl https://goatlabels.io/api/v1/shipments?limit=25 \
  -H "Authorization: Bearer $GOATLABELS_API_KEY"

{
  "object": "list",
  "has_more": false,
  "data": [ { "id": "shp_…", "object": "shipment", "status": "purchased", ... } ]
}

# By tracking number…
curl https://goatlabels.io/api/v1/tracking/1Z999AA10123456784 \
  -H "Authorization: Bearer $GOATLABELS_API_KEY"

# …or by shipment id (works before the first carrier scan too)
curl https://goatlabels.io/api/v1/shipments/shp_…/tracking \
  -H "Authorization: Bearer $GOATLABELS_API_KEY"

{
  "object": "tracking",
  "tracking_number": "1Z999AA10123456784",
  "shipment_id": "shp_…",
  "carrier": "UPS",
  "status": "in_transit",
  "live": true,
  "eta_date": "2026-07-08",
  "tracking_page_url": "https://…",
  "checkpoints": [
    { "time": "2026-07-03T09:12:00Z", "location": "San Francisco, CA", "message": "Departed facility", "status": "in_transit" },
    { "time": "2026-07-02T18:40:00Z", "location": "San Francisco, CA", "message": "Origin scan",       "status": "in_transit" }
  ]
}

curl -X POST https://goatlabels.io/api/v1/shipments/shp_…/return \
  -H "Authorization: Bearer $GOATLABELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer return — wrong size", "refund_amount": 25 }'

{
  "object": "return",
  "id": "ret_…",
  "shipment_id": "shp_…",
  "status": "label_created",
  "carrier": "USPS",
  "tracking_number": "9400…",
  "label_url": "https://…",
  "reason": "Customer return — wrong size",
  "refund_amount": 25,
  "cost": 6.42,
  "created": 1731000000
}

curl https://goatlabels.io/api/v1/carriers \
  -H "Authorization: Bearer $GOATLABELS_API_KEY"

{
  "object": "list",
  "data": [
    {
      "object": "carrier",
      "id": "usps",
      "name": "USPS",
      "services": [
        { "name": "USPS Priority Mail", "international": false, "ddp_supported": false, "transit_time": "1-3 working days" },
        { "name": "USPS Priority Mail Express", "international": false, "ddp_supported": false, "transit_time": "1-2 working days" }
      ]
    }
  ],
  "has_more": false
}

curl https://goatlabels.io/api/v1/boxes \
  -H "Authorization: Bearer $GOATLABELS_API_KEY"

{
  "object": "box_catalog",
  "carrier_boxes": [
    {
      "object": "carrier_box",
      "slug": "usps_priority_flat_medium_1",
      "carrier": "USPS",
      "name": "Priority Mail Medium Flat Rate Box — 1",
      "length": 11.25, "width": 8.75, "height": 6,
      "dimension_unit": "in",
      "flat_rate": true
    }
  ],
  "custom_boxes": [
    {
      "object": "custom_box",
      "id": "box_…",
      "name": "Sneaker box",
      "length": 14, "width": 10, "height": 5,
      "dimension_unit": "in",
      "weight": 2, "weight_unit": "lb",
      "type": "box",
      "default": true
    }
  ]
}

# Save a warehouse once…
curl -X POST https://goatlabels.io/api/v1/addresses \
  -H "Authorization: Bearer $GOATLABELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "SF Warehouse", "default": true,
    "name": "Warehouse", "line1": "1 Market St",
    "city": "San Francisco", "state": "CA",
    "postal_code": "94105", "country": "US",
    "phone": "+14155550100"
  }'

# …then create shipments with just the id
curl -X POST https://goatlabels.io/api/v1/shipments \
  -H "Authorization: Bearer $GOATLABELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_address_id": "adr_…",
    "to": { … }, "parcel": { … }
  }'

curl https://goatlabels.io/api/v1/wallet \
  -H "Authorization: Bearer $GOATLABELS_API_KEY"

curl "https://goatlabels.io/api/v1/wallet/transactions?limit=25" \
  -H "Authorization: Bearer $GOATLABELS_API_KEY"

{
  "object": "wallet",
  "balance": 142.55,
  "currency": "USD",
  "pending_refund_amount": 6.42,
  "next_refund_available_at": 1731600000
}

# Everything on the account, newest first (cursor-paginated)…
curl "https://goatlabels.io/api/v1/adjustments?limit=25" \
  -H "Authorization: Bearer $GOATLABELS_API_KEY"

# …or just one shipment's adjustments
curl https://goatlabels.io/api/v1/shipments/shp_…/adjustments \
  -H "Authorization: Bearer $GOATLABELS_API_KEY"

{
  "object": "list",
  "has_more": false,
  "data": [{
    "object": "adjustment",
    "id": "adj_…",
    "shipment_id": "shp_…",
    "reason": "reweigh",
    "description": "Carrier re-weigh: billed weight 3.2 lb vs declared 2 lb",
    "original_amount": 8.40,
    "adjusted_amount": 10.29,
    "delta_amount": 1.89,
    "currency": "USD",
    "wallet_transaction_id": "txn_…",
    "posted_at": 1731000000,
    "created": 1731000000
  }]
}

curl -X POST https://goatlabels.io/api/v1/addresses/validate \
  -H "Authorization: Bearer $GOATLABELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "line1": "9 King St", "city": "Toronto",
    "state": "ON", "postal_code": "M5H 1A1", "country": "CA"
  }'

{
  "object": "address_validation",
  "status": "verified",
  "address_type": "commercial",
  "residential": false,
  "corrected": {
    "line1": "9 King St W", "line2": null, "city": "Toronto",
    "state": "ON", "postal_code": "M5H 1A1", "country": "CA"
  },
  "warnings": []
}

curl -X POST https://goatlabels.io/api/v1/pickups \
  -H "Authorization: Bearer $GOATLABELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipment_ids": ["shp_a", "shp_b"],
    "pickup_date": "2026-07-01",
    "time_window": "09:00 — 12:00"
  }'

{
  "object": "pickup",
  "id": "pck_…",
  "pickup_date": "2026-07-01",
  "time_window": "09:00 — 12:00",
  "carrier": "UPS",
  "shipment_ids": ["shp_a", "shp_b"],
  "status": "scheduled",
  "confirmation_number": "WP12345",
  "pickup_fee": 0,
  "created": 1731000000
}

# Page 1
curl "https://goatlabels.io/api/v1/shipments?limit=25" \
  -H "Authorization: Bearer $GOATLABELS_API_KEY"

# Page 2 — pass the LAST id from page 1
curl "https://goatlabels.io/api/v1/shipments?limit=25&starting_after=shp_…" \
  -H "Authorization: Bearer $GOATLABELS_API_KEY"

# Retry-safe: same key + same body = same result, no duplicate shipment
curl -X POST https://goatlabels.io/api/v1/shipments \
  -H "Authorization: Bearer $GOATLABELS_API_KEY" \
  -H "Idempotency-Key: 7c1e4f2a-…" \
  -H "Content-Type: application/json" \
  -d @shipment.json

# The signing secret is returned ONCE in "secret" — store it now.
curl -X POST https://goatlabels.io/api/v1/webhooks \
  -H "Authorization: Bearer $GOATLABELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/goatlabels",
    "events": ["shipment.label.created", "shipment.cancelled"]
  }'

{
  "object": "webhook",
  "id": "whk_…",
  "url": "https://example.com/webhooks/goatlabels",
  "events": ["shipment.label.created", "shipment.cancelled"],
  "enabled": true,
  "secret_preview": "whsec_…ab12",
  "created": 1731000000,
  "secret": "whsec_…"   // shown ONCE — store it now
}

import crypto from "node:crypto";
import express from "express";

const app = express();
// Webhook verification needs the *raw* bytes — JSON-parsing first will
// re-serialize and break the signature.
app.use("/webhooks/goatlabels", express.raw({ type: "application/json" }));

app.post("/webhooks/goatlabels", (req, res) => {
  const sig = req.headers["x-goatlabels-signature"];
  if (typeof sig !== "string") return res.status(400).end();

  // Header is "t=<unix>,v1=<hex>"
  const parts = Object.fromEntries(
    sig.split(",").map((p) => p.split("=") as [string, string]),
  );
  const t = parts.t;
  const v1 = parts.v1;
  if (!t || !v1) return res.status(400).end();

  const expected = crypto
    .createHmac("sha256", process.env.GOATLABELS_WEBHOOK_SECRET)
    .update(`${t}.${req.body.toString("utf8")}`)
    .digest("hex");

  // Constant-time compare to avoid timing oracles.
  const ok =
    expected.length === v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(v1, "hex"));
  if (!ok) return res.status(401).end();

  // Optional: reject events older than 5 minutes to mitigate replay.
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > 300) {
    return res.status(401).end();
  }

  const event = JSON.parse(req.body.toString("utf8"));
  // ... handle event.event (shipment.* | batch.* | credit.balance.low | payment.confirmed | ping)
  res.status(200).end();
});

import os, hmac, hashlib, time
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["GOATLABELS_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/goatlabels")
def goatlabels_hook():
    sig = request.headers.get("X-GoatLabels-Signature", "")
    parts = dict(p.split("=", 1) for p in sig.split(",") if "=" in p)
    t, v1 = parts.get("t"), parts.get("v1")
    if not t or not v1:
        abort(400)

    # Use raw body bytes — re-serializing JSON would break the signature.
    payload = f"{t}.{request.get_data(as_text=True)}".encode()
    expected = hmac.new(SECRET, payload, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, v1):
        abort(401)
    if abs(int(time.time()) - int(t)) > 300:
        abort(401)  # replay window

    event = request.get_json()
    # ... handle event["event"] (shipment.* | batch.* | credit.balance.low | payment.confirmed | ping)
    return "", 200

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "type": "invalid_request_error",
    "message": "Request body failed validation.",
    "issues": [
      {
        "code": "invalid_type",
        "expected": "string",
        "received": "undefined",
        "path": ["to", "postal_code"],
        "message": "Required"
      },
      {
        "code": "too_small",
        "minimum": 1,
        "type": "number",
        "inclusive": true,
        "exact": false,
        "path": ["parcel", "weight"],
        "message": "Number must be greater than or equal to 1"
      }
    ]
  }
}

# Generate a typed client from the spec (example: openapi-typescript)
npx openapi-typescript https://goatlabels.io/api/v1/openapi.yaml -o goatlabels.d.ts