LemonStand - shop:checkout

LemonStand Documentation
Developer's Guide
API (function, action and class reference)
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 fields

A set of form fields required and supported by the shop:checkout action depends on a current checkout step. But one hidden field 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.

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 bulling_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 bulling 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.

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.

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.
$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"/>
```

Next: shop:compare
Previous: shop:change_password
Return to API (function, action and class reference)