Add Tracking API Integration Guide

APICurrentLast updated: December 6th 2023, @ 6:56:51 am

Merchants can use the PayPal Add Tracking API to manage tracking information.

Merchants can add tracking numbers and associated information to PayPal. Merchants can add tracking information with or without tracking numbers.

After adding these details to PayPal, merchants can:

Update or cancel tracking information.
Show tracking details.

1. Set up your development environment

Before you can integrate package tracking, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

2. Add tracking information with tracking numbers

You can add tracking information with or without tracking numbers for up to 20 PayPal transactions.

To add tracking information for multiple transactions, include these parameters in the request body:

Request parameter	Type	Required	Description
`transaction_id`	`string`	Required	The PayPal transaction ID.
`tracking_number`	`string`	Optional	The tracking number for the shipment. To add tracking information without tracking numbers, omit this parameter.
`tracking_number_type`	`enum`	Optional	The type of tracking number. The possible values are: `CARRIER_PROVIDED`. The tracking number is provided by a merchant. `E2E_PARTNER_PROVIDED`. The tracking number is provided by a marketplace.
`status`	`string`	Required	The status of the item shipment. For the supported statuses, see shipping statuses.
`shipment_date`	`string`	Optional	The date when the shipment occurred, in Internet date and time format. Minimum length: 10. Maximum length: 10.
`carrier`	`enum`	Optional	The carrier for the shipment. If your carrier name is not in the list, set `carrier` to `OTHER` and set carrier name in `carrier_name_other` . For the supported carriers, see Carriers.
`carrier_name_other`	`string`	Optional	The name of the carrier for the shipment. Required only if the `carrier` parameter is `OTHER`.
`notify_buyer`	`boolean`	Optional	If `true`, sends an email notification to the buyer of the PayPal transaction. The email contains the tracking information uploaded in the API. Default is `false`.
`last_updated_time`	`string`		The date and time when the tracking information was last updated, in Internet date and time format. Minimum length: 20. Maximum length: 64.

For parameter details, see parameters.

The following request adds tracking information with tracking numbers for multiple PayPal transactions:

curl -v -X POST https://api-m.sandbox.paypal.com/v1/shipping/trackers-batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -d '{
  "trackers": [
    {
      "transaction_id": "8MC585209K746392H",
      "tracking_number": "443844607820",
      "status": "SHIPPED",
      "carrier": "FEDEX"
    },
    {
      "transaction_id": "53Y56775AE587553X",
      "tracking_number": "443844607821",
      "status": "SHIPPED",
      "carrier": "FEDEX"
    }
  ]
}'

A successful request returns the HTTP 200 OK status code and a JSON response body that list tracking information:

{
  "tracker_identifiers": [
    {
      "transaction_id": "8MC585209K746392H",
      "tracking_number": "443844607820",
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com/v1/shipping/trackers/8MC585209K746392H-443844607820",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api-m.sandbox.paypal.com/v1/shipping/trackers/8MC585209K746392H-443844607820",
          "rel": "replace",
          "method": "PUT"
        }
      ]
    },
    {
      "transaction_id": "53Y56775AE587553X",
      "tracking_number": "443844607821",
      "links": [
        {
          "href": "https://api-m.sandbox.paypal.com/v1/shipping/trackers/53Y56775AE587553X-443844607821",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api-m.sandbox.paypal.com/v1/shipping/trackers/53Y56775AE587553X-443844607821",
          "rel": "replace",
          "method": "PUT"
        }
      ]
    }
  ],
  "errors": [
    {
      "name": "RESOURCE_NOT_FOUND",
      "debug_id": "46735c7461f3d",
      "message": "The specified resource does not exist.",
      "details": [
        {
          "field": "/trackers/0/transaction_id",
          "value": "8MC585309K746392H",
          "location": "body",
          "issue": "INVALID_TRANSACTION_ID"
        }
      ]
    }
  ],
  "links": [
    {
      "href": "https://api-m.sandbox.paypal.com/v1/shipping/trackers-batch",
      "rel": "self",
      "method": "POST"
    }
  ]
}

3. Add tracking information without tracking numbers

You can add tracking information with or without tracking numbers for up to 20 PayPal transactions.

To add tracking information for multiple transactions, include these parameters in the request body:

Request parameter	Type	Required	Description
`transaction_id`	`string`	Required	The PayPal transaction ID.
`tracking_number`	`string`	Optional	The tracking number for the shipment. To add tracking information without tracking numbers, omit this parameter.
`tracking_number_type`	`enum`	Optional	The type of tracking number. The possible values are: `CARRIER_PROVIDED`. The tracking number is provided by a merchant. `E2E_PARTNER_PROVIDED`. The tracking number is provided by a marketplace.
`status`	`string`	Required	The status of the item shipment. For the supported statuses, see shipping statuses.
`shipment_date`	`string`	Optional	The date when the shipment occurred, in Internet date and time format. Minimum length: 10. Maximum length: 10.
`carrier`	`enum`	Optional	The carrier for the shipment. If your carrier name is not in the list, set `carrier` to `OTHER` and set carrier name in `carrier_name_other` . For the supported carriers, see Carriers.
`carrier_name_other`	`string`	Optional	The name of the carrier for the shipment. Required only if the `carrier` parameter is `OTHER`.
`notify_buyer`	`boolean`	Optional	If `true`, sends an email notification to the buyer of the PayPal transaction. The email contains the tracking information uploaded in the API. Default is `false`.
`last_updated_time`	`string`		The date and time when the tracking information was last updated, in Internet date and time format. Minimum length: 20. Maximum length: 64.

For parameter details, see parameters.

The following request adds tracking information without a tracking number for a PayPal transaction:

curl -v -k -X POST 'https://api-m.sandbox.paypal.com/v1/shipping/trackers-batch' \
 -H 'Content-Type: application/json' \
 -d '{
  "trackers": [{
    "transaction_id": "8MC585209K746392H",
    "status": "SHIPPED"
  }]
}'

A successful request returns the HTTP 200 OK status code with a JSON response body that lists tracking information for each transaction:

{
  "tracker_identifiers": [{
    "transaction_id": "8MC585209K746392H",
    "links": [{
      "href": "https://api-m.sandbox.paypal.com/v1/shipping/trackers/8MC585209K746392H-NOTRACKER",
      "rel": "self",
      "method": "GET"
    }, {
      "href": "https://api-m.sandbox.paypal.com/v1/shipping/trackers/8MC585209K746392H-NOTRACKER",
      "rel": "replace",
      "method": "PUT"
    }, {
      "href": "https://api-m.sandbox.paypal.com/v1/shipping/trackers/8MC585209K746392H-NOTRACKER",
      "rel": "edit",
      "method": "PATCH"
    }]
  }]
}

4. Show tracking information

To show tracking information, call GET https://api-m.sandbox.paypal.com/v1/shipping/trackers/<transactionId>-<trackingnumber>.

You can filter this information by including search criteria in the request.

The following request searches for tracking information for a tracking number:

curl -v -X GET https://api-m.sandbox.paypal.com/v1/shipping/trackers/123456789-XYZ123456 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <Access-Token>"

A successful request returns the HTTP 200 OK status code and any tracking information that matches the search criteria:

{
  "transaction_id": "123456789",
  "tracking_number": "XYZ123456",
  "status": "SHIPPED",
  "shipment_date": "2015-05-31",
  "carrier": "FEDEX",
  "links": [{
    "href": "https://api-m.sandbox.paypal.com/v1/shipping/trackers-batch/123456789-XYZ123456",
    "rel": "self"
  }, {
    "href": "https://api-m.sandbox.paypal.com/v1/shipping/trackers-batch/123456789-XYZ123456",
    "rel": "replace",
    "method": "PUT"
  }, {
    "href": "https://api-m.sandbox.paypal.com/v1/shipping/trackers-batch",
    "rel": "create",
    "method": "POST"
  }]
}

5. Update or cancel tracking information

To update tracking information, include the tracking ID in the request URL and the information to change in the request body:

curl -v -X PUT https://api-m.sandbox.paypal.com/v1/shipping/trackers/8MC585209K746392H-443844607820 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
  "transaction_id": "8MC585209K746392H",
  "tracking_number": "443844607820",
  "status": "SHIPPED",
  "carrier": "FEDEX"
}'

A successful request returns the HTTP 204 No Content status code with no JSON response body.

To cancel tracking information, call the update tracking information method and set the status to CANCELLED:

curl -v -k -X PUT 'https://api-m.sandbox.paypal.com/v1/shipping/trackers/8MC585209K746392H-443844607820' \
 -H 'Content-Type: application/json' \
 -d '{
  "transaction_id": "8MC585209K746392H",
  "tracking_number": "443844607820",
  "status": "CANCELLED",
  "carrier": "FEDEX"
}'

A successful request returns the HTTP 204 No Content status code with no JSON response body.