Add Tracking API Integration Guide

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.

    To cancel information, merchants call the update tracking information method.

  • Show tracking details.

Integration steps

1. Required Set up your development environment.
2. Required Add tracking information with tracking numbers.
3. Required Add tracking information without tracking numbers.
4. Optional Show tracking information.
5. Optional Update or cancel tracking information.

Set up your development environment

Before you can integrate Add 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.

Then, return to this page to integrate Add Tracking.

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.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.sandbox.paypal.com/v1/shipping/trackers/8MC585209K746392H-443844607820",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.sandbox.paypal.com/v1/shipping/trackers/8MC585209K746392H-443844607820",
          "rel": "replace",
          "method": "PUT"
        }
      ]
    },
    {
      "transaction_id": "53Y56775AE587553X",
      "tracking_number": "443844607821",
      "links": [
        {
          "href": "https://api.sandbox.paypal.com/v1/shipping/trackers/53Y56775AE587553X-443844607821",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://api.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.sandbox.paypal.com/v1/shipping/trackers-batch",
      "rel": "self",
      "method": "POST"
    }
  ]
}

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.sandbox.paypal.com/v1/shipping/trackers-batch' \
 -H 'X-PAYPAL-SECURITY-CONTEXT: ' \
 -H 'Content-Type: application/json' \
 -d '{
  "trackers": [{
    "transaction_id": "8MC585209K746392H",
    "status": "SHIPPED",
    "carrier": "FEDEX"
  }]
}'

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

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

Show tracking information

To show tracking information, call GET https://api.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.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.sandbox.paypal.com/v1/shipping/trackers-batch/123456789-XYZ123456",
    "rel": "self"
  }, {
    "href": "https://api.sandbox.paypal.com/v1/shipping/trackers-batch/123456789-XYZ123456",
    "rel": "replace",
    "method": "PUT"
  }, {
    "href": "https://api.sandbox.paypal.com/v1/shipping/trackers-batch",
    "rel": "create",
    "method": "POST"
  }]
}

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.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:

HTTP status code: 204 No Content

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

curl -v -k -X PUT 'https://api.sandbox.paypal.com/v1/shipping/trackers/8MC585209K746392H-443844607820' \
 -H 'X-PAYPAL-SECURITY-CONTEXT: ' \
 -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:

204 No Content