Send tracking scans

​

Records the mail and carrier scans of shipments whose labels your application printed. Only available to applications CardNexus has granted the tracking privilege; any other application gets 403 FORBIDDEN.

Call it with your application credential and no CardNexus-Account header. Each shipment is matched by tracking number to the sales of sellers who connected your application with the sales:write scope. A tracking number that matches no sale yet returns matchedSales: 0; send the shipment again with its next scan and the earlier ones are recorded then.

Send every scan you have for a shipment each time. Scans are matched by eventId, so a scan you already sent is counted in duplicates and recorded only once.

A delivered scan marks the sale delivered, for parcels and letters alike.

Scans appear in shipping.history with source: "application".

Body

required
application/json
  • shipments
    Type: array of object 1…100
    required

    Up to 100 shipments per request.

    Properties: 3

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/tracking/events
curl https://public-api.cardnexus.com/v1/tracking/events \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "shipments": [
    {
      "trackingNumber": "00310110084032371774",
      "trackingUrl": "https://track.sortswift.example/l/00310110084032371774",
      "events": [
        {
          "eventId": "evt_8811",
          "status": "label_created",
          "occurredAt": "2026-09-21T10:21:00.000Z",
          "location": {
            "city": "Laurel",
            "state": "MD"
          },
          "description": "Label created"
        },
        {
          "eventId": "evt_8812",
          "status": "in_mailstream",
          "occurredAt": "2026-09-22T23:35:00.000Z",
          "location": {
            "city": "Gaithersburg",
            "state": "MD",
            "postalCode": "20898"
          },
          "description": "Origin processing"
        }
      ]
    }
  ]
}'

{
  "shipments": [
    {
      "trackingNumber": "00310110084032371774",
      "matchedSales": 1,
      "accepted": 1,
      "duplicates": 1
    },
    {
      "trackingNumber": "0004020819211531082732720802647",
      "matchedSales": 0,
      "accepted": 0,
      "duplicates": 0
    }
  ]
}

Scans processed.