LemonStand - shop:checkout

shop:checkout

The shop:checkout action is designed for creating the Checkout page. Please refer to the Creating the Checkout page article for examples of the action usage.

The checkout process is split to several steps. A current step name is always available through the $checkout_step field. That field can have the following values:

billing_info
shipping_info
shipping_method
payment_method
review

Supported and required form fieldsbu

A set of form fields required and supported by the shop:checkout action depends on a current checkout step. But one hidden field (checkout_step) is required on each step:

checkout_step – specifies a current checkout step. Depending on a value of this field, LemonStand validates corresponding form fields and switches the checkout process to a next step, when a customer clicks the Next button.
skip_to - allows to switch the checkout process to a specific step.
auto_skip_shipping - allows to skip the Shipping Method step if the shopping cart contains only non-shippable items (downloadable products or services). Please read this article to learn how to configure LemonStand to skip the shipping method checkout step.
empty_cart - allows to leave the cart content after the order is placed. This allows your customers to return to previous checkout step even if they already placed the order. The default value is 0 (false).

You can also pass the cart_name parameter if you want to the checkout to work with a specific shopping cart. Please read the Using a specific shopping cart section below.

The following fields are supported on the billing_info step:

first_name – customer billing first name. Required.
last_name – customer billing last name. Required.
email – customer email address. Required.
company – customer company name. Optional.
phone – customer phone number. Optional.
street_address – customer billing street address. Required.
city – customer billing city. Required.
zip – customer billing ZIP code. Required.
country – customer billing country identifier. Required.
state – customer billing state identifier. Required.

Fields, managing the automatic customer registration

You can use the following fields on the billing_info checkout step for implementing the customer automatic registration feature

register_customer - use this field if you want a customer to be automatically registered on checkout. If this field is not declared or its value is 0 (default), all other fields listed below will not have any effect. Accepted values are: 0, 1.
allow_empty_password - determines whether customers should enter a password to register. If the field value is 0, the password is not registered. In this case LemonStand will generate a random password. The default value is 0. You can set the field value to 1 and omit the customer password fields (customer_password, customer_password_confirm). Accepted values are: 0, 1.
customer_password - customer password. This field is optional if the allow_empty_password field has value of 1.
customer_password_confirm - customer password confirmation. Use this field along with the customer_password field.
no_password_error - error message to display in case if the customer did not specify his password. Default value is "Please enter your password.".
passwords_match_error - error message to display in case if the password and its confirmation do not match. Default value is "Password and confirmation password do not match.".
customer_exists_error - an error to display in case if a customer with the specified email address already exists. Default value is "A customer with the specified email is already registered. Please log in or use another email.".

The following hidden fields can be added to the review checkout step.

customer_auto_login - automatically log customer in after placing the order. Accepted values are: 0, 1.
customer_registration_notification - send a registration notification email message to customer. LemonStand uses an email template with the shop:registration_confirmation code for the registration notification. Accepted values are: 0, 1.

The following fields are supported on the shipping_info step:

first_name – customer shipping first name. Required.
last_name – customer shipping last name. Required.
company – shipping company name. Optional.
phone – shipping phone number. Optional.
street_address – customer shipping street address. Required.
city – customer shipping city. Required.
zip – customer shipping ZIP code. Required.
country – customer shipping country identifier. Required.
state – customer shipping state identifier. Required.
customer_password - customer password for the customer registration feature (see above). This field is optional if the allow_empty_password field has value of 1.
customer_password_confirm - customer password confirmation for the customer registration feature. This field is optional if the allow_empty_password field has value of 1.
is_business - determines whether the shipping location is a business address. Optional.

The following field is required on the shipping_method step:

shipping_option – an identifier of selected shipping method.

The following field is required on the payment_method step:

payment_method – an identifier of selected payment method.

Generated PHP variables

The following variables are available on each checkout step.

$checkout_step – a string value, corresponding a current checkout step.
$billing_info – an object of the Shop_CheckoutAddressInfo class representing a customer's billing name and address
$shipping_info – an object of the Shop_CheckoutAddressInfo class representing a customer's shipping name and address
$shipping_method – a PHP object with fields $id, $quote, $name, representing a selected shipping method. The $id field corresponds an identifier of the shipping method in LemonStand database.
$payment_method – a PHP object with fields $id, $name, representing a selected payment method. The $id field corresponds an identifier of the payment method in LemonStand database.
$coupon_code - a coupon code entered by a visitor
$discount - estimated cart discount. You can display this value during the checkout process.
$applied_discount_rules - array, represents a list of discount rules applied to the cart products. Each element in the array is an object with two fields - $rule(Shop_CartPriceRule class) and $discount (numeric value). You can use this variable for displaying a list of applied discounts. Example:
```
<h3>Applied discounts</h3>
<? foreach ($applied_discount_rules as $rule_info): ?>
  <p>
    <?= $rule_info->rule->name ?> 
    <?= $rule_info->rule->description ?> - 
    <?= format_currency($rule_info->discount) ?><br/>
  </p>
<? endforeach ?>
```
$cart_total - cart total value (subtotal).
$estimated_total - an estimated total value. This value is calculated on each step of the checkout process, taking into account price rules and known information about the customer.
$estimated_tax - an estimated tax value. This value is calculated on each step of the checkout process, taking into account price rules (defined on the Shop/Discounts page) and known information about the customer. The tax value includes the goods tax and shipping tax.
$shipping_required - this variable is FALSE if the shopping cart contains only non-shippable items (downloadable products or services).

The following variables are available on the billing_info and shipping_info checkout steps.

$countries – a collection of countries for populating the Country list. The collection is an object of the Db_DataCollection class. Each element in the collection is an object of the Shop_Country class.
$states - a collection of countries for populating the State list. The collection is an object of the Db_DataCollection class. Each element in the collection is an object of the Shop_CountryState class

The following variables are available on the shipping_method checkout step.

$shipping_options – a list of available shipping options, array. Each element in the array is an object of the Shop_ShippingOption class.

The following variables are available on the payment_method checkout step.

$goods_tax – a value of a goods tax
$subtotal – order subtotal sum
$shipping_quote – a shipping quote value
$shipping_tax – a shipping tax value
$payment_methods – a list of applicable payment methods, array. Each element in the array is an object of the Shop_PaymentMethod class.

The following variables are available on the review checkout step.

$goods_tax – a value of a goods tax
$subtotal – order subtotal sum
$shipping_quote – a shipping quote value
$shipping_tax – a shipping tax value
$total – order total sum
$discount - total discount value.
$product_taxes - a list of sales taxes applied to all order items, array. Each element in the array is an object containing the following fields:
- name - the tax name, for example GST,
- total - total tax amount
You can output tax names and values with the following code:
```
<? foreach ($product_taxes as $tax): ?>
  <?= h($tax->name) ?>: <?= format_currency($tax->total) ?>
<? endforeach ?>
```
$shipping_taxes - a list of taxes applied to the shipping service, array. Each element in the collection is an object containing the following fields:
- name - the tax name, for example GST,
- total - total tax amount
$taxes - a list of all taxes applied to products and shipping, as array. Taxes are combined by names. Each element in the array is an object containing the following fields:
- name - the tax name, for example GST,
- total - total tax amount

Supported AJAX handlers

on_action – posts a current step form data to the server, validates form data and switches the checkout process to a next step. Use this hander for creating the Next button on the checkout page. Example:
```
<input 
  type="image" 
  src="/resources/images/btn_next.gif" 
  alt="Next" 
  onclick="return $(this).getForm().sendRequest('on_action', {update:{'checkout_page': 'checkout_partial'}})"/>
```
shop:on_copyBillingInfo – copies billing information (a customer name and address) to the shipping information checkout step. Use this for creating a link “Copy billing information” in the shipping information step. Example:
```
<a 
  href="#" 
  onclick="return $(this).getForm().sendRequest(
    'shop:on_copyBillingInfo', 
    {update:{'checkout_page': 'checkout_partial'}})">
  billing information</a>
```
shop:on_updateStateList – allows you to update a list of states when a customer select some country in the country list. Example:
```
<select id="country" name="country" onchange="return this.getForm().sendRequest(
  'shop:on_updateStateList',
  {extraFields: {
    'country': $(this).get('value'), 
    'control_name': 'state', 
    'control_id': 'state', 
    'current_state': '<?= $shipping_info->state ?>'},
  update: {'shipping_states': 'shop:state_selector'}
})">
```
To make the state list updatable, place it into a separate partial. In the code example above the partial is called shop:state_selector. The parameters control_name, control_id, current_state will be passed into the state list partial by LemonStand when it handles the shop:on_updateStateList request. You can use these parameters in the state list partial to highlight a currently selected state. You can check how the Checkout page organized in the LemonStand demo store.

Using a specific shopping cart

LemonStand supports multiple shopping carts. You can bind a checkout process to a specific shopping cart. All handlers and checkout actions accept the $cart_name parameter, which specifies a name of a cart. By default LemonStand works with a shopping cart named "main". You don't need to pass the "main" shopping cart name to LemonStand, because it implies this name by default.

In order to display and manage a content of a specific shopping cart, you need:

Pass the cart_name parameter to the shop:checkout action before the action is executed. You can do it using the following code on the Pre Action Code field of the Create/Edit Page form:
```
$_POST['cart_name'] = 'my_second_cart';
```
Pass the cart_name parameter to all AJAX handlers which you invoke on the Cart page. The simplest way to do it is to add a hidden field to the form which wraps your checkout page content:
```
<input type="hidden" name="cart_name" value="my_second_cart"/>
```