Integrate package tracking

DocsCurrentLast updated: December 6th 2023, @ 8:15:32 am

Add package tracking numbers to your orders with the Orders v2 API.

Know before you code

You can only assign tracking information to orders that have been captured and are in one of the following states:

COMPLETED
PARTIALLY_REFUNDED
PENDING

1. Create order with item details

When you create the order, include the following item details in the purchase_units of the order:

sku: The item's SKU.
upc: The item's UPC.
image_url: The URL to the image of the item in the order.
url: The URL to the item on your store.

Sending item details helps payers dispute individual items instead of the entire transaction, which reduces dispute-related refunds and holds.

This example shows an order with item details made after the payer clicked the PayPal button:

Create Order sample request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/ 
2-H "Content-Type: application/json" 
3-H "Authorization: Bearer ACCESS_TOKEN" 
4-d '{
5"intent": "CAPTURE", "payment_source": {
6  "paypal": {
7    "experience_context": {
8      "payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
9      "landing_page": "LOGIN",
10      "shipping_preference": "GET_FROM_FILE",
11      "user_action": "PAY_NOW",
12      "return_url": "https://example.com/returnUrl",
13      "cancel_url": "https://example.com/cancelUrl"
14    }
15  }
16}, "purchase_units": [{
17  "invoice_id": "92021"
18  "amount": {
19    "currency_code": "USD",
20    "value": "230.00",
21    "breakdown": {
22      "item_total": {
23        "currency_code": "USD",
24        "value": "220.00"
25      },
26      "shipping": {
27        "currency_code": "USD",
28        "value": "10.00"
29      }
30    }
31  },
32  "items": [{
33    "name": "T-Shirt",
34    "description": "Super Fresh Shirt",
35    "unit_amount": {
36      "currency_code": "USD",
37      "value": "20.00"
38    },
39    "quantity": "1",
40    "category": "PHYSICAL_GOODS",
41    "sku": "sku01",
42    "image_url": "https://example.com/static/images/items/1/tshirt_green.jpg",
43    "url": "https://example.com/url-to-the-item-being-purchased-1",
44    "upc": {
45      "type": "UPC-A",
46      "code": "123456789012"
47    }
48  }, {
49    "name": "Shoes",
50    "description": "Running, Size 10.5",
51    "sku": "sku02",
52    "unit_amount": {
53      "currency_code": "USD",
54      "value": "100.00"
55    },
56    "quantity": "2",
57    "category": "PHYSICAL_GOODS",
58    "image_url": "https://example.com/static/images/items/1/shoes_running.jpg",
59    "url": "https://example.com/url-to-the-item-being-purchased-2",
60    "upc": {
61      "type": "UPC-A",
62      "code": "987654321012"
63    }
64  }]
65}]
66}'

Create Order sample response

1{
2  "id": "5O190127TN364715T",
3  "status": "PAYER_ACTION_REQUIRED",
4  "payment_source": {
5    "paypal": {}
6  },
7  "links": [{
8    "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
9    "rel": "self",
10    "method": "GET"
11  }, {
12    "href": "https://www.sandbox.paypal.com/checkoutnow?token=5O190127TN364715T",
13    "rel": "payer-action",
14    "method": "GET"
15  }]
16}

2. Capture order

After the order has been created and the payer approves the purchase, capture the order by calling the /v2/checkout/orders/{id}/capture endpoint. An order must be in the COMPLETED status and captured to assign shipping tracking information.

Capture Order sample request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture 
2-H "Content-Type: application/json" 
3-H "Authorization: Bearer ACCESS-TOKEN" 
4-d '{}'

Store the order ID and the purchase_units.payment.captures.id in the response after the order is captured.

In this example, the order ID is 5O190127TN364715T, and the purchase_units.payments.captures.id is 8MC585209K746392H:

Capture Order sample response

1{
2  "id": "5O190127TN364715T",
3  "status": "COMPLETED",
4  "payment_source": {
5    "paypal": {
6      "email_address": "payer@example.com",
7      "account_id": "4VUS3C84RXJDA",
8      "name": {
9        "given_name": "Firstname",
10        "surname": "Lastname"
11      },
12      "address": {
13        "country_code": "US"
14      }
15    }
16  },
17  "purchase_units": [{
18    "reference_id": "default",
19    "shipping": {
20      "name": {
21        "full_name": "Firstname Lastname"
22      },
23      "address": {
24        "address_line_1": "123 Main St",
25        "admin_area_2": "Anytown",
26        "admin_area_1": "CA",
27        "postal_code": "12345",
28        "country_code": "US"
29      }
30    },
31    "payments": {
32      "captures": [{
33        "id": "8MC585209K746392H",
34        "status": "COMPLETED",
35        "amount": {
36          "currency_code": "USD",
37          "value": "230.00"
38        },
39        "final_capture": true,
40        "disbursement_mode": "INSTANT",
41        "seller_protection": {
42          "status": "ELIGIBLE",
43          "dispute_categories": ["ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION"]
44        },
45        "seller_receivable_breakdown": {
46          "gross_amount": {
47            "currency_code": "USD",
48            "value": "230.00"
49          },
50          "paypal_fee": {
51            "currency_code": "USD",
52            "value": "8.52"
53          },
54          "net_amount": {
55            "currency_code": "USD",
56            "value": "221.48"
57          }
58        },
59        "links": [{
60          "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/8MC585209K746392H",
61          "rel": "self",
62          "method": "GET"
63        }, {
64          "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/8MC585209K746392H/refund",
65          "rel": "refund",
66          "method": "POST"
67        }, {
68          "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
69          "rel": "up",
70          "method": "GET"
71        }],
72        "create_time": "2022-09-27T20:52:27Z",
73        "update_time": "2022-09-27T20:52:27Z"
74      }]
75    }
76  }],
77  "payer": {
78    "name": {
79      "given_name": "Firstname",
80      "surname": "Lastname"
81    },
82    "email_address": "payer@example.com",
83    "payer_id": "4VUS3C84RXJDA",
84    "address": {
85      "country_code": "US"
86    }
87  },
88  "links": [{
89    "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
90    "rel": "self",
91    "method": "GET"
92  }]
93}

3. Assign package tracking information to an order

Use the Add Tracking API to assign parcel tracking numbers to PayPal orders after a shipping label is created.

Provide item details during the shipping tracking phase to identify the item in transit and improve the in-app payer experience.

The following example creates a new tracking number for an order where all items being shipped are in the same package:

Create tracking number sample request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/track 
2-H "Content-Type: application/json" 
3-H "Authorization: Bearer ACCESS-TOKEN" 
4-d '{ 
5"capture_id": "8MC585209K746392H", 
6"tracking_number": "443844607820", 
7"carrier": "FEDEX", 
8"notify_payer": true, 
9"items": [{
10  "sku": "sku01",
11  "quantity": "1",
12  "name": "T-Shirt",
13  "description": "Green T-Shirt",
14  "image_url": "https://example.com/static/images/items/1/tshirt_green.jpg",
15  "url": "https://example.com/url-to-the-item-being-purchased-1",
16  "upc": {
17    "type": "UPC-A",
18    "code": "123456789012"
19  }
20}, {
21  "sku": "sku02",
22  "quantity": "2",
23  "name": "Shoes",
24  "description": "Running, Size 10.5",
25  "image_url": "https://example.com/static/images/items/1/shoes_running.jpg",
26  "url": "https://example.com/url-to-the-item-being-purchased-2",
27  "upc": {
28    "type": "UPC-A",
29    "code": "987654321012"
30  }
31}]
32}'

Create tracking number sample response

1{ "status": "201 Created", "headers": {
2  "Content-Type": "application/json"
3}, "body": {
4  "id": "5O190127TN364715T",
5  "status": "COMPLETED",
6  "purchase_units": [{
7    "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
8    "items": [{
9      "name": "Shoes",
10      "sku": "sku02",
11      "quantity": "1"
12    }, {
13      "name": "T-Shirt",
14      "sku": "sku01",
15      "quantity": "1"
16    }],
17    "shipping": {
18      "trackers": [{
19        "id": "8MC585209K746392H-443844607820",
20        "links": [{
21          "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
22          "rel": "up",
23          "method": "GET"
24        }, {
25          "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/trackers/8MC585209K746392H-443844607820",
26          "rel": "update",
27          "method": "PATCH"
28        }],
29        "create_time": "2022-08-12T21:20:49Z",
30        "update_time": "2022-08-12T21:20:49Z"
31      }]
32    },
33    "payments": {
34      "captures": [{
35        "id": "8MC585209K746392H",
36        "status": "COMPLETED",
37        "amount": {
38          "currency_code": "USD",
39          "value": "100.00"
40        },
41        "seller_protection": {
42          "status": "NOT_ELIGIBLE"
43        },
44        "final_capture": true,
45        "seller_receivable_breakdown": {
46          "gross_amount": {
47            "currency_code": "USD",
48            "value": "100.00"
49          },
50          "paypal_fee": {
51            "currency_code": "USD",
52            "value": "3.00"
53          },
54          "net_amount": {
55            "currency_code": "USD",
56            "value": "97.00"
57          }
58        },
59        "create_time": "2018-04-01T21:20:49Z",
60        "update_time": "2018-04-01T21:20:49Z",
61        "links": [{
62          "href": "https://api-m.paypal.com/v2/payments/captures/8MC585209K746392H",
63          "rel": "self",
64          "method": "GET"
65        }, {
66          "href": "https://api-m.paypal.com/v2/payments/captures/8MC585209K746392H/refund",
67          "rel": "refund",
68          "method": "POST"
69        }]
70      }]
71    }
72  }],
73  "links": [{
74    "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
75    "rel": "self",
76    "method": "GET"
77  }]
78}
79}

If the items in the order are shipped in several separate parcels, call the v2/checkout/orders/{id}/track endpoint separately for each new tracking ID or parcel.

The Tracking API is idempotent, so if you pass the same capture-id and tracking-id combination, a HTTP 200 response is returned.

Reference

Add tracking information for an order