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 Content
Example 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 Content
Update 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 Content
Webhooks
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 |