Controller Actions

The following controller actions are available for the site’s front end:

Action | Description ------ | -----------

To invoke a controller action, send a POST request to Craft, with an action param set to the desired action path, either in the request body or query string.

#POST cart/complete

An alternative to checking out with the payments/pay action, this allows the customer to commit to buy the cart and complete the 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:

• allowEmptyCartOnCheckout
• requireShippingMethodSelectionAtCheckout
• requireBillingAddressAtCheckout
• requireShippingAddressAtCheckout

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

#Supported Params

The following params can be sent with the request:

Param | Description ----- | ----------- failMessage | The hashed flash notice that should be displayed if the cart failed to update. (Only used for text/html requests.) forceSave | Optionally set to true to force saving the cart. number | Optional order number for a specific, existing cart. redirect | The hashed URL the browser should redirect to. (Automatically set to loadCartRedirectUrl if a GET request that doesn’t expect JSON.) registerUserOnOrderComplete | Whether to create a user account for the customer when the cart is completed and turned into an order. successMessage | The hashed flash notice that should be displayed if the cart is updated successfully. (Only used for text/html requests.)

#Output

The output of the action depends on whether the cart was completed successfully and the request included an Accept: application/json header.

#Standard Request

Success | Output ------- | ------

#With JSON Request Header

Success | Output ------- | ------

#GET cart/get-cart

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

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

#Supported Params

The following params can be sent with the request:

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

#Output

JSON object with the current cart on the key defined by the cartVariable config setting.

#POST cart/update-cart

Updates the cart by adding purchasables, updating line items, or updating various cart attributes.

#Supported Params

The following params can be sent with the request:

Param | Description ----- | ----------- billingAddress[] | Array of billing address lines. (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[] | Array of estimated billing address lines. (See Addresses). estimatedBillingAddressSameAsShipping | Set to true to use shipping address for estimated billing address. estimatedShippingAddress[] | Array of estimated shipping address lines. (See Addresses). failMessage | The hashed flash notice that should be displayed if the cart failed to update. (Only used for text/html requests.) 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. redirect | The hashed URL the browser should redirect to. (Automatically set to loadCartRedirectUrl if a GET request that doesn’t expect JSON.) registerUserOnOrderComplete | Whether to create a user account for the customer when the cart is completed and turned into an order. shippingAddress[] | Array of shipping address lines. (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. successMessage | The hashed flash notice that should be displayed if the cart is updated successfully. (Only used for text/html requests.)

#Output

The output of the action depends on whether the cart was updated successfully and the request included an Accept: application/json header.

#Standard Request

Success | Output ------- | ------

#With JSON Request Header

Success | Output ------- | ------

#GET cart/load-cart

Loads a given cart into the current session.

#Supported Params

The following params can be sent with the request:

Param | Description ----- | ----------- number | Required cart number to be loaded. redirect | The hashed URL the browser should redirect to. (Automatically set to loadCartRedirectUrl if a GET request that doesn’t expect JSON.)

#Output

The output of the action depends on whether the cart was loaded successfully and the request included an Accept: application/json header.

#Standard Request

Success | Output ------- | ------

#With JSON Request Header

Success | Output ------- | ------

#POST customer-addresses/save

Creates or updates a customer’s address. Refreshes the cart if it’s using the provided address.

#Supported Params

The following params can be sent with the request:

Param | Description ----- | ----------- address.{$attr} | Address object with any of the key-value pairs in the system’s address lines. address.id | Required address ID to be edited, which must belong to the current customer. fields[] | Custom fields to be saved on the cart if it’s using the provided address. makePrimaryBillingAddress | Whether to save as the primary billing address. makePrimaryShippingAddress | Whether to save as the primary shipping address.

#Output

The output of the action depends on whether the address was saved successfully and the request included an Accept: application/json header.

#Standard Request

Success | Output ------- | ------

#With JSON Request Header

Success | Output ------- | ------

#POST customer-addresses/delete

Deletes one of the current customer’s addresses.

If the deleted address is used in the cart, that relationship will automatically be removed.

#Supported Params

The following params can be sent with the request:

Param | Description ----- | ----------- id | ID of the address to be removed, which must belong to the customer.

#Output

The output of the action depends on whether the cart was removed successfully and the request included an Accept: application/json header.

#Standard Request

Success | Output ------- | ------

#With JSON Request Header

Success | Output ------- | ------

#GET customer-addresses/get-addresses

Returns the current customer’s addresses as JSON.

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

#Output

Returns a JSON object with a success key and true value, and an addresses key with an array of the customer’s addresses.

#GET customer-orders/get-orders

Returns the current customer’s orders as JSON.

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

#Output

Returns a JSON object with a success key and true value, and an orders key with an array of the customer’s orders.

#GET downloads/pdf

Returns an order PDF as a file.

#Supported Params

The following params can be sent with the request:

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

#Output

File response with the rendered PDF and an application/pdf MIME type.

#POST payment-sources/add

Creates a new payment source.

#Supported Params

The following params can be sent with the request:

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.

#Output

The output of the action depends on whether the payment source was successfully and the request included an Accept: application/json header.

#Standard Request

Success | Output ------- | ------

#With JSON Request Header

Success | Output ------- | ------

#POST payment-sources/delete

Deletes a payment source.

#Supported Params

The following params can be sent with the request:

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.) redirect | The hashed URL the browser should redirect to.

#Output

The output of the action depends on whether the payment source was removed successfully and the request included an Accept: application/json header.

#Standard Request

Success | Output ------- | ------

#With JSON Request Header

Success | Output ------- | ------

#POST payments/pay

Makes a payment on an order.

#Supported Params

The following params can be sent with the request:

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. redirect | Return URL for successful 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.)

#Output

The output of the action depends on whether payment was applied successfully and the request included an Accept: application/json header.

#Standard Request

Success | Output ------- | ------

#With JSON Request Header

Success | Output ------- | ------

#GET payments/complete-payment

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

#Supported Params

The following params can be sent with the request:

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

#Output

The output of the action depends on whether the payment completed successfully and the request included an Accept: application/json header.

#Standard Request

Success | Output ------- | ------

#With JSON Request Header

Success | Output ------- | ------