Record a purchase's shipment and its delivery

POST/v1/purchases/{id}/tracking

Adds the tracker to the PayPal order (Orders v2) and, once delivered, records the delivery with PayPal's Add Tracking API. Idempotent per tracking number.

Path parameters

idstringRequired

Headers

Content-Typeapplication/jsonRequired
idempotency-keystringRequired
Idempotency-KeystringRequired: 1 to 255 characters. A retry with the same key returns the first answer.

Request body

application/json

carrierstringRequired: PayPal's carrier code.
tracking_numberstringRequired
deliveredboolean: The carrier confirmed delivery; it becomes the dispute's delivery proof.

Responses

200Recorded
404No such purchase
409The purchase was not captured
422PayPal refused
503PayPal unavailable

200 response

statestringRequired
tracker_idstringRequired

curl -X POST https://api.keelson.finance/v1/purchases/{id}/tracking \
  -H 'content-type: application/json' \
  -H 'idempotency-key: <idempotency-key>' \
  -H "idempotency-key: $(uuidgen)" \
  --data '{"carrier":"USPS","tracking_number":"string","delivered":true}'

const res = await fetch("https://api.keelson.finance/v1/purchases/{id}/tracking", {
  method: "POST",
  headers: {
    "content-type": "application/json",
    "idempotency-key": "<idempotency-key>",
    "idempotency-key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    "carrier": "USPS",
    "tracking_number": "string",
    "delivered": true
  }),
});
const data = await res.json();

Response · shape from the schema

{
  "state": "string",
  "tracker_id": "string"
}