Track shipments with the Orders API
DocsBetaLast updated: March 16th 2023, @ 11:23:55 am
If you sell tangible goods, adding tracking information to your PayPal orders as soon as you ship items to your customers can help you streamline the post-purchase lifecycle.
Providing tracking information can help you:
- Access money more quickly.
- Automate dispute resolution.
- Provide seller protection.
- Keep customers informed about when their items will arrive.
Know before you code
You can only assign tracking information to orders that have been captured and are in the COMPLETED state.
1. Create order with item details
When you create the order, include item details in the purchase_units of the order, such as the SKU, UPC, and item image URL.
This example shows an order with item details created after the payer clicked the PayPal button:
Create Order sample request
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",
"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",
"upc": {
"type": "UPC-A",
"code": "987654321012"
}
}
]
}
]
}'
Create Order sample response
{
"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://sandbox.paypal.com/checkoutnow?token=5O190127TN364715T",
"rel": "payer-action",
"method": "GET"
}
]
}
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
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 from 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
{
"id": "5O190127TN364715T",
"status": "COMPLETED",
"payment_source": {
"paypal": {
"email_address": "sb-fsta88221026@personal.example.com",
"account_id": "4VUS3C84RXJDA",
"name": {
"given_name": "John",
"surname": "Doe"
},
"address": {
"country_code": "US"
}
}
},
"purchase_units": [
{
"reference_id": "default",
"shipping": {
"name": {
"full_name": "John Doe"
},
"address": {
"address_line_1": "1 Main St",
"admin_area_2": "San Jose",
"admin_area_1": "CA",
"postal_code": "95131",
"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": "John",
"surname": "Doe"
},
"email_address": "sb-fsta88221026@personal.example.com",
"payer_id": "4VUS3C84RXJDA",
"address": {
"country_code": "US"
}
},
"links": [
{
"href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T",
"rel": "self",
"method": "GET"
}
]
}
3. Assign shipping 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.
Important: You can't add items to the request that weren't part of the order when it was captured. Make sure the SKU used for an item in the request matches one of the SKUs used in the
purchase_unitsarray during order creation. The Orders Tracking API returns an error if you pass different SKUs.
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
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": "Super Fresh Shirt",
"image_url": "https://example.com/static/images/items/1/tshirt_green.jpg",
"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",
"upc": {
"type": "UPC-A",
"code": "987654321012"
}
}
]
}'
Create tracking number sample response
"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.