Appearance
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\
Copy
Copied
\
bash\
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": "[email protected]"\
},\
"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\
\
Copy\
\
Copied\
\
```bash\
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\
\
Copy\
\
Copied\
\
```bash\
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\
\
Copy\
\
Copied\
\
```bash\
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\
\
Copy\
\
Copied\
\
```bash\
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\
\
Copy\
\
Copied\
\
```bash\
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.<br>**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 |\
\