Update an Order

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.

You can update these attributes and objects:

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

curl -v -X PATCH https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[{
      "op": "replace",
      "path": "/purchase_units/@reference_id=='Refe'/payment_instruction",
      "value": {
        "disbursement_mode": "DELAYED",
        "platform_fees": [{
          "amount": {
            "currency_code": "USD",
            "value": "35.00"
          },
          "payee": {
            "email_address": "merchant@paypal.com"
          }
      }]
    }
}]'

Request sample: Partner fee

curl -v -X PATCH https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[{
      "op": "add",
      "path": "/purchase_units/@reference_id=='Refe'/payment_instruction/platform_fees",
      "value": [{
        "amount": {
          "currency_code": "USD",
          "value": "20.00
        },
        "payee": {
          "email_address": "merchant@paypal.com"
        }
      }
    ]
  }]'

Request sample: Disbursement mode

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

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

curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5O190127TN364715T \
-H "Content-Type: application/json" \
-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.

{
  "id": "5O190127TN364715T",
  "status": "COMPLETED",
  "intent": "CAPTURE",
  "payer": {
    "name": {
      "given_name": "John",
      "surname": "Doe"
    },
    "email_address": "customer@example.com",
    "payer_id": "QYR5Z8XDVJNXQ"
  },
  "purchase_units": [
    {
      "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
      "amount": {
        "currency_code": "USD",
        "value": "35.00"
      },
      "payee": {
        "email_address": "merchant@example.com"
      },
      "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"
        }
      },
      "payments": {
        "captures": [
          {
            "id": "3C679366HH908993F",
            "status": "COMPLETED",
            "amount": {
              "currency_code": "USD",
              "value": "100.00"
            },
            "seller_protection": {
              "status": "ELIGIBLE",
              "dispute_categories": [
                "ITEM_NOT_RECEIVED",
                "UNAUTHORIZED_TRANSACTION"
              ]
            },
            "final_capture": true,
            "disbursement_mode": "DELAYED",
            "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/3C679366HH908993F",
                "rel": "self",
                "method": "GET"
              },
              {
                "href": "https://api-m.paypal.com/v2/payments/captures/3C679366HH908993F/refund",
                "rel": "refund",
                "method": "POST"
              }
            ]
          }
        ]
      }
    }
  ],
  "create_time": "2018-04-01T21:18:49Z",
  "update_time": "2018-04-01T21:20:49Z",
  "links": [
    {
      "href": "https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T",
      "rel": "self",
      "method": "GET"
    }
  ]
}