Nitromule

API quickstart — rates and labels

Updated 2026-09-07

On this page

This quickstart walks rate-only shopping and the OMS path (create order, then ship). Use a nm_test_ key until the flow works. Exact JSON field names always follow OpenAPI.

Prerequisites

  • Plan with API access
  • API key from Settings → API (nm_test_… recommended)
  • Billing payment method if you will buy platform (non-BYOA) postage
  • curl (and optionally jq)
export NM_API_KEY="nm_test_xxxxxxxx"
export NM_API="https://nitromule.com/api/integrations/v1"

1. Smoke: list carriers

curl -sS "$NM_API/carriers" \
 -H "Authorization: Bearer $NM_API_KEY" \
 -H "Accept: application/json"

2. Validate an address

curl -sS "$NM_API/addresses/validate" \
 -H "Authorization: Bearer $NM_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "address": {
 "name": "Jamie Receiver",
 "street1": "1 Market St",
 "city": "San Francisco",
 "state": "CA",
 "zip": "94105",
 "country": "US"
 }
 }'

Use normalized fields from the response when corrections are returned.

3. Rate-only shop (no purchase)

POST /rates returns UPS / USPS / FedEx offers. Keep ship-from, ship-to, weight, and dimensions populated per OpenAPI.

curl -sS "$NM_API/rates" \
 -H "Authorization: Bearer $NM_API_KEY" \
 -H "Content-Type: application/json" \
 -d @rate-request.json

Pick identifiers from the response for the buy step.

4. OMS path: create an order, then buy

Create order (illustrative — copy required fields from OpenAPI):

curl -sS "$NM_API/orders" \
 -H "Authorization: Bearer $NM_API_KEY" \
 -H "Content-Type: application/json" \
 -H "Idempotency-Key: order-$(date +%s)" \
 -d @create-order.json

Place Order for that order:

curl -sS "$NM_API/shipments" \
 -H "Authorization: Bearer $NM_API_KEY" \
 -H "Content-Type: application/json" \
 -H "Idempotency-Key: ship-$(date +%s)" \
 -d '{
 "order_id": "ORDER_ID_FROM_CREATE"
 }'
Note

Platform postage charges the merchant Billing card; BYOA / $0 paths skip Nitromule postage charge. Expect 402 if payment is required and missing. Client-only nm-paid style headers do not unlock platform postage.

5. Persist label + tracking

Store order_id, tracking number, and label URL from the shipment response in your OMS.

6. Void if unused

curl -sS -X POST "$NM_API/shipments/ORDER_ID/void" \
 -H "Authorization: Bearer $NM_API_KEY"

7. Track

curl -sS "$NM_API/tracking" \
 -H "Authorization: Bearer $NM_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{ "order_id": "ORDER_ID" }'

8. Webhooks

Register for shipment.created, shipment.voided, and tracking.updated — Webhooks.

Idempotency

Send Idempotency-Key on creates and purchases. Replaying the same key should not double-buy postage.

Next

Authentication · OpenAPI · MCP · Test mode

Related articles