Checkout
extends AbstractCartRoute
in package
Uses
DraftOrderTrait, CheckoutTrait
Checkout class.
Table of Contents
- IDENTIFIER = 'checkout'
- The route identifier.
- SCHEMA_TYPE = 'checkout'
- The routes schema.
- SCHEMA_VERSION = 1
- The routes schema version.
- $additional_fields_controller : CheckoutFields
- Additional fields controller class instance.
- $cart_controller : CartController
- Cart controller class instance.
- $cart_item_schema : CartItemSchema
- Schema class for the cart item.
- $cart_schema : CartSchema
- Schema class for the cart.
- $has_cart_token : bool|null
- True when this route has been requested with a valid cart token.
- $namespace : string
- Route namespace.
- $order_controller : OrderController
- Order controller class instance.
- $schema : AbstractSchema
- Schema class instance.
- $schema_controller : SchemaController
- Schema Controller instance.
- $order : WC_Order|null
- Holds the current order being processed. Null until `create_or_update_draft_order()` materialises it (either by reusing the session's pending/failed order or by creating a new one from the cart).
- __construct() : mixed
- Constructor.
- get_args() : array<string|int, mixed>
- Get method arguments for this REST route.
- get_collection_params() : array<string|int, mixed>
- Retrieves the query params for the collections.
- get_document_object_from_rest_request() : DocumentObject
- Returns a document object from a REST request.
- get_item_schema() : array<string|int, mixed>
- Get item schema properties.
- get_namespace() : string
- Get the namespace for this route.
- get_path() : string
- Get the path of this REST route.
- get_path_regex() : string
- Get the path of this rest route.
- get_response() : WP_REST_Response
- Get the route response based on the type of request.
- prepare_item_for_response() : WP_REST_Response
- Prepare a single item for response.
- set_namespace() : mixed
- Set the namespace for this route.
- validate_callback() : true|WP_Error
- Validation callback for the checkout route.
- add_response_headers() : WP_REST_Response
- Add nonce headers to a response object.
- cart_updated() : mixed
- Triggered after an update to cart data. Re-calculates totals and updates draft orders (if they already exist) to keep all data in sync.
- check_nonce() : WP_Error|bool
- For non-GET endpoints, require and validate a nonce to prevent CSRF attacks.
- error_to_response() : WP_REST_Response
- Converts an error to a response object. Based on \WP_REST_Server.
- get_cart_token() : string
- Generates a cart token for the response headers.
- get_context_param() : array<string|int, mixed>
- Retrieves the context param.
- get_draft_order() : WC_Order|null
- Uses the draft order ID to return an order object, if valid.
- get_draft_order_id() : int
- Gets draft order data from the customer session.
- get_response_by_request_method() : WP_REST_Response
- Get the route response based on the type of request.
- get_route_delete_response() : WP_REST_Response
- Get route response for DELETE requests.
- get_route_error_response() : WP_Error
- Get route response when something went wrong.
- get_route_error_response_from_object() : WP_Error
- Get route response when something went wrong.
- get_route_post_response() : WP_REST_Response|WP_Error
- Process an order.
- get_route_response() : WP_REST_Response
- Return a checkout response for GET requests.
- get_route_update_response() : WP_REST_Response|WP_Error
- Get route response for PUT/PATCH requests.
- has_cart_token() : bool
- Checks if the request has a valid cart token.
- is_update_request() : bool
- Are we updating data or getting data?
- is_valid_draft_order() : bool
- Whether the passed argument is a draft order or an order that is pending/failed and the cart hasn't changed.
- load_cart_session() : mixed
- Load the cart session before handling responses.
- prepare_links() : array<string|int, mixed>
- Prepare links for the request.
- prepare_response_for_collection() : array<string|int, mixed>|mixed
- Prepares a response for insertion into a collection.
- requires_nonce() : bool
- Checks if a nonce is required for the route.
- set_draft_order_id() : mixed
- Updates draft order data in the customer session.
- add_data_to_error_object() : mixed
- Adds additional data to the \WP_Error object.
- build_draft_route_response() : WP_REST_Response
- Build a checkout response for a session with no order in flight.
- create_or_update_draft_order() : mixed
- Create or update a draft order based on the cart.
- get_order_or_throw() : WC_Order
- Returns the order being processed, throwing if it hasn't been materialised yet.
- get_request_payment_data() : array<string|int, mixed>
- Gets and formats payment request data.
- get_request_payment_method() : WC_Payment_Gateway|null
- Gets the chosen payment method from the request.
- get_request_payment_method_id() : string
- Gets the chosen payment method ID from the request.
- get_request_payment_method_title() : string
- Gets the chosen payment method title from the request.
- persist_additional_fields_for_customer() : void
- Persist additional fields for the customer session.
- persist_additional_fields_for_order() : mixed
- Persist additional fields for the order after validating them.
- process_customer() : mixed
- Order processing relating to customer account.
- process_order() : WP_REST_Response|WP_Error
- Process an order based on optimistic save approach to minimize the number of order saves.
- process_payment() : mixed
- Fires an action hook instructing active payment gateways to process the payment for an order and provide a result.
- process_without_payment() : mixed
- For orders which do not require payment, just update status.
- resolve_and_persist_additional_fields() : void
- Resolve the additional checkout fields from the request and persist each one via the supplied callback. Fields hidden by conditional logic that were still posted are cleared (passed with an empty value).
- should_create_customer_account() : bool
- Check request options and store (shop) config to determine if a user account should be created as part of order processing.
- update_customer_address_field() : mixed
- Updates a customer address field.
- update_customer_from_request() : mixed
- Updates the current customer session using data from the request (e.g. address data).
- update_order_from_request() : mixed
- Update the current order using the posted values from the request.
- update_session_from_request() : void
- Persist the PATCH request's payment method and additional fields to the customer session. Counterpart to `update_order_from_request` for the no-order PATCH path.
- validate_user_can_place_order() : mixed
- This validates if the order can be placed regarding settings in WooCommerce > Settings > Accounts & Privacy If registration during checkout is disabled, guest checkout is disabled and the user is not logged in, prevent checkout.
Constants
IDENTIFIER
The route identifier.
public
string
IDENTIFIER
= 'checkout'
SCHEMA_TYPE
The routes schema.
public
string
SCHEMA_TYPE
= 'checkout'
SCHEMA_VERSION
The routes schema version.
public
int
SCHEMA_VERSION
= 1
Properties
$additional_fields_controller
Additional fields controller class instance.
protected
CheckoutFields
$additional_fields_controller
$cart_controller
Cart controller class instance.
protected
CartController
$cart_controller
$cart_item_schema
Schema class for the cart item.
protected
CartItemSchema
$cart_item_schema
$cart_schema
Schema class for the cart.
protected
CartSchema
$cart_schema
$has_cart_token
True when this route has been requested with a valid cart token.
protected
bool|null
$has_cart_token
= null
$namespace
Route namespace.
protected
string
$namespace
= 'wc/store/v1'
$order_controller
Order controller class instance.
protected
OrderController
$order_controller
$schema
Schema class instance.
protected
AbstractSchema
$schema
$schema_controller
Schema Controller instance.
protected
SchemaController
$schema_controller
$order
Holds the current order being processed. Null until `create_or_update_draft_order()` materialises it (either by reusing the session's pending/failed order or by creating a new one from the cart).
private
WC_Order|null
$order
= null
Methods
__construct()
Constructor.
public
__construct(SchemaController $schema_controller, AbstractSchema $schema) : mixed
Parameters
- $schema_controller : SchemaController
-
Schema Controller instance.
- $schema : AbstractSchema
-
Schema class for this route.
Return values
mixed —get_args()
Get method arguments for this REST route.
public
get_args() : array<string|int, mixed>
Return values
array<string|int, mixed> — An array of endpoints.get_collection_params()
Retrieves the query params for the collections.
public
get_collection_params() : array<string|int, mixed>
Return values
array<string|int, mixed> — Query parameters for the collection.get_document_object_from_rest_request()
Returns a document object from a REST request.
public
get_document_object_from_rest_request(WP_REST_Request $request) : DocumentObject
Parameters
- $request : WP_REST_Request
-
The REST request.
Return values
DocumentObject — The document object or null if experimental blocks are not enabled.get_item_schema()
Get item schema properties.
public
get_item_schema() : array<string|int, mixed>
Return values
array<string|int, mixed> —get_namespace()
Get the namespace for this route.
public
get_namespace() : string
Return values
string —get_path()
Get the path of this REST route.
public
get_path() : string
Return values
string —get_path_regex()
Get the path of this rest route.
public
static get_path_regex() : string
Return values
string —get_response()
Get the route response based on the type of request.
public
get_response(WP_REST_Request $request) : WP_REST_Response
Parameters
- $request : WP_REST_Request
-
Request object.
Return values
WP_REST_Response —prepare_item_for_response()
Prepare a single item for response.
public
prepare_item_for_response(mixed $item, WP_REST_Request $request) : WP_REST_Response
Parameters
- $item : mixed
-
Item to format to schema.
- $request : WP_REST_Request
-
Request object.
Return values
WP_REST_Response — $response Response data.set_namespace()
Set the namespace for this route.
public
set_namespace(string $namespace) : mixed
Parameters
- $namespace : string
-
Given namespace.
Return values
mixed —validate_callback()
Validation callback for the checkout route.
public
validate_callback(WP_REST_Request $request) : true|WP_Error
This runs after individual field validation_callbacks have been called.
Parameters
- $request : WP_REST_Request
-
Request object.
Return values
true|WP_Error —add_response_headers()
Add nonce headers to a response object.
protected
add_response_headers(WP_REST_Response $response) : WP_REST_Response
Parameters
- $response : WP_REST_Response
-
The response object.
Return values
WP_REST_Response —cart_updated()
Triggered after an update to cart data. Re-calculates totals and updates draft orders (if they already exist) to keep all data in sync.
protected
cart_updated(WP_REST_Request $request) : mixed
Parameters
- $request : WP_REST_Request
-
Request object.
Return values
mixed —check_nonce()
For non-GET endpoints, require and validate a nonce to prevent CSRF attacks.
protected
check_nonce(WP_REST_Request $request) : WP_Error|bool
Nonces will mismatch if the logged in session cookie is different! If using a client to test, set this cookie to match the logged in cookie in your browser.
Parameters
- $request : WP_REST_Request
-
Request object.
Return values
WP_Error|bool —error_to_response()
Converts an error to a response object. Based on \WP_REST_Server.
protected
error_to_response(WP_Error $error) : WP_REST_Response
Parameters
- $error : WP_Error
-
WP_Error instance.
Return values
WP_REST_Response — List of associative arrays with code and message keys.get_cart_token()
Generates a cart token for the response headers.
protected
get_cart_token() : string
Current namespace is used as the token Issuer. *
Return values
string —get_context_param()
Retrieves the context param.
protected
get_context_param([array<string|int, mixed> $args = array() ]) : array<string|int, mixed>
Ensures consistent descriptions between endpoints, and populates enum from schema.
Parameters
- $args : array<string|int, mixed> = array()
-
Optional. Additional arguments for context parameter. Default empty array.
Return values
array<string|int, mixed> — Context parameter details.get_draft_order()
Uses the draft order ID to return an order object, if valid.
protected
get_draft_order() : WC_Order|null
Return values
WC_Order|null —get_draft_order_id()
Gets draft order data from the customer session.
protected
get_draft_order_id() : int
Return values
int —get_response_by_request_method()
Get the route response based on the type of request.
protected
get_response_by_request_method(WP_REST_Request $request) : WP_REST_Response
Parameters
- $request : WP_REST_Request
-
Request object.
Return values
WP_REST_Response —get_route_delete_response()
Get route response for DELETE requests.
protected
get_route_delete_response(WP_REST_Request $request) : WP_REST_Response
When implemented, should return a \WP_REST_Response.
Parameters
- $request : WP_REST_Request
-
Request object.
Tags
Return values
WP_REST_Response —get_route_error_response()
Get route response when something went wrong.
protected
get_route_error_response(string $error_code, string $error_message[, int $http_status_code = 500 ][, array<string|int, mixed> $additional_data = [] ]) : WP_Error
Parameters
- $error_code : string
-
String based error code.
- $error_message : string
-
User facing error message.
- $http_status_code : int = 500
-
HTTP status. Defaults to 500.
- $additional_data : array<string|int, mixed> = []
-
Extra data (key value pairs) to expose in the error response.
Return values
WP_Error — WP Error object.get_route_error_response_from_object()
Get route response when something went wrong.
protected
get_route_error_response_from_object(WP_Error $error_object[, int $http_status_code = 500 ][, array<string|int, mixed> $additional_data = [] ]) : WP_Error
Parameters
- $error_object : WP_Error
-
User facing error message.
- $http_status_code : int = 500
-
HTTP status. Defaults to 500.
- $additional_data : array<string|int, mixed> = []
-
Extra data (key value pairs) to expose in the error response.
Return values
WP_Error — WP Error object.get_route_post_response()
Process an order.
protected
get_route_post_response(WP_REST_Request<string|int, array<string, mixed>> $request) : WP_REST_Response|WP_Error
Parameters
- $request : WP_REST_Request<string|int, array<string, mixed>>
-
Request object.
Tags
Return values
WP_REST_Response|WP_Error —get_route_response()
Return a checkout response for GET requests.
protected
get_route_response(WP_REST_Request $request) : WP_REST_Response
If a pending/failed order from a previous payment attempt is in the customer
session, reuse it (the failed-payment retry path). Otherwise build a no-order
response directly from cart + customer + request.
Parameters
- $request : WP_REST_Request
-
Request object.
Tags
Return values
WP_REST_Response —get_route_update_response()
Get route response for PUT/PATCH requests.
protected
get_route_update_response(WP_REST_Request $request) : WP_REST_Response|WP_Error
Branches on whether a pending/failed order already exists in the customer's session:
- Order in session (failed-payment retry): update the existing order via
create_or_update_draft_order()+update_order_from_request(). Same shape as the POST flow. - No order in session (fresh checkout form interaction): persist request
state to the customer session via
update_session_from_request()and return a no-order response built from cart + customer + request.
Draft order creation is deferred to POST (place-order time) to avoid
orphaned wc-checkout-draft rows from form interactions that never
complete. POSTs do not flow through this method — see
get_route_post_response().
Parameters
- $request : WP_REST_Request
-
Request object.
Tags
Return values
WP_REST_Response|WP_Error —has_cart_token()
Checks if the request has a valid cart token.
protected
has_cart_token(WP_REST_Request $request) : bool
Parameters
- $request : WP_REST_Request
-
Request object.
Return values
bool —is_update_request()
Are we updating data or getting data?
protected
is_update_request(WP_REST_Request $request) : bool
Parameters
- $request : WP_REST_Request
-
Request object.
Return values
bool —is_valid_draft_order()
Whether the passed argument is a draft order or an order that is pending/failed and the cart hasn't changed.
protected
is_valid_draft_order(WC_Order $order_object) : bool
Parameters
- $order_object : WC_Order
-
Order object to check.
Return values
bool — Whether the order is valid as a draft order.load_cart_session()
Load the cart session before handling responses.
protected
load_cart_session(WP_REST_Request $request) : mixed
Parameters
- $request : WP_REST_Request
-
Request object.
Return values
mixed —prepare_links()
Prepare links for the request.
protected
prepare_links(mixed $item, WP_REST_Request $request) : array<string|int, mixed>
Parameters
- $item : mixed
-
Item to prepare.
- $request : WP_REST_Request
-
Request object.
Return values
array<string|int, mixed> —prepare_response_for_collection()
Prepares a response for insertion into a collection.
protected
prepare_response_for_collection(WP_REST_Response $response) : array<string|int, mixed>|mixed
Parameters
- $response : WP_REST_Response
-
Response object.
Return values
array<string|int, mixed>|mixed — Response data, ready for insertion into collection data.requires_nonce()
Checks if a nonce is required for the route.
protected
requires_nonce(WP_REST_Request $request) : bool
Parameters
- $request : WP_REST_Request
-
Request.
Return values
bool —set_draft_order_id()
Updates draft order data in the customer session.
protected
set_draft_order_id(int $order_id) : mixed
Parameters
- $order_id : int
-
Draft order ID.
Return values
mixed —add_data_to_error_object()
Adds additional data to the \WP_Error object.
private
add_data_to_error_object(WP_Error $error, array<string|int, mixed> $data, int $http_status_code[, bool $include_cart = false ]) : mixed
Parameters
- $error : WP_Error
-
The error object to add the cart to.
- $data : array<string|int, mixed>
-
The data to add to the error object.
- $http_status_code : int
-
The HTTP status code this error should return.
- $include_cart : bool = false
-
Whether the cart should be included in the error data.
Tags
Return values
mixed —build_draft_route_response()
Build a checkout response for a session with no order in flight.
private
build_draft_route_response(WP_REST_Request $request) : WP_REST_Response
Parameters
- $request : WP_REST_Request
-
Request object.
Tags
Return values
WP_REST_Response —create_or_update_draft_order()
Create or update a draft order based on the cart.
private
create_or_update_draft_order(WP_REST_Request $request) : mixed
Parameters
- $request : WP_REST_Request
-
Full details about the request.
Tags
Return values
mixed —get_order_or_throw()
Returns the order being processed, throwing if it hasn't been materialised yet.
private
get_order_or_throw() : WC_Order
Use the returned WC_Order (rather than $this->order) for type-safe access in
the rest of the calling method.
Tags
Return values
WC_Order —get_request_payment_data()
Gets and formats payment request data.
private
get_request_payment_data(WP_REST_Request $request) : array<string|int, mixed>
Parameters
- $request : WP_REST_Request
-
Request object.
Return values
array<string|int, mixed> —get_request_payment_method()
Gets the chosen payment method from the request.
private
get_request_payment_method(WP_REST_Request $request) : WC_Payment_Gateway|null
Parameters
- $request : WP_REST_Request
-
Request object.
Tags
Return values
WC_Payment_Gateway|null —get_request_payment_method_id()
Gets the chosen payment method ID from the request.
private
get_request_payment_method_id(WP_REST_Request $request) : string
Parameters
- $request : WP_REST_Request
-
Request object.
Tags
Return values
string —get_request_payment_method_title()
Gets the chosen payment method title from the request.
private
get_request_payment_method_title(WP_REST_Request $request) : string
Parameters
- $request : WP_REST_Request
-
Request object.
Tags
Return values
string —persist_additional_fields_for_customer()
Persist additional fields for the customer session.
private
persist_additional_fields_for_customer(WP_REST_Request $request) : void
Counterpart to persist_additional_fields_for_order for routes that operate
without a persisted order (e.g. the deferred-draft PATCH path).
Parameters
- $request : WP_REST_Request
-
Full details about the request.
Tags
Return values
void —persist_additional_fields_for_order()
Persist additional fields for the order after validating them.
private
persist_additional_fields_for_order(WP_REST_Request $request) : mixed
Parameters
- $request : WP_REST_Request
-
Full details about the request.
Tags
Return values
mixed —process_customer()
Order processing relating to customer account.
private
process_customer(WP_REST_Request $request) : mixed
Creates a customer account as needed (based on request & store settings) and updates the order with the new customer ID. Updates the order with user details (e.g. address).
Parameters
- $request : WP_REST_Request
-
Request object.
Tags
Return values
mixed —process_order()
Process an order based on optimistic save approach to minimize the number of order saves.
private
process_order(WP_REST_Request<string|int, array<string, mixed>> $request) : WP_REST_Response|WP_Error
- Obtain Draft Order
- Process Request
- Process Customer
- Validate Order
- Process Payment
Parameters
- $request : WP_REST_Request<string|int, array<string, mixed>>
-
Request object.
Tags
Return values
WP_REST_Response|WP_Error —process_payment()
Fires an action hook instructing active payment gateways to process the payment for an order and provide a result.
private
process_payment(WP_REST_Request $request, PaymentResult $payment_result) : mixed
Parameters
- $request : WP_REST_Request
-
Request object.
- $payment_result : PaymentResult
-
Payment result object.
Tags
Return values
mixed —process_without_payment()
For orders which do not require payment, just update status.
private
process_without_payment(WP_REST_Request $request, PaymentResult $payment_result) : mixed
Parameters
- $request : WP_REST_Request
-
Request object.
- $payment_result : PaymentResult
-
Payment result object.
Tags
Return values
mixed —resolve_and_persist_additional_fields()
Resolve the additional checkout fields from the request and persist each one via the supplied callback. Fields hidden by conditional logic that were still posted are cleared (passed with an empty value).
private
resolve_and_persist_additional_fields(WP_REST_Request $request, callable $persist) : void
Parameters
- $request : WP_REST_Request
-
Full details about the request.
- $persist : callable
-
Callback invoked as
$persist( string $key, mixed $value )for each field.
Tags
Return values
void —should_create_customer_account()
Check request options and store (shop) config to determine if a user account should be created as part of order processing.
private
should_create_customer_account(WP_REST_Request $request) : bool
Parameters
- $request : WP_REST_Request
-
The current request object being handled.
Return values
bool — True if a new user account should be created.update_customer_address_field()
Updates a customer address field.
private
update_customer_address_field(WC_Customer $customer, string $key, mixed $value, string $address_type) : mixed
Parameters
- $customer : WC_Customer
-
The customer to update.
- $key : string
-
The key of the field to update.
- $value : mixed
-
The value to update the field to.
- $address_type : string
-
The type of address to update (billing|shipping).
Return values
mixed —update_customer_from_request()
Updates the current customer session using data from the request (e.g. address data).
private
update_customer_from_request(WP_REST_Request $request) : mixed
Address session data is synced to the order itself later on by OrderController::update_order_from_cart()
Parameters
- $request : WP_REST_Request
-
Full details about the request.
Return values
mixed —update_order_from_request()
Update the current order using the posted values from the request.
private
update_order_from_request(WP_REST_Request $request[, bool $persist = true ]) : mixed
Called only with a real, persisted order — either the place-order POST flow or
the rare failed-payment PATCH retry flow where get_draft_order() resolved to
an existing pending/failed order from the customer's session. Fresh-session
PATCHes never call this method; they go through the no-order draft path.
Parameters
- $request : WP_REST_Request
-
Full details about the request.
- $persist : bool = true
-
Whether to persist the changes right away (defaults to true).
Tags
Return values
mixed —update_session_from_request()
Persist the PATCH request's payment method and additional fields to the customer session. Counterpart to `update_order_from_request` for the no-order PATCH path.
private
update_session_from_request(WP_REST_Request $request) : void
Parameters
- $request : WP_REST_Request
-
Request object.
Tags
Return values
void —validate_user_can_place_order()
This validates if the order can be placed regarding settings in WooCommerce > Settings > Accounts & Privacy If registration during checkout is disabled, guest checkout is disabled and the user is not logged in, prevent checkout.
private
validate_user_can_place_order() : mixed