Tracking (v1)

Returns the full, vendor-agnostic scan history for a tracked item. This endpoint is the system of record for tracking events across every shipping vendor (USPS First Class, presort vendors, and future carriers) — the response shape is identical regardless of which carrier produced the scans.

Unlike the legacy Payment Tracking endpoint (which is hard-wired to payments and reflects a single carrier's passthrough), this endpoint is entity-agnostic: pass the kind of item you want to track with the entity_type parameter.

Tracking is keyed to the physical mailpiece, so when one piece fulfils several items (for example, every payment in a bundle), each item returns the same single, de-duplicated event timeline.

You may request a single item or up to 1,000 items at once by passing an array of IDs, and narrow the result set by status. You can also omit id entirely to page through every tracking record you own for that entity_type (returned newest tracking first). Results are paginated (up to 1,000 per page). Access is scoped to your OAuth credentials: you can only retrieve tracking for items owned by your account — IDs outside your scope are silently omitted from the response.

Parameters
Parameter Type Required Default Description
entity_type String No payment The kind of item to track. Supported values: payment, document, payment_bundle. A payment_bundle is yours when it contains at least one payment owned by your account.
id Int | Int[] No N/A One item ID or an array of item IDs (e.g. payment, document, or bundle IDs) found in your Checkissuing dashboard or returned by other API calls. Omit this parameter to return every tracking record you own for the given entity_type (paginated, newest tracking first). When supplied, a maximum of 1,000 IDs may be requested per call; requesting more returns an error.
tracking_status String | String[] No N/A Optional filter. One status or an array of statuses; only items whose current status matches are returned. Each value must be one of pending, in_transit, out_for_delivery, delivered, exception, cancelled, unknown. An invalid value returns an error.
per_page Int No 1000 Number of items per page, between 1 and 1,000. Values above 1,000 are clamped to 1,000.
page Int No 1 1-based page number to retrieve.
Response Fields
Field Description
status 1 on success, 0 when errors are present.
errors Array of error strings (empty on success).
error_message The error strings joined into a single message (empty on success).
entity_type Echo of the requested entity type.
pagination Page metadata: page, per_page, total (total matching items across all pages), and total_pages.
tracking[] An array of tracked items (one entry per matching, owned item with tracking). Each entry carries its own id plus the fields below.
tracking[].id The item ID this tracking entry belongs to.
tracking[].tracking_number The carrier tracking number / barcode (e.g. the IMb for USPS First Class). May be null.
tracking[].tracking_carrier Carrier code (e.g. USPS).
tracking[].tracking_status Current status: pending, in_transit, out_for_delivery, delivered, exception, cancelled, unknown.
tracking[].events[] Chronological scan timeline (oldest first). Each event includes event_phase, event_label, occurred_at, location, facility_code, vendor, raw_event_code, stop_the_clock, source, confidence (confirmed or unconfirmed), and anticipated_delivery_date / estimated_delivery_date.
Sample Response
{
  "status": 1,
  "errors": [],
  "error_message": "",
  "entity_type": "payment",
  "pagination": {
    "page": 1,
    "per_page": 1000,
    "total": 1,
    "total_pages": 1
  },
  "tracking": [
    {
      "id": 12345,
      "tracking_number": "0027012345678901234500000000000",
      "tracking_carrier": "USPS",
      "tracking_status": "in_transit",
      "tracking_status_updated_at": "2026-06-10T11:16:36-04:00",
      "events": [
        {
          "event_phase": "handoff",
          "event_label": "Accepted by USPS",
          "occurred_at": "2026-06-09T10:00:00-04:00",
          "location": "DALLAS, TX",
          "facility_code": "75260",
          "vendor": "usps",
          "raw_event_code": "A09",
          "stop_the_clock": false,
          "source": "usps",
          "confidence": "confirmed",
          "anticipated_delivery_date": null,
          "estimated_delivery_date": "2026-06-12"
        },
        {
          "event_phase": "secondary_sort",
          "event_label": "In transit",
          "occurred_at": "2026-06-10T11:16:36-04:00",
          "location": "WARRENDALE, PA",
          "facility_code": "15086",
          "vendor": "usps",
          "raw_event_code": "L",
          "stop_the_clock": false,
          "source": "usps",
          "confidence": "confirmed",
          "anticipated_delivery_date": "2026-06-10",
          "estimated_delivery_date": "2026-06-12"
        }
      ]
    }
  ]
}
Errors

Validation problems are returned with status: 0 and a populated errors array (and error_message), while tracking is an empty array. Possible errors include:

  • Invalid entity_type — the entity_type is not a supported value.
  • Too many ids — more than 1,000 IDs were supplied in a single call.
  • Invalid tracking_status — one or more tracking_status values are not recognized.

A request with valid parameters but no matching, owned items still returns status: 1 with an empty tracking array and pagination.total: 0. A missing or invalid OAuth token returns HTTP 403 with Access Denied.

Batch Request Example

Request tracking for several payments at once, limited to in-transit and delivered items: 

{
  "entity_type": "payment",
  "id": [12345, 12346, 12347],
  "tracking_status": ["in_transit", "delivered"],
  "per_page": 1000,
  "page": 1
}