Packy Tracking API (1.0.0)

1 credit = 1 unique tracking number.

Once you add a tracking number, that single credit covers the package's normal tracking lifecycle. This includes everything from the moment it's created, through transit, final delivery, potential returns (if things don't go as planned), and even a little extra buffer time afterward—just to ensure you have all the data you need.

Optional API operations can have their own price. In particular, every successful forced refresh (POST /v1/trackings/{tracking_number}/refresh) is charged separately at the current price of the tracking.refresh operation, even when the carrier reports no new events.

Every parcel in the system is assigned a status that reflects the latest stage of its journey. As new tracking events arrive, the status is updated automatically. The possible statuses are:

Note: When a parcel has several events at once, the most significant status is shown (for example, Delivered takes precedence over In Transit).

The same API is also exposed as an MCP (Model Context Protocol) server, so you can connect directly to a model or agent instead of writing HTTP calls yourself. The model acts on behalf of your account with exactly the rights of the regular Tracking API, and MCP is not billed separately — calls consume the same plan credits as the equivalent HTTP requests.

Two ways to authenticate

For the API-key method, authenticate every request with Authorization: Bearer <your-api-key>. The X-API-Key: <your-api-key> header is accepted as a fallback.

Every account has its own key. Do not share it in group chats or shared documents — if it leaks, deactivate it in the dashboard and issue a new one.

Cursor (API key)

Config file: project or user MCP settings (mcp.json).

{
  "mcpServers": {
    "packyapp-tracking-mcp": {
      "url": "https://mcp.parceltracking.app/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Replace <your-api-key> with your account API key, then:

1. Save mcp.json.
2. Restart MCP / the agent the way Cursor requires.
3. Confirm the Packy tool list appears in the client.

Claude Desktop (API key)

Config file:

{
  "mcpServers": {
    "packyapp-tracking-mcp": {
      "url": "https://mcp.parceltracking.app/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Replace <your-api-key> the same way as above, then:

1. Save claude_desktop_config.json.
2. Fully quit and reopen Claude Desktop.
3. Confirm the Packy channel tools are available.

Claude Custom connector (OAuth)

Prepare first, in the dashboard — not from the model client:

1. Sign in to (or create) your account at https://lk.parceltracking.app.
2. Create an API key and make sure it is active.
3. Check that the key belongs to the account and plan you want the model to work under.

The OAuth connection runs under the key you pick: the model's calls and credits are attributed to it, it keeps working while that key is active, and it stops as soon as you deactivate the key. Without an account and at least one active key the browser sign-in can succeed while the model still ends up with no working tools.

Then connect:

1. In Claude, add a Custom connector / MCP server with the URL https://mcp.parceltracking.app/mcp.
2. Start the connection — Packy sign-in opens in the browser.
3. Sign in to the dashboard. A short Continue authorization page then redirects you onward automatically; there is nothing to click. That link is single-use and expires after 2 minutes, so if the flow breaks, restart it from Claude instead of reopening the previous URL.
4. On the Allow access? consent screen, choose the API key this connection will run under and press Allow. If the account has no active key, the screen says so and you cannot continue — go back to the preparation steps above.
5. Return to Claude and confirm the status is Connected and the Packy tools are listed.

Access tokens are short-lived and refreshed automatically, so you do not need to reconnect periodically.

Available tools

The channel covers the core /v1 resources:

Credits are consumed exactly as they are over HTTP: a trackings_create call from the model costs the same credit as POST /v1/trackings, and a batch create spends one credit per tracking number in the batch. It is the only billable tool — the courier and webhook tools cost nothing, so the only calls worth running deliberately are creates.

Check that it works

Disconnect access

API-key connections. Deactivate or rotate the account API key in the dashboard, then remove or update the packyapp-tracking-mcp entry in the client config. Once the key is deactivated, the previous model connection stops working.

OAuth connections. Open Connected applications in the dashboard and revoke the application's access, then remove the connector in Claude. Deactivating the API key the connection runs under also stops it immediately.

Troubleshooting

Create, list, retrieve, refresh, and delete shipment trackings.

List supported couriers and detect a courier by tracking number.

Manage webhook subscriptions for delivery updates, and the contract for the deliveries we send to your endpoint.

When a tracking you are subscribed to receives an update, we send an HTTP POST to every enabled subscription whose account owns that tracking. The request body is the tracking payload, forwarded verbatim — the same JSON, byte-for-byte, that GET /v1/trackings/{id} returns for the parcel. No wrapper object and no event field are added, so you must sign/verify against the raw request body (see below).

{
  "trackcode": "RA123456789CN",
  "status": "delivered",
  "origin_country": "CN",
  "destination_country": "UA",
  "events": [],
  "source": [
    {
      "code": "ukrposhta",
      "name": "Ukrposhta",
      "track": "RA123456789CN",
      "external_link": "https://track.ukrposhta.ua/tracking_RA123456789CN"
    }
  ]
}

Headers

Signature verification

Compute the expected signature over the raw request body (before any deserialization, since the body is re-sent byte-for-byte) and compare in constant time:

expected = "sha256=" + hex(HMAC_SHA256(secret, raw_request_body))
compare(expected, X-Webhook-Signature)   // constant-time

Delivery, retries & idempotency

Any 2xx response is treated as a successful delivery. Any other status code, or a network/timeout error, triggers a retry. Because X-Webhook-Id is stable across retries, treat deliveries as at-least-once and deduplicate on that id.