Orders

June 5, 2026 · View on GitHub

Use the /orders resource to create, update, retrieve, authorize, capture and track orders.

OrdersController ordersController = client.getOrdersController();

Create Order

Creates an order. Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see checkout or multiparty checkout. Note: For error handling and troubleshooting, see Orders v2 errors.

CompletableFuture<ApiResponse<Order>> createOrderAsync(
    final CreateOrderInput input)

Authentication

This endpoint requires Oauth2

Parameters

Parameter	Type	Tags	Description
`input`	`CreateOrderInput`	Required	Input structure for the method CreateOrderAsync

Response Type

200: A successful response to an idempotent request returns the HTTP 200 OK status code with a JSON response body that shows order details.

This method returns an ApiResponse instance. The getResult() getter of this instance returns the response data which is of type Order.

Example Usage

CreateOrderInput createOrderInput = new CreateOrderInput.Builder(
    null,
    new OrderRequest.Builder(
        CheckoutPaymentIntent.CAPTURE,
        Arrays.asList(
            new PurchaseUnitRequest.Builder(
                new AmountWithBreakdown.Builder(
                    "currency_code6",
                    "value0"
                )
                .build()
            )
            .build()
        )
    )
    .build()
)
.prefer("return=minimal")
.build();

ordersController.createOrderAsync(createOrderInput).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    Throwable cause = exception.getCause();

    if (cause instanceof ErrorException) {
        ErrorException errorException = (ErrorException) cause;
        errorException.printStackTrace();
    } else {
        // fallback for unexpected errors
        exception.printStackTrace();
    }

    return null;
});

Errors

HTTP Status Code	Error Description	Exception Class
400	Request is not well-formed, syntactically incorrect, or violates schema.	`ErrorException`
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	`ErrorException`
422	The requested action could not be performed, semantically incorrect, or failed business validation.	`ErrorException`
Default	The error response.	`ErrorException`

Get Order

Shows details for an order, by ID. Note: For error handling and troubleshooting, see Orders v2 errors.

CompletableFuture<ApiResponse<Order>> getOrderAsync(
    final GetOrderInput input)

Authentication

This endpoint requires Oauth2

Parameters

Parameter	Type	Tags	Description
`input`	`GetOrderInput`	Required	Input structure for the method GetOrderAsync

Response Type

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

This method returns an ApiResponse instance. The getResult() getter of this instance returns the response data which is of type Order.

Example Usage

GetOrderInput getOrderInput = new GetOrderInput.Builder(
    "id0"
)
.build();

ordersController.getOrderAsync(getOrderInput).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    Throwable cause = exception.getCause();

    if (cause instanceof ErrorException) {
        ErrorException errorException = (ErrorException) cause;
        errorException.printStackTrace();
    } else {
        // fallback for unexpected errors
        exception.printStackTrace();
    }

    return null;
});

Errors

HTTP Status Code	Error Description	Exception Class
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	`ErrorException`
404	The specified resource does not exist.	`ErrorException`
Default	The error response.	`ErrorException`

Patch Order

Updates an order with a CREATED or APPROVED status. You cannot update an order with the COMPLETED status.

To make an update, you must 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}". Merchants and partners can add Level 2 and 3 data to payments to reduce risk and payment processing costs. For more information about processing payments, see checkout or multiparty checkout.

Note: For error handling and troubleshooting, see Orders v2 errors.

Patchable attributes or objects:

Attribute	Op	Notes
`intent`	replace
`payer`	replace, add	Using replace op for `payer` will replace the whole `payer` object with the value sent in 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_units[].payment_instruction.platform_fees`	replace, add, remove
`purchase_units[].supplementary_data.airline`	replace, add, remove
`purchase_units[].supplementary_data.card`	replace, add, remove
`application_context.client_configuration`	replace, add

CompletableFuture<ApiResponse<Void>> patchOrderAsync(
    final PatchOrderInput input)

Authentication

This endpoint requires Oauth2

Parameters

Parameter	Type	Tags	Description
`input`	`PatchOrderInput`	Required	Input structure for the method PatchOrderAsync

Response Type

204: A successful request returns the HTTP 204 No Content status code with an empty object in the JSON response body.

void

Example Usage

PatchOrderInput patchOrderInput = new PatchOrderInput.Builder(
    "id0",
    null
)
.body(Arrays.asList(
        new Patch.Builder(
            PatchOp.ADD
        )
        .build()
    ))
.build();

ordersController.patchOrderAsync(patchOrderInput).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    Throwable cause = exception.getCause();

    if (cause instanceof ErrorException) {
        ErrorException errorException = (ErrorException) cause;
        errorException.printStackTrace();
    } else {
        // fallback for unexpected errors
        exception.printStackTrace();
    }

    return null;
});

Errors

HTTP Status Code	Error Description	Exception Class
400	Request is not well-formed, syntactically incorrect, or violates schema.	`ErrorException`
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	`ErrorException`
404	The specified resource does not exist.	`ErrorException`
422	The requested action could not be performed, semantically incorrect, or failed business validation.	`ErrorException`
Default	The error response.	`ErrorException`

Confirm Order

Payer confirms their intent to pay for the the Order with the given payment source.

CompletableFuture<ApiResponse<Order>> confirmOrderAsync(
    final ConfirmOrderInput input)

Authentication

This endpoint requires Oauth2

Parameters

Parameter	Type	Tags	Description
`input`	`ConfirmOrderInput`	Required	Input structure for the method ConfirmOrderAsync

Response Type

200: A successful request indicates that the payment source was added to the Order. A successful request returns the HTTP 200 OK status code with a JSON response body that shows order details.

This method returns an ApiResponse instance. The getResult() getter of this instance returns the response data which is of type Order.

Example Usage

ConfirmOrderInput confirmOrderInput = new ConfirmOrderInput.Builder(
    "id0",
    null
)
.prefer("return=minimal")
.build();

ordersController.confirmOrderAsync(confirmOrderInput).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    Throwable cause = exception.getCause();

    if (cause instanceof ErrorException) {
        ErrorException errorException = (ErrorException) cause;
        errorException.printStackTrace();
    } else {
        // fallback for unexpected errors
        exception.printStackTrace();
    }

    return null;
});

Errors

HTTP Status Code	Error Description	Exception Class
400	Request is not well-formed, syntactically incorrect, or violates schema.	`ErrorException`
403	Authorization failed due to insufficient permissions.	`ErrorException`
422	The requested action could not be performed, semantically incorrect, or failed business validation.	`ErrorException`
500	An internal server error has occurred.	`ErrorException`
Default	The error response.	`ErrorException`

Authorize Order

Authorizes payment for an order. To successfully authorize payment for an order, the buyer must first approve the order or a valid payment_source must be provided in the request. A buyer can approve the order upon being redirected to the rel:approve URL that was returned in the HATEOAS links in the create order response. Note: For error handling and troubleshooting, see Orders v2 errors.

CompletableFuture<ApiResponse<OrderAuthorizeResponse>> authorizeOrderAsync(
    final AuthorizeOrderInput input)

Authentication

This endpoint requires Oauth2

Parameters

Parameter	Type	Tags	Description
`input`	`AuthorizeOrderInput`	Required	Input structure for the method AuthorizeOrderAsync

Response Type

200: A successful response to an idempotent request returns the HTTP 200 OK status code with a JSON response body that shows authorized payment details.

This method returns an ApiResponse instance. The getResult() getter of this instance returns the response data which is of type OrderAuthorizeResponse.

Example Usage

AuthorizeOrderInput authorizeOrderInput = new AuthorizeOrderInput.Builder(
    "id0",
    null
)
.prefer("return=minimal")
.build();

ordersController.authorizeOrderAsync(authorizeOrderInput).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    Throwable cause = exception.getCause();

    if (cause instanceof ErrorException) {
        ErrorException errorException = (ErrorException) cause;
        errorException.printStackTrace();
    } else {
        // fallback for unexpected errors
        exception.printStackTrace();
    }

    return null;
});

Errors

HTTP Status Code	Error Description	Exception Class
400	Request is not well-formed, syntactically incorrect, or violates schema.	`ErrorException`
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	`ErrorException`
403	The authorized payment failed due to insufficient permissions.	`ErrorException`
404	The specified resource does not exist.	`ErrorException`
422	The requested action could not be performed, semantically incorrect, or failed business validation.	`ErrorException`
500	An internal server error has occurred.	`ErrorException`
Default	The error response.	`ErrorException`

Capture Order

Captures payment for an order. To successfully capture payment for an order, the buyer must first approve the order or a valid payment_source must be provided in the request. A buyer can approve the order upon being redirected to the rel:approve URL that was returned in the HATEOAS links in the create order response. Note: For error handling and troubleshooting, see Orders v2 errors.

CompletableFuture<ApiResponse<Order>> captureOrderAsync(
    final CaptureOrderInput input)

Authentication

This endpoint requires Oauth2

Parameters

Parameter	Type	Tags	Description
`input`	`CaptureOrderInput`	Required	Input structure for the method CaptureOrderAsync

Response Type

200: A successful response to an idempotent request returns the HTTP 200 OK status code with a JSON response body that shows captured payment details.

This method returns an ApiResponse instance. The getResult() getter of this instance returns the response data which is of type Order.

Example Usage

CaptureOrderInput captureOrderInput = new CaptureOrderInput.Builder(
    "id0",
    null
)
.prefer("return=minimal")
.build();

ordersController.captureOrderAsync(captureOrderInput).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    Throwable cause = exception.getCause();

    if (cause instanceof ErrorException) {
        ErrorException errorException = (ErrorException) cause;
        errorException.printStackTrace();
    } else {
        // fallback for unexpected errors
        exception.printStackTrace();
    }

    return null;
});

Errors

HTTP Status Code	Error Description	Exception Class
400	Request is not well-formed, syntactically incorrect, or violates schema.	`ErrorException`
401	Authentication failed due to missing authorization header, or invalid authentication credentials.	`ErrorException`
403	The authorized payment failed due to insufficient permissions.	`ErrorException`
404	The specified resource does not exist.	`ErrorException`
422	The requested action could not be performed, semantically incorrect, or failed business validation.	`ErrorException`
500	An internal server error has occurred.	`ErrorException`
Default	The error response.	`ErrorException`

Create Order Tracking

Adds tracking information for an Order.

CompletableFuture<ApiResponse<Order>> createOrderTrackingAsync(
    final CreateOrderTrackingInput input)

Authentication

This endpoint requires Oauth2

Parameters

Parameter	Type	Tags	Description
`input`	`CreateOrderTrackingInput`	Required	Input structure for the method CreateOrderTrackingAsync

Response Type

200: A successful response to an idempotent request returns the HTTP 200 OK status code with a JSON response body that shows tracker details.

This method returns an ApiResponse instance. The getResult() getter of this instance returns the response data which is of type Order.

Example Usage

CreateOrderTrackingInput createOrderTrackingInput = new CreateOrderTrackingInput.Builder(
    "id0",
    null,
    new OrderTrackerRequest.Builder(
        "capture_id8"
    )
    .notifyPayer(false)
    .build()
)
.build();

ordersController.createOrderTrackingAsync(createOrderTrackingInput).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    Throwable cause = exception.getCause();

    if (cause instanceof ErrorException) {
        ErrorException errorException = (ErrorException) cause;
        errorException.printStackTrace();
    } else {
        // fallback for unexpected errors
        exception.printStackTrace();
    }

    return null;
});

Errors

HTTP Status Code	Error Description	Exception Class
400	Request is not well-formed, syntactically incorrect, or violates schema.	`ErrorException`
403	Authorization failed due to insufficient permissions.	`ErrorException`
404	The specified resource does not exist.	`ErrorException`
422	The requested action could not be performed, semantically incorrect, or failed business validation.	`ErrorException`
500	An internal server error has occurred.	`ErrorException`
Default	The error response.	`ErrorException`

Update Order Tracking

Updates or cancels the tracking information for a PayPal order, by ID. Updatable attributes or objects: Attribute Op Notes items replace Using replace op for items will replace the entire items object with the value sent in request. notify_payer replace, add status replace Only patching status to CANCELLED is currently supported.

CompletableFuture<ApiResponse<Void>> updateOrderTrackingAsync(
    final UpdateOrderTrackingInput input)

Authentication

This endpoint requires Oauth2

Parameters

Parameter	Type	Tags	Description
`input`	`UpdateOrderTrackingInput`	Required	Input structure for the method UpdateOrderTrackingAsync

Response Type

204: A successful request returns the HTTP 204 No Content status code with an empty object in the JSON response body.

void

Example Usage

UpdateOrderTrackingInput updateOrderTrackingInput = new UpdateOrderTrackingInput.Builder(
    "id0",
    "tracker_id2",
    null
)
.body(Arrays.asList(
        new Patch.Builder(
            PatchOp.ADD
        )
        .build()
    ))
.build();

ordersController.updateOrderTrackingAsync(updateOrderTrackingInput).thenAccept(result -> {
    // TODO success callback handler
    System.out.println(result);
}).exceptionally(exception -> {
    Throwable cause = exception.getCause();

    if (cause instanceof ErrorException) {
        ErrorException errorException = (ErrorException) cause;
        errorException.printStackTrace();
    } else {
        // fallback for unexpected errors
        exception.printStackTrace();
    }

    return null;
});

Errors

HTTP Status Code	Error Description	Exception Class
400	Request is not well-formed, syntactically incorrect, or violates schema.	`ErrorException`
403	Authorization failed due to insufficient permissions.	`ErrorException`
404	The specified resource does not exist.	`ErrorException`
422	The requested action could not be performed, semantically incorrect, or failed business validation.	`ErrorException`
500	An internal server error has occurred.	`ErrorException`
Default	The error response.	`ErrorException`