Other use cases
Learn about other Orders v2 API use cases.
Update an order
Updates an order with a CREATED or APPROVED status. You cannot update an order with the COMPLETED status.
To make an update, you need to provide a reference_id. If you omit this value with an order that contains only one purchase unit, PayPal sets the value to default, which enables you to use the path: "/purchase_units/@reference_id=='default'/{attribute-or-object}".
Patchable fields and objects
| Attribute | Op | Notes |
|---|---|---|
intent |
replace |
|
payer |
replace, add |
Using replace as the operation for payer will replace the whole payer object with the value sent in the request. |
purchase_units |
replace, add |
|
purchase_units[].custom_id |
replace, add, remove |
|
purchase_units\|].description |
replace, add, remove |
|
purchase_units].payee.email |
replace |
|
purchase_units].shipping. name |
replace, add |
|
purchase_units].shipping.email_address |
replace, add |
|
purchase_units].shipping. phone_number |
replace, add |
|
purchase_units\|].shipping.options |
replace, add |
|
purchase_units[].shipping.address |
replace, add |
|
purchase_units [].shipping.type |
replace, add |
|
purchase_units].soft_descriptor |
replace, remove |
|
purchase_units [] -amount |
replace |
|
purchase_units[].items |
replace, add, remove |
|
purchase_units]. invoice_id |
replace, add, remove |
|
purchase_units].payment_instruction |
replace |
|
purchase_units[].payment_instruction.disbursement_mode |
replace |
By default, disbursement_mode is INSTANT. |
purchase_units].payment_instruction.payee_receivable_fx_rate_id |
replace, add, remove |
|
purchase_unitsll.payment_instruction.platform_fees |
replace, add, remove |
|
purchase_units [].supplementary_data.airline |
replace, add, remove |
|
purchase_units[l.supplementary_data.card |
replace, add, remove |
|
application_context.client_configuration |
replace, add |
Example 1: Updating purchase_units
Update the purchase_units object of an order by sending a PATCH request with the order ID to /v2/checkout/orders/ORDER-ID.
Sample patch purchase_units request
curl -v -X PATCH https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID
-H 'Content-Type: application/json'
-H 'Authorization: Bearer access_token'
-d '[
{
"op": "replace",
"path": "/purchase_units/@reference_id=='PUHF'",
"value": {
"reference_id": "PUHF",
"description": "Sporting Goods",
"invoice_id": "INV-HighFashions",
"custom_id": "CUST-HighFashions",
"soft_descriptor": "HighFashions",
"amount": {
"currency_code": "USD",
"value": "240.00",
"breakdown": {
"item_total": {
"currency_code": "USD",
"value": "200.00"
},
"shipping": {
"currency_code": "USD",
"value": "20.00"
},
"handling": {
"currency_code": "USD",
"value": "10.00"
},
"tax_total": {
"currency_code": "USD",
"value": "20.00"
},
"shipping_discount": {
"currency_code": "USD",
"value": "5.00"
},
"discount": {
"currency_code": "USD",
"value": "5.00"
}
}
},
"payee": {
"email_address": "merchant@example.com"
},
"items": [
{
"name": "T-Shirt",
"description": "Green XL",
"sku": "sku01",
"unit_amount": {
"currency_code": "USD",
"value": "90.00"
},
"tax": {
"currency_code": "USD",
"value": "10.00"
},
"quantity": "1",
"category": "PHYSICAL_GOODS"
},
{
"name": "Shoes",
"description": "Running, Size 10.5",
"sku": "sku02",
"unit_amount": {
"currency_code": "USD",
"value": "45.00"
},
"tax": {
"currency_code": "USD",
"value": "5.00"
},
"quantity": "2",
"category": "PHYSICAL_GOODS"
}
],
"shipping": {
"address": {
"address_line_1": "2211 N First Street",
"address_line_2": "Building 17",
"admin_area_2": "San Jose",
"admin_area_1": "CA",
"postal_code": "95131",
"country_code": "US"
}
}
}
}
]'Sample patch purchase_units response
204 No ContentExample 2: Updating supplementary_data.card
Update the supplementary_data.card object of an order by sending a PATCH request with the order ID to /v2/checkout/orders/ORDER-ID.
Sample patch supplementary_data.card request
curl -v -X PATCH https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID
-H 'Content-Type: application/json'
-H 'Authorization: Bearer access_token'
'[
{ "op": "add",
"path": "/purchase_units/@reference_id=='default'/supplementary_data/card",
"value": {
"level_2": {
"invoice_id": "INVOICE_ID1",
"tax_total": {
"currency_code": "USD",
"value": "5.00"
}
}
}
}
]'Sample patch supplementary_data.card response
204 No ContentUpdate or cancel tracking information for a PayPal order
Updates or cancels the tracking information for a PayPal order, by ID.
Patchable fields and objects
| Attribute | Op | Notes |
|---|---|---|
items |
replace |
Using the replace operation for items will replace the entire items object with the value sent in the request. |
notify_payer |
replace, add |
|
status |
replace |
You can only patch the status to CANCELLED. |
Sample update items in tracking order request
curl -v -X PATCH https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER-ID/trackers/TRACKER-ID \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS-TOKEN' \
-d '[
{
"op": "replace",
"path": "items",
"value": [
{
"name": "T-Shirt",
"sku": "sku01",
"quantity": "1",
"upc": {
"type": "UPC-A",
"code": "upc001"
},
"image_url": "https://www.example.com/example1.jpg",
"url": "https://www.example.com/example"
},
{
"name": "NeoPhone",
"sku": "sku02",
"quantity": "2",
"upc": {
"type": "UPC-A",
"code": "upc002"
},
"image_url": "https://www.example.com/example2.jpg",
"url": "https://www.example.com/example"
}
]
}
]'Sample update items in tracking order response
204 No ContentWebhooks
The Orders v2 API and its endpoints support the following webhooks:
| Event | Trigger | Related method |
|---|---|---|
CHECKOUT.ORDER.COMPLETED |
A checkout order is processed. Note: For use by marketplaces and platforms only. |
Orders v2 API |
CHECKOUT.ORDER.APPROVED |
A buyer approved a checkout order. | Orders v2 API |
CHECKOUT.PAYMENT-APPROVAL.REVERSED |
A problem occurred after the buyer approved the order but before you captured the payment. Refer to Handle uncaptured payments for what to do when this event occurs. | Orders v2 API |