Receive updated order information via callback URL

The documentation for this ‘endpoint’ is different from the other endpoints under v2 Orders. For this endpoint the role of client and server is reversed. The client sending the request is PayPal, and the server sending the response is the merchant. In the request, PayPal will send the buyer’s redacted shipping address and selected shipping option to the callback URL defined the create order request. The response from the merchant will update the Orders resource.

POST /v2/checkout/orders/order-update-callback

Receive updated order information via callback URL

cURL

curl --request POST \
  --url https://api-m.sandbox.paypal.com/v2/checkout/orders/order-update-callback \
  --header 'Content-Type: application/json' \
  --data '
{
  "shipping_address": {
    "country_code": "<string>",
    "admin_area_2": "<string>",
    "admin_area_1": "<string>",
    "postal_code": "<string>"
  },
  "purchase_units": [
    {
      "amount": {
        "currency_code": "<string>",
        "value": "<string>",
        "breakdown": {
          "item_total": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "shipping": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "handling": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "tax_total": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "insurance": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "shipping_discount": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "discount": {
            "currency_code": "<string>",
            "value": "<string>"
          }
        }
      },
      "reference_id": "<string>",
      "payee": {
        "email_address": "<string>",
        "merchant_id": "<string>"
      },
      "payment_instruction": {
        "platform_fees": [
          {
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "payee": {
              "email_address": "<string>",
              "merchant_id": "<string>"
            }
          }
        ],
        "disbursement_mode": "INSTANT",
        "payee_pricing_tier_id": "<string>",
        "payee_receivable_fx_rate_id": "<string>"
      },
      "description": "<string>",
      "custom_id": "<string>",
      "invoice_id": "<string>",
      "soft_descriptor": "<string>",
      "items": [
        {
          "name": "<string>",
          "unit_amount": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "quantity": "<string>",
          "tax": {
            "currency_code": "<string>",
            "value": "<string>"
          },
          "description": "<string>",
          "sku": "<string>",
          "url": "<string>",
          "category": "DIGITAL_GOODS",
          "image_url": "<string>",
          "upc": {
            "type": "UPC-A",
            "code": "<string>"
          },
          "billing_plan": {
            "billing_cycles": [
              {
                "tenure_type": "REGULAR",
                "pricing_scheme": {
                  "pricing_model": "FIXED",
                  "price": {
                    "currency_code": "<string>",
                    "value": "<string>"
                  },
                  "reload_threshold_amount": {
                    "currency_code": "<string>",
                    "value": "<string>"
                  }
                },
                "frequency": "<unknown>",
                "total_cycles": 1,
                "sequence": 1,
                "start_date": "<string>"
              }
            ],
            "setup_fee": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "name": "<string>"
          }
        }
      ],
      "shipping": {
        "name": {
          "full_name": "<string>"
        },
        "email_address": "<string>",
        "phone_number": {
          "country_code": "<string>",
          "national_number": "<string>"
        },
        "type": "SHIPPING",
        "options": [
          {
            "id": "<string>",
            "label": "<string>",
            "selected": true,
            "type": "SHIPPING",
            "amount": {
              "currency_code": "<string>",
              "value": "<string>"
            }
          }
        ],
        "address": {
          "country_code": "<string>",
          "address_line_1": "<string>",
          "address_line_2": "<string>",
          "admin_area_2": "<string>",
          "admin_area_1": "<string>",
          "postal_code": "<string>"
        }
      },
      "supplementary_data": {
        "card": {
          "level_2": {
            "invoice_id": "<string>",
            "tax_total": {
              "currency_code": "<string>",
              "value": "<string>"
            }
          },
          "level_3": {
            "shipping_amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "duty_amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "discount_amount": {
              "currency_code": "<string>",
              "value": "<string>"
            },
            "shipping_address": {
              "country_code": "<string>",
              "address_line_1": "<string>",
              "address_line_2": "<string>",
              "admin_area_2": "<string>",
              "admin_area_1": "<string>",
              "postal_code": "<string>"
            },
            "ships_from_postal_code": "<string>",
            "line_items": [
              {
                "name": "<string>",
                "quantity": "<string>",
                "description": "<string>",
                "sku": "<string>",
                "url": "<string>",
                "image_url": "<string>",
                "upc": {
                  "type": "UPC-A",
                  "code": "<string>"
                },
                "billing_plan": {
                  "billing_cycles": [
                    {
                      "tenure_type": "REGULAR",
                      "pricing_scheme": {
                        "pricing_model": "FIXED",
                        "price": {
                          "currency_code": "<string>",
                          "value": "<string>"
                        },
                        "reload_threshold_amount": {
                          "currency_code": "<string>",
                          "value": "<string>"
                        }
                      },
                      "frequency": "<unknown>",
                      "total_cycles": 1,
                      "sequence": 1,
                      "start_date": "<string>"
                    }
                  ],
                  "setup_fee": {
                    "currency_code": "<string>",
                    "value": "<string>"
                  },
                  "name": "<string>"
                },
                "unit_amount": {
                  "currency_code": "<string>",
                  "value": "<string>"
                },
                "tax": {
                  "currency_code": "<string>",
                  "value": "<string>"
                },
                "commodity_code": "<string>",
                "discount_amount": {
                  "currency_code": "<string>",
                  "value": "<string>"
                },
                "total_amount": {
                  "currency_code": "<string>",
                  "value": "<string>"
                },
                "unit_of_measure": "<string>"
              }
            ]
          }
        },
        "risk": {
          "customer": {
            "ip_address": "<string>"
          }
        }
      }
    }
  ]
}
'

200

{
  "id": "<string>",
  "purchase_units": {
    "reference_id": "<string>",
    "amount": {
      "currency_code": "<string>",
      "value": "<string>",
      "breakdown": {
        "item_total": {
          "currency_code": "<string>",
          "value": "<string>"
        },
        "shipping": {
          "currency_code": "<string>",
          "value": "<string>"
        },
        "handling": {
          "currency_code": "<string>",
          "value": "<string>"
        },
        "tax_total": {
          "currency_code": "<string>",
          "value": "<string>"
        },
        "insurance": {
          "currency_code": "<string>",
          "value": "<string>"
        },
        "shipping_discount": {
          "currency_code": "<string>",
          "value": "<string>"
        },
        "discount": {
          "currency_code": "<string>",
          "value": "<string>"
        }
      }
    },
    "shipping_options": [
      {
        "id": "<string>",
        "label": "<string>",
        "selected": true,
        "type": "SHIPPING",
        "amount": {
          "currency_code": "<string>",
          "value": "<string>"
        }
      }
    ]
  }
}

Body

application/json

Shipping Options Callback request. This will be implemented by the merchants.

shipping_address · Portable Postal Address (Medium-Grained) · object · required

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

Show child attributes

purchase_units · Purchase Unit Request · object[] · required

An array of purchase units. At present only 1 purchase_unit is supported. Each purchase unit establishes a contract between a payer and the payee. Each purchase unit represents either a full or partial order that the payer intends to purchase from the payee.

Required array length: 1 element

Show child attributes

shipping_option · Shipping Option · object

The options that the payee or merchant offers to the payer to ship or pick up their items.

Show child attributes

Response

200

application/json

The callback to merchant was successful.

Returns the updated shipping options for an order.

id · string

The ID of the order.

Required string length: 1 - 36

purchase_units · Shipping Option and Amount data at Purchase Unit · object

This would contain shipping option and amount data at purchase unit level.

Show child attributes