Announce a package

Tells us a package of your cards is on its way. Send the carrier tracking number as soon as the label exists, and the site — the warehouse the label is addressed to (list them with GET /sites). Each warehouse works only its own incoming list, so a package with the wrong site is not expected where it lands; it is still received there, and received_site then differs from destination_site. When the box reaches the warehouse, the receiving operator scans its label and the shipment moves to RECEIVED. Read that back with GET /inbound-shipments/:id, or wait for the inbound_shipment.received event on your activity log. Received means the box is on our floor, not that its cards are intaken; those still appear one by one in GET /cards as they are scanned, each naming this shipment in its inbound_shipment field (id, tracking_number, carrier, reference), so GET /cards?inbound_shipment_id=<id> lists exactly the cards that came out of this box. If the cards are for one of your sub-accounts, say so with sub_account (a slug from GET /sub-accounts): the receiving bench sees it and files the intake under it, and the shipment shows up under GET /inbound-shipments?sub_account=. Anything else you want on the box goes in metadata, a JSON object of your own that we store and show back; documents — the packing list, the invoice, a manifest, photos — go on as attachments once the shipment exists (POST /inbound-shipments/:id/attachments). Announcing the same box twice is safe. If you already have a live announcement for this tracking number, or we received a box with it in the last 120 days, you get that shipment back with 200 and created: false instead of a duplicate. Re-announcing a box we already have is therefore a quick way to learn it arrived. Everything but the tracking number and the site can be changed with PATCH /inbound-shipments/:id while the package is EXPECTED; to change where a box is going, cancel it and announce it again with the right site. We match on letters and digits only (spaces, dashes and case are ignored), and a USPS or FedEx label barcode matches even though it carries extra digits around the tracking number. Send exactly the number the carrier gave you.

{
  "tracking_number": "9400111899223197428490",
  "site": "oregon-1",
  "carrier": "usps",
  "card_count": 120,
  "reference": "PO-1001",
  "metadata": {
    "po": "PO-1001",
    "contact": "ops@example.com"
  },
  "idempotency_key": "docs-inbound-9400111899223197428490"
}

curl -X POST 'https://service.rip.fun/api/v1/inbound-shipments' \
  -H 'X-API-Key: rip_…' \
  -H 'Content-Type: application/json' \
  -d '{"tracking_number":"9400111899223197428490","site":"oregon-1","carrier":"usps","card_count":120,"reference":"PO-1001","metadata":{"po":"PO-1001","contact":"ops@example.com"},"idempotency_key":"docs-inbound-9400111899223197428490"}'

Request fields

Response fields (data)

Errors

See Errors for the response envelope and the full code list.