← Docs/API Reference

API Reference

Static reference for the USPS workflows RevAddress supports today: addresses, rates, service standards, locations, tracking, label workflows, BYOK, and admin diagnostics. Base URL: https://api.revaddress.com

How to evaluate and expand

Standardization, geocoding, and address extract run free with no signup. Connect your own USPS Developer Portal license — any key, Free included — and DPV, rates, service standards, city/state, and tracking run on your license through our infrastructure. Add an API key for batch operations, checkout validation, webhooks, and pickup scheduling.

Free tier

Address standardization + extract (US Census)
Street-level geocode + ACS demographics demo
Sandbox DPV / CMRA demo
DPV, rates, service standards, and city/state on your USPS license (BYOK)

Standardize and geocode live with no key. Connect your own USPS Developer Portal app — Free keys can — and the USPS suite runs on our infrastructure.

API key required

Package tracking
Batch validation + checkout widget
Dashboard + webhooks
Pickup scheduling

Paid endpoints unlock after signup. Flat monthly pricing.

Higher volume

Increased throughput
Enterprise onboarding
Custom integrations

Download OpenAPI YAML Get Free API Key

Census address standardization, geocoding, address extract, and the intelligence demo work free — no API key, no USPS license. DPV, ZIP+4 city/state lookup, rates, service standards, and locations run on your USPS license (BYOK). Add an API key when you move into tracking, labels, request-access pickup, batch validation, or BYOK.

Authentication

Free Tier

No API key required. IP-rate-limited: 30 req/10s. Census standardization, geocoding, address extract. Rates, locations, and service standards on your USPS license (BYOK).

Protected

X-API-Key: rv_live_...
Labels, tracking, pickup, batch validation.

Rate Limits

Starter 120/min · Growth 300/min · Pro 600/min. Headers: X-RateLimit-Limit, -Remaining, -Reset.

Try it live

Try the validate endpoint right now — no API key, no signup. Keyless calls return Census standardization with coordinates; full USPS DPV and ZIP+4 run on your own USPS license (BYOK, free key included) or on hosted verification as it comes online. Guided missing-unit recovery works on both.

Smart mode by default

Street Address

Unit / Apt / Suite (optional)

City

State

ZIP

Response

← Enter an address and click Validate

Quick Start Examples

The four most common first requests. Hit the live API immediately.

POST/api/address/validate

Address validation — free tier, no key needed

FREE

curl -s "https://api.revaddress.com/api/address/validate" \
  -H "Content-Type: application/json" \
  -d '{"streetAddress":"228 Park Ave S PMB 101842","city":"New York","state":"NY","ZIPCode":"10003"}'

import requests

resp = requests.post(
    "https://api.revaddress.com/api/address/validate",
    json={
        "streetAddress": "228 Park Ave S PMB 101842",
        "city": "New York",
        "state": "NY",
        "ZIPCode": "10003"
    }
)
data = resp.json()
print(data["address"]["ZIPPlus4"])  # 1502

const resp = await fetch("https://api.revaddress.com/api/address/validate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    streetAddress: "228 Park Ave S PMB 101842",
    city: "New York",
    state: "NY",
    ZIPCode: "10003"
  })
});
const { address, additionalInfo } = await resp.json();
console.log(address.ZIPPlus4);       // "1502"
console.log(additionalInfo.DPVConfirmation); // "Y"

POST/api/rates

Rate shopping across all USPS mail classes

FREE

curl -s "https://api.revaddress.com/api/rates" \
  -H "Content-Type: application/json" \
  -d '{"originZIPCode":"10003","destinationZIPCode":"90210","weight":2.5,"length":12,"width":9,"height":2}'

import requests

resp = requests.post(
    "https://api.revaddress.com/api/rates",
    json={
        "originZIPCode": "10003",
        "destinationZIPCode": "90210",
        "weight": 2.5,
        "length": 12,
        "width": 9,
        "height": 2
    }
)
data = resp.json()
for opt in data["rates"]["rateOptions"]:
    print(f"{opt['mailClass']}: ${opt['totalBasePrice']:.2f} (zone {opt['zone']})")

const resp = await fetch("https://api.revaddress.com/api/rates", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    originZIPCode: "10003",
    destinationZIPCode: "90210",
    weight: 2.5,
    length: 12, width: 9, height: 2
  })
});
const { rates, serviceStandards } = await resp.json();
for (const opt of rates.rateOptions) {
  console.log(`${opt.mailClass}: $${opt.totalBasePrice}`);
}

POST/api/batch/validate

Up to 50 addresses in one request

Growth+

curl -s "https://api.revaddress.com/api/batch/validate" \
  -H "X-API-Key: rv_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"addresses":[{"streetAddress":"228 Park Ave S","city":"New York","state":"NY","ZIPCode":"10003"},{"streetAddress":"1600 Pennsylvania Ave NW","city":"Washington","state":"DC","ZIPCode":"20500"}]}'

import requests

addresses = [
    {"streetAddress": "228 Park Ave S", "city": "New York", "state": "NY", "ZIPCode": "10003"},
    {"streetAddress": "1600 Pennsylvania Ave NW", "city": "Washington", "state": "DC", "ZIPCode": "20500"},
]

resp = requests.post(
    "https://api.revaddress.com/api/batch/validate",
    headers={"X-API-Key": "rv_live_your_key_here"},
    json={"addresses": addresses}
)
data = resp.json()
print(f"Validated: {data['successful']}/{data['total']}")
print(f"Cache hits: {data['usage']['cached_hits']}")

const resp = await fetch("https://api.revaddress.com/api/batch/validate", {
  method: "POST",
  headers: {
    "X-API-Key": "rv_live_your_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    addresses: [
      { streetAddress: "228 Park Ave S", city: "New York", state: "NY", ZIPCode: "10003" },
      { streetAddress: "1600 Pennsylvania Ave NW", city: "Washington", state: "DC" }
    ]
  })
});
const { total, successful, results, usage } = await resp.json();
console.log(`Validated ${successful}/${total}, ${usage.cached_hits} from cache`);

GET/api/tracking/:number

Tracking status with normalized categories when USPS provides events

Starter+

curl -s "https://api.revaddress.com/api/tracking/9400111899223456789012" \
  -H "X-API-Key: rv_live_your_key_here"

import requests

resp = requests.get(
    "https://api.revaddress.com/api/tracking/9400111899223456789012",
    headers={"X-API-Key": "rv_live_your_key_here"}
)
data = resp.json()
print(data["statusCategory"])  # "Pre-Shipment"
for event in data["trackingEvents"]:
    print(event["eventTimestamp"], event["eventType"])

const resp = await fetch(
  "https://api.revaddress.com/api/tracking/9400111899223456789012",
  { headers: { "X-API-Key": "rv_live_your_key_here" } }
);
const { statusCategory, trackingEvents } = await resp.json();
console.log(statusCategory); // "Pre-Shipment"

Addresses

Free Tier

US address validation and ZIP lookup. Census standardization + geocode free — no API key, no license. DPV and city/state run on your USPS license (BYOK).

Validate and standardize a US address using USPS CASS-certified data. Returns ZIP+4, DPV confirmation, residential/business classification, and vacancy status. Results are cached in KV for 24 hours.

Parameters

Name	In	Required	Example
`streetAddress`	query	required	228 Park Ave S PMB 101842
`secondaryAddress`	query	optional	Suite 100
`city`	query	optional	New York
`state`	query	optional	NY
`ZIPCode`	query	optional	10003

Response

{
  "address": {
    "streetAddress": "228 PARK AVE S PMB 101842",
    "city": "NEW YORK",
    "state": "NY",
    "ZIPCode": "10003",
    "ZIPPlus4": "1502"
  },
  "additionalInfo": {
    "deliveryPoint": "42",
    "DPVConfirmation": "Y",
    "business": "Y",
    "vacant": "N"
  },
  "matches": [{ "code": "31", "text": "Single Response - exact match" }],
  "cached": false,
  "resolution": {
    "classification": "deliverable_exact",
    "nextAction": "done",
    "userMessage": "USPS confirmed this address."
  }
}

Same validation but accepts the address as a JSON request body. Useful in workflows where building query strings is inconvenient.

Request Body

{
  "streetAddress": "1600 Pennsylvania Ave NW",
  "city": "Washington",
  "state": "DC",
  "ZIPCode": "20500"
}

Response

{
  "address": {
    "streetAddress": "1600 PENNSYLVANIA AVE NW",
    "city": "WASHINGTON",
    "state": "DC",
    "ZIPCode": "20500",
    "ZIPPlus4": "0005"
  },
  "additionalInfo": {
    "DPVConfirmation": "Y",
    "vacant": "N",
    "deliveryPoint": "00",
    "business": "Y"
  },
  "cached": false,
  "resolution": {
    "classification": "deliverable_exact",
    "nextAction": "done",
    "userMessage": "USPS confirmed this address."
  }
}

Name	In	Required	Example
`ZIPCode`	query	required	10003

Validate up to 50 addresses in a single request. Individual failures never kill the batch (Promise.allSettled). Cached addresses are free — only fresh USPS lookups count toward your quota. Requires Growth tier or above.

Request Body

{
  "addresses": [
    {
      "streetAddress": "228 Park Ave S",
      "city": "New York",
      "state": "NY",
      "ZIPCode": "10003"
    },
    {
      "streetAddress": "1600 Pennsylvania Ave NW",
      "city": "Washington",
      "state": "DC",
      "ZIPCode": "20500"
    }
  ]
}

Response

{
  "total": 2,
  "successful": 2,
  "failed": 0,
  "results": [
    {
      "index": 0,
      "status": "success",
      "address": { "streetAddress": "228 PARK AVE S PMB 101842", "city": "NEW YORK", "state": "NY", "ZIPCode": "10003", "ZIPPlus4": "1502" },
      "additionalInfo": { "DPVConfirmation": "Y", "business": "Y", "vacant": "N" },
      "cached": true
    },
    {
      "index": 1,
      "status": "success",
      "address": { "streetAddress": "1600 PENNSYLVANIA AVE NW", "city": "WASHINGTON", "state": "DC", "ZIPCode": "20500", "ZIPPlus4": "0005" },
      "additionalInfo": { "DPVConfirmation": "Y", "business": "Y", "vacant": "N" },
      "cached": false
    }
  ],
  "usage": { "cached_hits": 1, "fresh_lookups": 1 }
}

Rates

Free Tier

Domestic and international shipping rate quotes. Free tier — runs on your USPS license (BYOK).

Returns USPS rate quotes for all domestic mail classes. Enriched with delivery time estimates from the Service Standards API. Dimensions default to 6×4×1 if not provided.

Request Body

{
  "originZIPCode": "10003",
  "destinationZIPCode": "90210",
  "weight": 2.5,
  "length": 12,
  "width": 9,
  "height": 2
}

Response

{
  "rates": {
    "rateOptions": [
      { "mailClass": "PRIORITY_MAIL", "totalBasePrice": 8.55, "zone": "5" },
      { "mailClass": "USPS_GROUND_ADVANTAGE", "totalBasePrice": 5.25, "zone": "5" },
      { "mailClass": "PRIORITY_MAIL_EXPRESS", "totalBasePrice": 26.60, "zone": "5" }
    ]
  },
  "serviceStandards": {
    "estimates": [
      { "mailClass": "PRIORITY_MAIL", "days": 2 },
      { "mailClass": "USPS_GROUND_ADVANTAGE", "days": 5 }
    ]
  },
  "input": { "origin": "10003", "destination": "90210", "weight": 2.5 }
}

Returns USPS rate quotes for international shipments. Supply a 2-letter ISO 3166-1 alpha-2 destination country code.

Request Body

{
  "destinationCountryCode": "CA",
  "originZIPCode": "10003",
  "weight": 2.5
}

Response

{
  "rates": {
    "rateOptions": [
      { "mailClass": "PRIORITY_MAIL_INTERNATIONAL", "totalBasePrice": 49.50 },
      { "mailClass": "PRIORITY_MAIL_EXPRESS_INTERNATIONAL", "totalBasePrice": 89.75 },
      { "mailClass": "FIRST-CLASS_PACKAGE_INTERNATIONAL_SERVICE", "totalBasePrice": 15.25 }
    ]
  },
  "input": { "origin": "10003", "destination": "CA", "weight": 2.5 }
}

Tracking

USPS tracking route access with normalized status data. API key required; broader public claim strength still waits on deeper scan-backed proof.

Returns tracking status plus any normalized USPS events currently available from USPS Tracking v3.2. Events are stored in D1 for analytics and operator review. expand=SUMMARY returns status only; DETAIL (default) includes richer event data when USPS provides it.

Parameters

Name	In	Required	Example
`trackingNumber`	path	required	9400111899223456789012
`expand` SUMMARY or DETAIL (default)	query	optional	DETAIL

Response

{
  "trackingNumber": "9400111899223456789012",
  "statusCategory": "Pre-Shipment",
  "statusSummary": "Shipping Label Created, USPS Awaiting Item",
  "expectedDeliveryDate": null,
  "trackingEvents": [
    {
      "eventType": "Shipping Label Created, USPS Awaiting Item",
      "eventCode": "GX",
      "eventCity": "NEW YORK",
      "eventState": "NY",
      "eventZIP": "10003",
      "eventTimestamp": "2026-03-17T03:26:34Z"
    }
  ]
}

Labels

Managed label workflows with download and void support for protected accounts.

Creates a USPS shipping label. In workflow mode (default), returns a workflowId — send POST /api/workflows/{id}/approve to authorize the charge. In direct mode, creates the label synchronously and returns the PDF URL. Supports idempotencyKey to prevent duplicate charges on retries.

Request Body

{
  "fromAddress": {
    "firstName": "Jane",
    "lastName": "Doe",
    "streetAddress": "228 Park Ave S PMB 101842",
    "city": "New York",
    "state": "NY",
    "ZIPCode": "10003"
  },
  "toAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "streetAddress": "1600 Pennsylvania Ave NW",
    "city": "Washington",
    "state": "DC",
    "ZIPCode": "20500"
  },
  "mailClass": "PRIORITY_MAIL",
  "weight": 2.5,
  "length": 12,
  "width": 9,
  "height": 2,
  "idempotencyKey": "order-12345-label-1"
}

Response

// Workflow mode — 202 Accepted
{
  "workflowId": "wf_abc123def456",
  "status": "pending_approval",
  "message": "Workflow created. Send POST /api/workflows/{id}/approve to authorize charge."
}

// Direct mode — 201 Created
{
  "labelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trackingNumber": "9400111899223456789012",
  "postage": 8.55,
  "zone": "5",
  "commitment": { "name": "2 Days", "scheduleDeliveryDate": "2026-03-12" },
  "labelUrl": "/api/labels/a1b2c3d4-e5f6-7890-abcd-ef1234567890/download",
  "environment": "production"
}

Returns your most recent labels. Scoped to your merchant ID. Use ?limit=N to control page size (1–100, default 20).

Parameters

Name	In	Required	Example
`limit` 1–100, default 20	query	optional	20

Response

{
  "labels": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "tracking_number": "9400111899223456789012",
      "mail_class": "PRIORITY_MAIL",
      "postage": 8.55,
      "status": "delivered",
      "commitment": "2 Days",
      "created_at": 1741234567890
    }
  ]
}

Returns the label PDF from R2 storage. Response is application/pdf with Content-Disposition: attachment. Labels are scoped to your merchant ID.

Parameters

Name	In	Required	Example
`labelId`	path	required	a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response

// Returns binary PDF — application/pdf

Voids a label and requests a USPS postage refund. Cannot void delivered or already-voided labels. USPS void request is fire-and-forget — the D1 record is always updated regardless of USPS response.

Parameters

Name	In	Required	Example
`labelId`	path	required	a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response

{
  "labelId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "trackingNumber": "9400111899223456789012",
  "status": "voided",
  "refundAmount": 8.55,
  "voidedAt": "2026-03-10T12:00:00.000Z"
}

Workflows

Durable label creation workflows with explicit charge approval and status polling.

Returns current Cloudflare Workflow status and step progress for a label creation workflow.

Parameters

Name	In	Required	Example
`workflowId`	path	required	wf_abc123def456

Response

{
  "workflowId": "wf_abc123def456",
  "status": "running",
  "output": null
}

Sends the charge-approved event to an awaiting label workflow. Unblocks step 3 (waitForEvent) and allows label creation to proceed.

Parameters

Name	In	Required	Example
`workflowId`	path	required	wf_abc123def456

Request Body

{ "approved": true }

Response

{
  "workflowId": "wf_abc123def456",
  "event": "charge-approved",
  "payload": { "approved": true }
}

Pickup

Pickup availability and scheduling routes for protected accounts. Request access; rolling out account by account.

Check whether the pickup surface is enabled for a given address and account setup. Requires streetAddress, city, state, and ZIPCode in the request body.

Request Body

{
  "streetAddress": "228 Park Ave S",
  "city": "New York",
  "state": "NY",
  "ZIPCode": "10003"
}

Response

{
  "pickupAvailability": {
    "available": true,
    "nextPickupDate": "2026-03-11"
  }
}

Request a USPS pickup where pickup access is enabled for your account and a prepared, prepaid package is ready for carrier handoff. See USPS Carrier Pickup v3 documentation for the full request body schema.

Request Body

{
  "streetAddress": "228 Park Ave S",
  "city": "New York",
  "state": "NY",
  "ZIPCode": "10003",
  "pickupDate": "2026-03-11",
  "packageCount": 2,
  "estimatedWeight": 5
}

Response

{
  "confirmationNumber": "WTC123456789",
  "pickupDate": "2026-03-11"
}

Locations & Standards

Free Tier

USPS drop-off locations and delivery time standards. Free tier — runs on your USPS license (BYOK).

Find USPS Post Offices, collection boxes, and retail locations near a ZIP code. Results cached for 24 hours.

Parameters

Name	In	Required	Example
`destinationZIPCode`	query	required	10003
`mailClass` Default: PARCEL_SELECT	query	optional	PARCEL_SELECT
`originZIPCode`	query	optional	10001
`weight`	query	optional	2.5

Response

{
  "dropOffLocations": [
    {
      "locationName": "JAMES A. FARLEY BLDG",
      "streetAddress": "421 8TH AVE",
      "city": "NEW YORK",
      "state": "NY",
      "zipCode": "10001",
      "locationType": "POST_OFFICE"
    }
  ],
  "cached": false
}

Returns USPS delivery time estimates between two ZIP codes by mail class. Results cached for 24 hours (standards change quarterly).

Parameters

Name	In	Required	Example
`originZIPCode`	query	required	10003
`destinationZIPCode`	query	required	90210
`mailClass`	query	optional	PRIORITY_MAIL

Response

{
  "estimates": [
    { "mailClass": "PRIORITY_MAIL", "days": 2, "scheduleDeliveryDate": "2026-03-12" },
    { "mailClass": "USPS_GROUND_ADVANTAGE", "days": 5, "scheduleDeliveryDate": "2026-03-15" }
  ],
  "cached": false
}

Returns available USPS shipping products for a given origin/destination pair.

Parameters

Name	In	Required	Example
`originZIPCode`	query	required	10003
`destinationZIPCode`	query	required	90210
`mailClass`	query	optional	PRIORITY_MAIL
`weight`	query	optional	1
`priceType`	query	optional	RETAIL

Response

{
  "shipmentOptions": [
    {
      "mailClass": "PRIORITY_MAIL",
      "serviceId": "PM",
      "commitment": "2 Days",
      "priceType": "RETAIL"
    }
  ]
}

Admin Diagnostics

Admin-only diagnostics for protected operator use.

Returns current OAuth and payment token validity plus the latest payment-auth attempt metadata, including upstream status, message, failure class, and blocked reason.

Response

{
  "environment": "production",
  "oauth": { "valid": true, "ttl_seconds": 25120 },
  "payment": {
    "valid": true,
    "ttl_seconds": 23980,
    "lastAttemptAt": "2026-03-15T15:24:11.112Z",
    "lastUpstreamStatus": 200,
    "lastUpstreamMessage": "Payment authorization token obtained",
    "failureClass": null,
    "blockedReason": null
  }
}

Clears cached OAuth and payment tokens for the selected USPS environment (`prod` by default, `tem` optional) and returns the post-clear token snapshot.

Parameters

Name	In	Required	Example
`env` prod (default) or tem	query	optional	prod

Response

{
  "environment": "production",
  "cleared": true,
  "oauth": { "valid": false, "ttl_seconds": 0 },
  "payment": {
    "valid": false,
    "ttl_seconds": 0,
    "failureClass": null
  }
}

Refreshes OAuth and payment tokens and returns structured success/failure metadata instead of a single coarse result.

Response

{
  "oauth": { "success": true, "ttl_seconds": 25200 },
  "payment": {
    "success": true,
    "ttl_seconds": 24000,
    "lastUpstreamStatus": 200,
    "lastUpstreamMessage": "Payment authorization token obtained",
    "failureClass": null,
    "blockedReason": null
  }
}

Attempts payment authorization without buying postage. Internal operator diagnostic only.

Response

{
  "success": true,
  "message": "Payment authorization token obtained",
  "failureClass": null,
  "blockedReason": null
}

BYOK

Bring your own USPS Developer Portal credentials and every USPS call from your keys — DPV, rates, service standards, shipping options, city/state, tracking, pickups, international prices — runs on your license through our infrastructure. Any API key can connect, Free included (guided form: /dashboard/#byok). AES-GCM encrypted at rest; per-merchant token manager handles OAuth refresh, retries, caching.

Store and encrypt your USPS Developer Portal credentials (client_id + client_secret; crid / master_mid / label_mid / epa_account optional, labels & payments only). Encrypted with AES-GCM using an HKDF-derived per-merchant key. Each BYOK merchant gets an isolated Durable Object for token management. Immediately attempts OAuth verification — returns verified (201) or pending_verification (200). Once verified, every USPS endpoint called with your key runs on your license.

Request Body

{
  "client_id": "your-usps-consumer-key",
  "client_secret": "your-usps-consumer-secret",
  "crid": "12345678",
  "master_mid": "900000001",
  "label_mid": "900000002",
  "epa_account": "1000000001"
}

Response

// Verified (201)
{
  "merchant_id": "stripe_cus_abc123",
  "status": "verified",
  "has_payment_fields": true,
  "verification": { "success": true, "message": "OAuth token obtained successfully" },
  "message": "Credentials verified — your USPS tokens are now managed separately."
}

// Stored but not verified (200)
{
  "merchant_id": "stripe_cus_abc123",
  "status": "pending_verification",
  "verification": { "success": false, "error": "token_exchange_failed" },
  "message": "Credentials stored but verification failed. Check your USPS client_id/secret."
}

Returns BYOK credential status and live token health for the authenticated merchant.

Response

{
  "merchant_id": "stripe_cus_abc123",
  "byok_enabled": true,
  "status": "verified",
  "has_payment_fields": true,
  "last_verified_at": "2026-03-09 17:00:00",
  "tokens": {
    "oauth": { "valid": true, "ttl_seconds": 25200 },
    "payment": { "valid": true, "ttl_seconds": 24000 }
  }
}

Attempt OAuth token exchange with stored credentials. Updates status and last_verified_at.

Response

{
  "merchant_id": "stripe_cus_abc123",
  "status": "verified",
  "last_verified_at": "2026-03-10 08:00:00"
}

Account

Self-service usage and key management. Scoped to your API key.

Returns API call breakdown by endpoint for the authenticated merchant. Scoped to your API key. Optionally filter by month (YYYY-MM).

Parameters

Name	In	Required	Example
`month` YYYY-MM format	query	optional	2026-03

Response

{
  "usage": [
    { "merchant_id": "stripe_cus_abc123", "endpoint": "/api/address/validate", "call_count": 892 },
    { "merchant_id": "stripe_cus_abc123", "endpoint": "/api/tracking/:number", "call_count": 231 },
    { "merchant_id": "stripe_cus_abc123", "endpoint": "/api/rates", "call_count": 124 }
  ],
  "filters": { "merchant_id": "stripe_cus_abc123", "month": "2026-03" }
}

Returns all API keys for your merchant account. Key hashes are masked (first 8 + last 4 chars). Use key_hash_full for revocation.

Response

{
  "keys": [
    {
      "key_hash": "a1b2c3d4...ef12",
      "key_hash_full": "a1b2c3d4e5f6...",
      "label": "production",
      "tier": "starter",
      "rate_limit_per_min": 120,
      "created_at": 1741234567890,
      "last_used_at": 1741234599000,
      "revoked_at": null
    }
  ],
  "merchant_id": "stripe_cus_abc123"
}

Revoke an API key that belongs to your merchant account. Only keys that belong to your own merchant ID can be revoked.

Parameters

Name	In	Required	Example
`keyHash`	path	required	a1b2c3d4e5f6...

Response

{ "key_hash": "a1b2c3d4e5f6...", "revoked": true }

Creates a Stripe billing portal session when self-serve billing is configured for the account. Returns a redirect URL for plan, payment-method, and invoice management, or falls back to direct support workflows if self-serve billing is unavailable.

Response

{ "portal_url": "https://billing.stripe.com/session/..." }

Error Reference

All errors return a consistent JSON shape with machine-readable codes.

{
  "error": "usps_auth_failed",
  "message": "OAuth token expired or invalid",
  "status": 401,
  "code": "AUTH_EXPIRED",
  "retryable": true
}

Error Code	HTTP Status	Retryable	Action
api_key_required	401	—	Add X-API-Key header
invalid_api_key	401	—	Check that you're using the right live or free-evaluation key for this environment
api_key_revoked	401	—	Generate a new key
rate_limit_exceeded	429	Yes	Check retryAfter in response, back off
monthly_limit_exceeded	429	Next month	Upgrade plan at /pricing
free_tier_rate_limit	429	Yes	Slow down or get a free API key
tier_required	403	—	Upgrade plan (batch requires Growth+)
usps_validation_error	422	No	Fix input address data
usps_auth_failed	401	Yes	Token auto-refreshes — retry once
payment_token_unavailable	503	Yes	Retry after a few seconds
batch_too_large	400	No	Split into batches of ≤50
credits_exhausted	402	After top-up	Buy credits — the response carries required, balance and a top-up link

Prepaid credits

Credits are pay-as-you-go: no subscription, no invoice, no minimum. One credit is $0.001, and each endpoint debits by what its data is worth — a standardized address costs 1, a full area-intelligence report costs 15. The live table lives at GET /api/credits/pricing, which is the same map the meter charges from, so it can never quote a price you aren't billed.

Order of spend

1Your plan's monthly allowance, if you're on one. A subscriber under their cap never burns a credit.
2Credits, once the allowance is gone — or from the first call if you hold no subscription.
3Nothing. At zero the call returns 402 credits_exhausted before any work runs, so an exhausted balance costs you a millisecond, not a partial result.

Reading your balance

# Every metered response carries the balance in headers
X-Credits-Charged: 15
X-Credits-Remaining: 48210

# Full balance, expiry and burn
curl -s https://api.revaddress.com/api/my/credits \
  -H "X-API-Key: rv_live_..."

# Buy a block (returns a Stripe Checkout URL)
curl -s -X POST https://api.revaddress.com/api/my/credits/checkout \
  -H "X-API-Key: rv_live_..." \
  -H "Content-Type: application/json" \
  -d '{"block":"block_200"}'

Free on signup

1,000 credits, good for 30 days. Enough to finish an integration before you decide anything.

Expiry

Credits you paid for last 12 months. Bonus credits last 90 days and are always spent first, so a gift expiring can never cost you a dollar you paid.

Bring your own USPS license

BYOK merchants are never charged the USPS-verified surcharge — that fee lands on your own USPS invoice, not ours.

SDKs

Pythonv1.0.0

pip install usps-v3

PyPI GitHub Tutorial

Node.jsv1.0.0

npm install usps-v3

npm GitHub Tutorial

PHPv1.0.0

composer require revaddress/usps-v3-php

Packagist GitHub Magento Guide