On this page
No Headings
Last updated: June 4, 2026
Add package tracking numbers to your orders with the Orders v2 API.
You can only assign tracking information to orders that have been captured and are in one of the following states:
COMPLETEDPARTIALLY_REFUNDEDPENDINGWhen 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:
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/
-H "Content-Type: application/json"
-H "Authorization: Bearer ACCESS_TOKEN"
-d '{
"intent": "CAPTURE", "payment_source": {
"paypal": {
"experience_context": {
"payment_method_preference": "IMMEDIATE_PAYMENT_REQUIRED",
"landing_page": "LOGIN",
"shipping_preference": "GET_FROM_FILE",
"user_action": "PAY_NOW",
"return_url": "https://example.com/returnUrl",
"cancel_url": "https://example.com/cancelUrl"
}
}
}, "purchase_units": [{
"invoice_id": "92021"
"amount": {
"currency_code": "USD",
"value": "230.00",
"breakdown": {
"item_total": {
"currency_code": "USD",
"value": "220.00"
},
"shipping": {
"currency_code": "USD",
"value": "10.00"
}
}
},
"items": [{
"name": "T-Shirt",
"description": "Super Fresh Shirt",
"unit_amount": {
"currency_code": "USD",
"value": "20.00"
},
"quantity": "1",
"category": "PHYSICAL_GOODS",
"sku": "sku01",
"image_url": "https://example.com/static/images/items/1/tshirt_green.jpg",
"url": "https://example.com/url-to-the-item-being-purchased-1",
"upc": {
"type": "UPC-A",
"code": "123456789012"
}
}, {
"name": "Shoes",
"description": "Running, Size 10.5",
"sku": "sku02",
"unit_amount": {
"currency_code": "USD",
"value": "100.00"
},
"quantity": "2",
"category": "PHYSICAL_GOODS",
"image_url": "https://example.com/static/images/items/1/shoes_running.jpg",
"url": "https://example.com/url-to-the-item-being-purchased-2",
"upc": {
"type": "UPC-A",
"code": "987654321012"
}
}]
}]
}'{
"id": "5O190127TN364715T",
"status": "PAYER_ACTION_REQUIRED",
"payment_source": {
"paypal": {}
},
"links": [{
"href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "self",
"method": "GET"
}, {
"href": "https://www.sandbox.paypal.com/checkoutnow?token=5O190127TN364715T",
"rel": "payer-action",
"method": "GET"
}]
}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.
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/capture
-H "Content-Type: application/json"
-H "Authorization: Bearer ACCESS-TOKEN"
-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:
{
"id": "5O190127TN364715T",
"status": "COMPLETED",
"payment_source": {
"paypal": {
"email_address": "[email protected]",
"account_id": "4VUS3C84RXJDA",
"name": {
"given_name": "Firstname",
"surname": "Lastname"
},
"address": {
"country_code": "US"
}
}
},
"purchase_units": [{
"reference_id": "default",
"shipping": {
"name": {
"full_name": "Firstname Lastname"
},
"address": {
"address_line_1": "123 Main St",
"admin_area_2": "Anytown",
"admin_area_1": "CA",
"postal_code": "12345",
"country_code": "US"
}
},
"payments": {
"captures": [{
"id": "8MC585209K746392H",
"status": "COMPLETED",
"amount": {
"currency_code": "USD",
"value": "230.00"
},
"final_capture": true,
"disbursement_mode": "INSTANT",
"seller_protection": {
"status": "ELIGIBLE",
"dispute_categories": ["ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION"]
},
"seller_receivable_breakdown": {
"gross_amount": {
"currency_code": "USD",
"value": "230.00"
},
"paypal_fee": {
"currency_code": "USD",
"value": "8.52"
},
"net_amount": {
"currency_code": "USD",
"value": "221.48"
}
},
"links": [{
"href": "https://api-m.sandbox.paypal.com/v2/payments/captures/8MC585209K746392H",
"rel": "self",
"method": "GET"
}, {
"href": "https://api-m.sandbox.paypal.com/v2/payments/captures/8MC585209K746392H/refund",
"rel": "refund",
"method": "POST"
}, {
"href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "up",
"method": "GET"
}],
"create_time": "2022-09-27T20:52:27Z",
"update_time": "2022-09-27T20:52:27Z"
}]
}
}],
"payer": {
"name": {
"given_name": "Firstname",
"surname": "Lastname"
},
"email_address": "[email protected]",
"payer_id": "4VUS3C84RXJDA",
"address": {
"country_code": "US"
}
},
"links": [{
"href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "self",
"method": "GET"
}]
}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:
curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T/track
-H "Content-Type: application/json"
-H "Authorization: Bearer ACCESS-TOKEN"
-d '{
"capture_id": "8MC585209K746392H",
"tracking_number": "443844607820",
"carrier": "FEDEX",
"notify_payer": true,
"items": [{
"sku": "sku01",
"quantity": "1",
"name": "T-Shirt",
"description": "Green T-Shirt",
"image_url": "https://example.com/static/images/items/1/tshirt_green.jpg",
"url": "https://example.com/url-to-the-item-being-purchased-1",
"upc": {
"type": "UPC-A",
"code": "123456789012"
}
}, {
"sku": "sku02",
"quantity": "2",
"name": "Shoes",
"description": "Running, Size 10.5",
"image_url": "https://example.com/static/images/items/1/shoes_running.jpg",
"url": "https://example.com/url-to-the-item-being-purchased-2",
"upc": {
"type": "UPC-A",
"code": "987654321012"
}
}]
}'{ "status": "201 Created", "headers": {
"Content-Type": "application/json"
}, "body": {
"id": "5O190127TN364715T",
"status": "COMPLETED",
"purchase_units": [{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"items": [{
"name": "Shoes",
"sku": "sku02",
"quantity": "1"
}, {
"name": "T-Shirt",
"sku": "sku01",
"quantity": "1"
}],
"shipping": {
"trackers": [{
"id": "8MC585209K746392H-443844607820",
"links": [{
"href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "up",
"method": "GET"
}, {
"href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/trackers/8MC585209K746392H-443844607820",
"rel": "update",
"method": "PATCH"
}],
"create_time": "2022-08-12T21:20:49Z",
"update_time": "2022-08-12T21:20:49Z"
}]
},
"payments": {
"captures": [{
"id": "8MC585209K746392H",
"status": "COMPLETED",
"amount": {
"currency_code": "USD",
"value": "100.00"
},
"seller_protection": {
"status": "NOT_ELIGIBLE"
},
"final_capture": true,
"seller_receivable_breakdown": {
"gross_amount": {
"currency_code": "USD",
"value": "100.00"
},
"paypal_fee": {
"currency_code": "USD",
"value": "3.00"
},
"net_amount": {
"currency_code": "USD",
"value": "97.00"
}
},
"create_time": "2018-04-01T21:20:49Z",
"update_time": "2018-04-01T21:20:49Z",
"links": [{
"href": "https://api-m.paypal.com/v2/payments/captures/8MC585209K746392H",
"rel": "self",
"method": "GET"
}, {
"href": "https://api-m.paypal.com/v2/payments/captures/8MC585209K746392H/refund",
"rel": "refund",
"method": "POST"
}]
}]
}
}],
"links": [{
"href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "self",
"method": "GET"
}]
}
}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.