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.

Authorization

AuthorizationBearer <token>

FlowClient CredentialsToken URLhttps://api-m.sandbox.paypal.com/v1/oauth2/tokenInheader

Scopes

Manage payments and checkout workflow.https://uri.paypal.com/services/payments/payment

Header Parameters

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

shipping_addressobject<address_portable>Optional

The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute).

address_portable properties

10 properties

address_line_1string<currency_code>Optional

The first line of the address, such as number and street, for example, `173 Drury Lane`. Needed for data entry, and Compliance and Risk checks. This field needs to pass the full address.

Match^[\S\s]*$Length0 <= length <= 300

address_line_2string<currency_code>Optional

The second line of the address, for example, a suite or apartment number.

Match^[\S\s]*$Length0 <= length <= 300

address_line_3string<currency_code>Optional

The third line of the address, if needed. Examples include a street complement for Brazil, direction text, such as `next to Walmart`, or a landmark in an Indian address.

Match^[\S\s]*$Length0 <= length <= 100

admin_area_4string<currency_code>Optional

The neighborhood, ward, or district. This is smaller than `admin_area_level_3` or `sub_locality`. Value is:

The postal sorting code that is used in Guernsey and many French territories, such as French Guiana.
The fine-grained administrative levels in China.

Match^[\S\s]*$Length0 <= length <= 100

admin_area_3string<currency_code>Optional

The sub-locality, suburb, neighborhood, or district. This is smaller than `admin_area_level_2`. Value is:

Brazil. Suburb, *bairro*, or neighborhood.
India. Sub-locality or district. Street name information isn't always available, but a sub-locality or district can be a very small area.

Match^[\S\s]*$Length0 <= length <= 100

admin_area_2string<currency_code>Optional

A city, town, or village. Smaller than `admin_area_level_1`.

Match^[\S\s]*$Length0 <= length <= 120

admin_area_1string<currency_code>Optional

The highest-level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. This data is formatted for postal delivery, for example, `CA` and not `California`. Value, by country, is:

UK. A county.
US. A state.
Canada. A province.
Japan. A prefecture.
Switzerland. A *kanton*.

Match^[\S\s]*$Length0 <= length <= 300

postal_codestring<currency_code>Optional

The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code).

Match^[\S\s]*$Length0 <= length <= 60

country_codestring<country_code>Required

The [2-character ISO 3166-1 code](/api/rest/reference/country-codes/) that identifies the country or region.

Note: The country code for Great Britain is GB and not UK as used in the top-level domain names for that country. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.

Match^([A-Z]{2}|C2)$Length2 <= length <= 2

address_detailsobject<Address Details>Optional

The non-portable additional address details include fine-grain address information for Compliance, Risk, and other scenarios. This isn't portable with common third-party and open source applications. This can include data that is redundant with core fields. For example, `address_portable.address_line_1` is usually a combination of `address_details.street_number`, `street_name`, and `street_type`.

shipping_optionobject<shipping_option>Optional

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

shipping_option properties

5 properties

idstring<currency_code>Required

A unique ID that identifies a payer-selected shipping option.

Match^[\S\s]*$Length0 <= length <= 127

labelstring<currency_code>Required

A description that the payer sees, which helps them choose an appropriate shipping option. For example, `Free Shipping`, `USPS Priority Shipping`, `Expédition prioritaire USPS`, or `USPS yōuxiān fā huò`. Localize this description to the payer's locale.

Match^[\S\s]*$Length0 <= length <= 127

typeenum<shipping_type>Optional

A classification for the method of purchase fulfillment.

Allowed values

"SHIPPING"Default
"PICKUP"
"PICKUP_IN_STORE"
"PICKUP_FROM_PERSON"

amountobject<money>Optional

The currency and amount for a financial transaction, such as a balance or payment due.

selectedbooleanRequired

If the API request sets `selected = true`, it represents the shipping option that the payee or merchant expects to be pre-selected for the payer when they first view the `shipping.options` in the PayPal Checkout experience. As part of the response if a `shipping.option` contains `selected=true`, it represents the shipping option that the payer selected during the course of checkout with PayPal. Only one `shipping.option` can be set to `selected=true`.

purchase_unitsobject<purchase_unit_request>[]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.

Items1 <= length <= 1

Response Body

`application/json`

curl -X POST "https://example.com/v2/checkout/orders/order-update-callback" \  -H "Authorization: Bearer A21AAGHr9qtiRRXH4oYcQokQgV99rGqEIfgrr8xHCclP0OzmD9KVgg5ppIIg1jzJgQkV4wd02svIvBJyg6cLFJjFow_SjBhxQ" \  -H "PayPal-Transmission-Id: 69cd13f0-d67a-11e5-baa3-778b53f4ae55" \  -H "PayPal-Transmission-Time: 2016-02-18T20:01:35Z" \  -H "PayPal-Cert-Url: https://api-m.paypal.com/v1/notifications/certs/CERT-1234567890" \  -H "PayPal-Transmission-Sig: lmI95Jx3Y9nhR5SJWlHVIWpg4AgFk7n9bCHSRxbrd8A9zrhdu2rMyFrmz+Zjh3s3boXB07VXCXUZy/UFzUlnGJn0wDugt7FlSvdKeIJenLRemUxYCPVoEZzg9VFNqOa48gMkvF+XTpxBeUx/kWy6B5cp7GkT2+pOowfRK7OaynuxUoKW3JcMWw272VKjLTtTAShncla7tGF+55rxyt2KNZIIqxNMJ48RDZheGU5w1npu9dZHnPgTXB9iomeVRoD8O/jhRpnKsGrDschyNdkeh81BJJMH4Ctc6lnCCquoP/GzCzz33MMsNdid7vL/NIWaCsekQpW26FpWPi/tfj8nLA==" \  -H "PayPal-Auth-Algo: SHA256withRSA" \  -H "Content-Type: application/json" \  -d '{    "id": "8HFTASDATTV",    "shipping_address": {      "country_code": "US",      "admin_area_1": "TX",      "admin_area_2": "Dallas",      "postal_code": "75001"    },    "purchase_units": [      {        "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",        "amount": {          "currency_code": "USD",          "value": "100.00"        }      }    ]  }'

{  "id": "8HFTASDATTV",  "purchase_units": {    "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",    "amount": {      "currency_code": "USD",      "value": "105.00",      "breakdown": {        "item_total": {          "currency_code": "USD",          "value": "100.00"        },        "tax_total": {          "currency_code": "USD",          "value": "5.00"        },        "shipping": {          "currency_code": "USD",          "value": "0.00"        }      }    },    "shipping_options": [      {        "id": "1",        "amount": {          "currency_code": "USD",          "value": "0.00"        },        "type": "SHIPPING",        "label": "Free Shipping",        "selected": true      },      {        "id": "2",        "amount": {          "currency_code": "USD",          "value": "7.00"        },        "type": "SHIPPING",        "label": "USPS Priority Shipping",        "selected": false      },      {        "id": "3",        "amount": {          "currency_code": "USD",          "value": "10.00"        },        "type": "SHIPPING",        "label": "1-Day Shipping",        "selected": false      }    ]  }}

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

Authorization

Header Parameters

Request Body

address_portable properties

Address Details properties

shipping_option properties

money properties

purchase_unit_request properties

amount_with_breakdown properties

amount_breakdown properties

money properties

money properties

money properties

money properties

money properties

money properties

discount_with_breakdown properties

payee properties

payment_instruction properties

platform_fee properties

money properties

payee_base properties

item_request properties

money properties

money properties

universal_product_code properties

order_billing_plan properties

billing_cycle properties

pricing_scheme properties

money properties

money properties

money properties

shipping_detail properties

name properties

phone properties

shipping_option properties

money properties

address_portable properties

Address Details properties

supplementary_data properties

card_supplementary_data properties

level_2_card_processing_data properties

money properties

level_3_card_processing_data properties

money properties

money properties

money properties

address_portable properties

Address Details properties

line_item properties

universal_product_code properties

order_billing_plan properties

billing_cycle properties

pricing_scheme properties

money properties

money properties

money properties

money properties

money properties

money properties

money properties

risk_supplementary_data properties

participant_metadata properties

Response Body

200application/json

400application/json

401application/json

403application/json

422application/json

500application/json

defaultapplication/json

Shipping Options Callback Request - Shipping Address Only Event

Shipping Options Callback Request - Shipping Address and Shipping Options Event

On this page

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`