Update an Order

DOCS

Last updated: Dec 20th, 5:00pm

You may need to update an order for any number of reasons. For example, shipping costs may change when a buyer updates their shipping address, inventory items change, or inventory sites change.

To update an order with a CREATED or APPROVED status, pass the order ID as a path parameter to PATCH v2/checkout/orders/{order_id}/.

Important: You cannot update an order with the COMPLETED status.

In the JSON body of your request, send the op to note the type of action to complete, the path of the target to update, and the value of the change.

Parameter	Type	Description
`op`	enum	Required. The operation to complete. Possible values: `add`, `remove`, `replace`, `move`, `copy`, `test`.
`path`	string	The JSON pointer to target document location at which to complete the operation.
`value`	number, integer, string, boolean, null, array, object	The value to apply. The `remove` operation does not require a value.

You can update these attributes and objects:

Attribute or object	Operations
`intent`	replace
`purchase_units`	add, replace
`purchase_units[].custom_id`	add, replace, remove
`purchase_units[].description`	add, replace, remove
`purchase_units[].payee.email`	add, replace
`purchase_units[].shipping`	add, replace, remove
`purchase_units[].soft_descriptor`	add, replace, remove
`purchase_units[].amount`	replace
`purchase_units[].invoice_id`	add, replace, remove
`purchase_units[].payment_instruction`	replace
`purchase_units[].payment_instruction.disbursement_mode`	replace
`purchase_units[].payment_instruction.platform_fees`	replace

When patching purchase_units, provide a reference_id as part of the path. The purchase unit is an array, and PayPal does not support JSON pointers in arrays.

If you have not provided a reference_id and the order was created with one (1) purchase_units, PayPal sets the value to default. This allows you to use a path such as: "path": "/purchase_units/@reference_id=='default'/{attribute or object you want to patch}".

Request sample: Payment instruction

1curl -v -X PATCH https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer Access-Token" \
4-d '[{
5      "op": "replace",
6      "path": "/purchase_units/@reference_id=='Refe'/payment_instruction",
7      "value": {
8        "disbursement_mode": "DELAYED",
9        "platform_fees": [{
10          "amount": {
11            "currency_code": "USD",
12            "value": "35.00"
13          },
14          "payee": {
15            "email_address": "merchant@paypal.com"
16          }
17        }]
18      }
19    }]'

Request sample: Partner fee

1curl -v -X PATCH https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
2-H "Content-Type: application/json" \
3-H "Authorization: Bearer Access-Token" \
4-d '[{
5      "op": "replace",
6      "path": "/purchase_units/@reference_id=='Refe'/payment_instruction",
7      "value": {
8        "disbursement_mode": "DELAYED",
9        "platform_fees": [{
10          "amount": {
11            "currency_code": "USD",
12            "value": "35.00"
13          },
14          "payee": {
15            "email_address": "merchant@paypal.com"
16          }
17        }]
18      }
19    }]'

Request sample: Disbursement mode

1curl -v -X PATCH https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
2    -H "Content-Type: application/json" \
3    -H "Authorization: Bearer Access-Token" \
4    -d '[{ 
5    "op": "replace",
6    "path": "/purchase_units/@reference_id=='Refe'/payment_instruction/disbursement_mode",
7    "value": "DELAYED"
8    }]'

Response

For any update, a successful request returns the HTTP 204 No Content status code with an empty object in the JSON response body.

Show order details

After any update, you can make a show order details call to verify your changes by passing the order_id as a path parameter to /v2/checkout/orders/{order_id}.

Request sample

1curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
2    -H "Content-Type: application/json" \
3    -H "Authorization: Bearer Access-Token"

Response sample

A successful request returns the HTTP 200 OK status code and a JSON response body that shows order details.

This particular sample response shows the results of the first update to the previous payment instruction update.

1{
2  "id": "5O190127TN364715T",
3  "status": "COMPLETED",
4  "intent": "CAPTURE",
5  "payer": {
6    "name": {
7      "given_name": "John",
8      "surname": "Doe"
9    },
10    "email_address": "customer@example.com",
11    "payer_id": "QYR5Z8XDVJNXQ"
12  },
13  "purchase_units": [
14    {
15      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
16      "amount": {
17        "currency_code": "USD",
18        "value": "35.00"
19      },
20      "payee": {
21        "email_address": "merchant@example.com"
22      },
23      "shipping": {
24        "address": {
25          "address_line_1": "2211 N First Street",
26          "address_line_2": "Building 17",
27          "admin_area_2": "San Jose",
28          "admin_area_1": "CA",
29          "postal_code": "95131",
30          "country_code": "US"
31        }
32      },
33      "payments": {
34        "captures": [
35          {
36            "id": "3C679366HH908993F",
37            "status": "COMPLETED",
38            "amount": {
39              "currency_code": "USD",
40              "value": "100.00"
41            },
42            "seller_protection": {
43              "status": "ELIGIBLE",
44              "dispute_categories": [
45                "ITEM_NOT_RECEIVED",
46                "UNAUTHORIZED_TRANSACTION"
47              ]
48            },
49            "final_capture": true,
50            "disbursement_mode": "DELAYED",
51            "seller_receivable_breakdown": {
52              "gross_amount": {
53                "currency_code": "USD",
54                "value": "100.00"
55              },
56              "paypal_fee": {
57                "currency_code": "USD",
58                "value": "3.00"
59              },
60              "net_amount": {
61                "currency_code": "USD",
62                "value": "97.00"
63              }
64            },
65            "create_time": "2018-04-01T21:20:49Z",
66            "update_time": "2018-04-01T21:20:49Z",
67            "links": [
68              {
69                "href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F",
70                "rel": "self",
71                "method": "GET"
72              },
73              {
74                "href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
75                "rel": "refund",
76                "method": "POST"
77              }
78            ]
79          }
80        ]
81      }
82    }
83  ],
84  "create_time": "2018-04-01T21:18:49Z",
85  "update_time": "2018-04-01T21:20:49Z",
86  "links": [
87    {
88      "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
89      "rel": "self",
90      "method": "GET"
91    }
92  ]
93}