Controller Actions

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

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

# Available Actions

Methods	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/forget-cart	Removes a cookie for the current cart.
POST	cart/update-cart	Manage a customer’s current cart.
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.
GET	downloads/pdf	Returns an order PDF as a file.
POST	subscriptions/subscribe	Starts a new subscription.
POST	subscriptions/cancel	Cancels an active subscription.
POST	subscriptions/switch	Switch an active subscription’s plan.
POST	subscriptions/reactivate	Reactivates a canceled subscription.

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. At a minimum, the Allow Checkout Without Payment setting setting must be enabled for the cart’s store, or an HTTP exception will be thrown.

See the Making Payments page for more information about this action’s requirements.

# 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][after-fauilure]; cart is available in the template under a variable determined by the cartVariable.	[Standard behavior][after-fauilure]; 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.
`saveBillingAddressOnOrderComplete`	Whether to save the billing address to the customer’s address book when the cart is completed and turned into an order.
`saveShippingAddressOnOrderComplete`	Whether to save the shipping address to the customer’s address book when the cart is completed and turned into an order.
`saveAddressesOnOrderComplete`	Whether to save both the shipping and billing address to the customer’s address book when the cart is completed and turned into an order. Unlike `saveBillingAddressOnOrderComplete` and `saveShippingAddressOnOrderComplete`, this is not stored on the order itself—it just allows customers to set both at the same time.
`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.

# POST `cart/forget-cart`

Detaches a cart from the current customer’s session. Read more about managing carts.

This action has no arguments and responses are only sent as text/html.

# Response

State	`text/html`
	Standard behavior.

# 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 `payment-sources/add`

Creates a new payment source for the current customer.

# 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.
`isPrimaryPaymentSource`	Send a non-empty value to make this the customer’s primary payment source.

# 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 the models available in success and failure states are different!

# 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.)
`saveBillingAddressOnOrderComplete`	Whether to save the billing address to the customer’s address book when the cart is completed and turned into an order.
`saveShippingAddressOnOrderComplete`	Whether to save the shipping address to the customer’s address book when the cart is completed and turned into an order.
`saveAddressesOnOrderComplete`	Whether to save both the shipping and billing address to the customer’s address book when the cart is completed and turned into an order.

# 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.

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`.

# 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 `subscriptions/subscribe`

Starts a new subscription with the current customer’s default payment source. Learn more about supporting Subscriptions.

We recommend using normal HTML forms and a text/html content type for this action, as the gateway may require redirection to resolve billing issues when a subscription cannot be started. This workflow can be problematic when using application/json over Ajax.

# Supported Params

Param	Description
`planUid`	Required. UID of the Commerce plan the customer wants to subscribe to.
`fields[...]`	Subscription custom field values, indexed by their handles.
`fieldsLocation`	Allows relocation of the default `fields` key for custom field data (see above).
`*`	Conditionally required. Each gateway that supports subscriptions may require additional properties on its craft\commerce\models\subscriptions\SubscriptionForm (opens new window) subclass.

planUid and all gateway-specific properties must be hashed to prevent tampering.

# Response

State	`text/html`	`application/json`
	Standard behavior.	Standard behavior; the Subscription model is available under the `subscription` key.
	Standard behavior. Most subscription failures will be presented as a succinct error message. Specific issues are logged, but may not be disclosed to the customer. The user may be redirected to the `updateBillingDetailsUrl` setting to resolve billing issues.	Standard behavior.

# POST `subscriptions/cancel`

Cancels an active subscription.

# Supported Params

Param	Description
`subscriptionUid`	Required. UID of the subscription to cancel. Must be hashed.
`*`	Conditionally required. Each gateway that supports subscriptions may require additional properties on its craft\commerce\models\subscriptions\CancelSubscriptionForm (opens new window) subclass.

# Response

State	`text/html`	`application/json`
	Standard behavior.	Standard behavior; the Subscription model is available under the `subscription` key.
	Standard behavior.	Standard behavior.

# POST `subscriptions/switch`

Switch the plan on an active subscription.

# Supported Params

Param	Description
`subscriptionUid`	Required. UID of the subscription getting updated. Must be hashed.
`planUid`	Required. UID of the plan to switch to. Must be hashed.
`*`	Conditionally required. Each gateway that supports subscriptions may require additional properties on its craft\commerce\models\subscriptions\SwitchPlansForm (opens new window) subclass.

# Response

The request may fail if the new and old plans are not compatible. This is determined by the gateway, so be sure and consult its documentation and platform limitations.

You can check whether two plans are compatible in Twig, to narrow the options displayed to your customers:

{% set currentPlan = subscription.getPlan() %}
{% set gateway = currentPlan.getGateway() %}
{% set allPlans = craft.commerce.plans.getPlansByGatewayId(gateway.id) %}
{% set switchablePlans = allPlans|filter((p) => p.canSwitchFrom(currentPlan)) %}

<select name="planUid">
  {% for plan in switchablePlans %}
    <option value="{{ plan.uid|hash }}">{{ plan.name }}</option>
  {% endfor %}
</select>

State	`text/html`	`application/json`
	Standard behavior.	Standard behavior; the Subscription model is available under the `subscription` key.
	Standard behavior.	Standard behavior.

# POST `subscriptions/reactivate`

Reactivates a canceled subscription. Only subscriptions that haven’t expired yet can be reactivated—a subscription may be canceled

# Supported Params

Param	Description
`subscriptionUid`	Required. UID of the subscription to reactivate. Must be hashed.

# Response

State	`text/html`	`application/json`
	Standard behavior.	Standard behavior; the Subscription model is available under the `subscription` key.
	Standard behavior.	Standard behavior.

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

# POST cart/forget-cart

# Response

# GET cart/get-cart

# 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

# GET downloads/pdf

# Supported Params

# Response

# POST subscriptions/subscribe

# Supported Params

# Response

# POST subscriptions/cancel

# Supported Params

# Response

# POST subscriptions/switch

# Supported Params

# Response

# POST subscriptions/reactivate

# Supported Params

# Response

Was this page helpful?

# POST `cart/complete`

# GET `cart/get-cart`

# POST `cart/update-cart`

# GET/POST `cart/load-cart`

# POST `cart/forget-cart`

# GET `cart/get-cart`

# POST `payment-sources/add`

# POST `payment-sources/delete`

# POST `payments/pay`

# GET `payments/complete-payment`

# GET `downloads/pdf`

# POST `subscriptions/subscribe`

# POST `subscriptions/cancel`

# POST `subscriptions/switch`

# POST `subscriptions/reactivate`