Controller Actions

Commerce exposes a number of common resources to your storefront via an HTTP API.

We recommend reviewing the main Craft documentation on working with controller actions before you dig in, here!

# Available Actions

Action	Description
POST cart/complete	Completes an order without payment.
GET cart/get-cart	Returns the current cart as JSON.
GET/POST cart/load-cart	Loads a cookie for the given cart.
POST cart/update-cart	Manage a customer’s current cart.
GET downloads/pdf	Returns an order PDF as a file.
POST payment-sources/add	Creates a new payment source.
POST payment-sources/delete	Deletes a payment source.
GET payments/complete-payment	Processes customer’s return from an off-site payment.
POST payments/pay	Makes a payment on an order.

Address management actions are part of the main Craft documentation. Commerce also allows address information to be set directly on a cart via POST cart/update-cart.

# POST `cart/complete`

You can let your customers complete an order without a payment transaction. The allowCheckoutWithoutPayment setting must be enabled or an HTTP exception will be thrown.

The cart must have an email address and honor the following settings:

See the Making Payments page for more on using this action.

# Supported Params

Param	Description
`forceSave`	Optionally set to `true` to force saving the cart.
`number`	Optional order number for a specific, existing cart.
`registerUserOnOrderComplete`	Whether to create a user account for the customer when the cart is completed and turned into an order.

# Response

The output of the action depends on whether the cart was completed successfully and the Accept header.

State	`text/html`	`application/json`
	Standard behavior.	Standard behavior; cart data is available under a key determined by the cartVariable config setting.
	Standard behavior; cart is available in the template under a variable determined by the cartVariable.	Standard behavior; cart data is available under a key determined by the cartVariable config setting.

# GET `cart/get-cart`

Returns the current cart as JSON. A new cart cookie will be generated if one doesn’t already exist.

The request must include Accept: application/json in its headers.

# Supported Params

Param	Description
`number`	Optional order number for a specific, existing cart.
`forceSave`	Optionally set to `true` to force saving the cart.

# Response

State	`application/json`
	Standard behavior; cart data is available under a key determined by the cartVariable config setting.

# POST `cart/update-cart`

Updates the cart by adding or updating line items, and setting addresses and other cart attributes.

Read more about working with Addresses in Commerce.

# Supported Params

Param	Description
`billingAddress[]`	Billing address attributes. (See Addresses).
`billingAddressId`	ID of an existing address to use as the billing address.
`billingAddressSameAsShipping`	Set to `true` to use shipping address for billing address. (Will ignore billing address ID and fields.)
`clearNotices`	When passed, clears all cart notices.
`clearLineItems`	When passed, empties all line items from cart.
`couponCode`	Coupon code for a discount that should be applied to the cart.
`email`	Email address to be associated with the cart.
`estimatedBillingAddress[]`	Estimated billing address attributes. (See Addresses).
`estimatedBillingAddressSameAsShipping`	Set to `true` to use shipping address for estimated billing address.
`estimatedShippingAddress[]`	Estimated shipping address attributes. (See Addresses).
`fields[]`	Optional array of custom fields to be submitted to the cart.
`forceSave`	Optionally set to `true` to force saving the cart.
`gatewayId`	The payment gateway ID to be used when the cart is completed.
`lineItems[]`	Array of one or more of the cart’s line items to update. Each must have an `id` key-value pair, and may include `options`, `note`, and `qty` key-value pairs. An item may include a `remove` key with a value of `1` or a `qty` of `0` to be removed from the cart.
`number`	Optional order number for specific, existing cart.
`paymentCurrency`	ISO code of a configured payment currency to be used for the cart.
`paymentSourceId`	The ID for a payment source that should be used when the cart is completed.
`purchasableId`	Single purchasable ID to be added to the cart. If provided, will also use optional `note`, `options[]`, and `qty` parameters.
`purchasables[]`	Array of one or more purchasables to be added to the cart. Each must include an `id` key-value pair, and may include `options`, `note`, and `qty` key-value pairs.
`registerUserOnOrderComplete`	Whether to create a user account for the customer when the cart is completed and turned into an order.
`shippingAddress[]`	Shipping address attributes. (See Addresses).
`shippingAddressId`	ID of an existing address to use as the shipping address.
`shippingAddressSameAsBilling`	Set to `true` to use billing address for shipping address and ignore `shippingAddress` and `shippingAddressId`.
`shippingMethodHandle`	The handle of a shipping method to be set for the cart.

# Response

The output of the action depends on whether the cart was updated successfully and the Accept header.

State	`text/html`	`application/json`
	Standard behavior.	Standard behavior; cart data is available under a key determined by the cartVariable config setting.
	Standard behavior.	Standard behavior; cart data is available under a key determined by the cartVariable config setting.

# GET/POST `cart/load-cart`

Loads a cookie for the specified cart.

# Supported Params

Param	Description
`number`	Required cart number to be loaded.

# Response

The action’s output depends on whether the cart was loaded successfully and the Accept header.

State	`text/html`	`application/json`
	Standard behavior; GET requests are redirected to the loadCartRedirectUrl.	Standard behavior.
	Standard behavior; GET requests are redirected per the loadCartRedirectUrl.	Standard behavior.

# GET `downloads/pdf`

Generates and sends an order PDF as a file.

# Supported Params

Param	Description
`number`	Required order number.
`option`	Optional string value that’s passed to the PDF template.
`pdfHandle`	Handle of a configured PDF to be rendered.

# Response

State	Output
	File response with the rendered PDF and an `application/pdf` MIME type.
	Exceptions will be rendered with the normal error template.

# POST `payment-sources/add`

Creates a new payment source.

# Supported Params

Param	Description
`*`	All body parameters will be provided directly to the gateway’s payment form model.
`description`	Description for the payment source.
`gatewayId`	ID of the new payment source’s gateway, which must support payment sources.

# Response

The action’s output depends on whether the payment source was saved and the Accept header.

State	`text/html`	`application/json`
	Standard behavior.	Standard behavior; PaymentSource (opens new window) data available under the `paymentSource` key.
	Standard behavior; BasePaymentForm (opens new window) subclass available in the template as `paymentForm`,	Standard behavior; payment form data available under the `paymentForm` key.

Note that successful requests will return the payment source that was created; failures will bounce back the payment form with errors.

# POST `payment-sources/delete`

Deletes a payment source.

# Supported Params

Param	Description
`id`	ID of the saved payment source to delete. (Must belong to the customer, otherwise the user deleting must have `commerce-manageOrders` permission.)

# Response

The action’s output depends on whether the payment source was removed successfully and the Accept header.

State	`text/html`	`application/json`
	Standard behavior.	Standard behavior.
	Standard behavior.	Standard behavior.

# POST `payments/pay`

Makes a payment on an order. Read more about making payments.

# Supported Params

Param	Description
`*`	All body parameters will be provided directly to the gateway’s payment form model.
`cancelUrl`	URL user should end up on if they choose to cancel payment.
`email`	Email address of the person responsible for payment, which must match the email address on the order. Required if the order being paid is not the active cart.
`gatewayId`	The payment gateway ID to be used for payment.
`number`	The order number payment should be applied to. When ommitted, payment is applied to the current cart.
`paymentAmount`	Hashed payment amount, expressed in the cart’s `paymentCurrency`, available only if partial payments are allowed.
`paymentCurrency`	ISO code of a configured payment currency to be used for the payment.
`paymentSourceId`	The ID for a payment source that should be used for payment.
`registerUserOnOrderComplete`	Whether the customer should have an account created on order completion.
`savePaymentSource`	Whether to save card information as a payment source. (Gateway must support payment sources.)

# Response

The action’s output depends on whether payment was applied successfully and Accept header.

State	`text/html`	`application/json`
	Standard behavior; redirection defaults to the order’s `returnUrl`.	Standard behavior; cart data is available under a key determined by the cartVariable, as well as special `paymentForm`, `transactionId`, and `transactionHash` properties.
	Standard behavior; cart is available in the template under a variable determined by the cartVariable, as well as special `paymentForm` and `paymentFormErrors` variables.	Standard behavior; cart data is available under a key determined by the cartVariable, as well as special `paymentForm` and `paymentFormErrors` properties.

Both the cart and payment form models may have errors. Be sure and check all returned variables when a payment fails—the top-level errors key in JSON responses will only include errors from the payment form.

# GET `payments/complete-payment`

Processes customer’s return from an off-site payment.

# Supported Params

Param	Description
`commerceTransactionHash`	Required transaction hash used to verify the off-site payment being completed.

# Response

The action’s output depends on whether the payment completed successfully and the Accept header.

# Standard Request

State	`text/html`	`application/json`
	Standard behavior; redirection defaults to the order’s `returnUrl`.	Standard behavior; special `url` property set to the order’s `returnUrl`.
	Standard behavior; redirection defaults to the order’s `cancelUrl`.	Standard behavior; special `url` property set to the order’s `cancelUrl`.

Controller Actions

# Available Actions

# POST cart/complete

# Supported Params

# Response

# GET cart/get-cart

# Supported Params

# Response

# POST cart/update-cart

# Supported Params

# Response

# GET/POST cart/load-cart

# Supported Params

# Response

# GET downloads/pdf

# Supported Params

# Response

# POST payment-sources/add

# Supported Params

# Response

# POST payment-sources/delete

# Supported Params

# Response

# POST payments/pay

# Supported Params

# Response

# GET payments/complete-payment

# Supported Params

# Response

# Standard Request

Was this page helpful?

# POST `cart/complete`

# GET `cart/get-cart`

# POST `cart/update-cart`

# GET/POST `cart/load-cart`

# GET `downloads/pdf`

# POST `payment-sources/add`

# POST `payment-sources/delete`

# POST `payments/pay`

# GET `payments/complete-payment`