🎉 Simple Commerce v3.0 is out! Includes new features & some big quality of life improvements.

Simple Commerce Logo


Available tags

To help you integrate Simple Commerce into your Antlers templates, Simple Commerce provides various tags:

Form Tags

Some Simple Commerce tags output <form> elements that submit to Simple Commerce endpoints. There's a couple of optional parameters you can add to form tags.

  • redirect - the URL where you'd like to redirect the user after a successful form submission.
  • error_redirect - the URL where you'd like to redirect the user after any validation errors are thrown by the form.
  • request - the name of the Form Request you wish to use for validation of the form.
1{{ sc:cart:addItem redirect="/cart" }}
2 <input type="hidden" name="product" value="{{ id }}">
3 <input type="hidden" name="quantity" value="1">
4 <button class="button-primary">Add to Cart</button>
5{{ /sc:cart:addItem }}

Hot Tip: I'd highly recommend disabling the button after the user submits the form to prevent them from submitting it multiple times.

When Simple Commerce builds the HTML for your form, any of the optional parameters you provide will be encrypted for additional protection (so you're users can't mess with redirects/requests by editing your HTML).

However, if you wish to use static caching or submit SC's forms via AJAX, you'll probably want to disable this behaviour. You may do so by adding the following to your configuration file:

1// config/simple-commerce
3'disable_form_parameter_validation' => true,

Field Whitelisting

When using Form Tags, Simple Commerce will now require you to specify any additional fields you wish to be editable via front-end forms.

For example: you may wish for customers to fill in the shipping_note field via the {{ sc:cart:update }} form but you wouldn't want them filling the is_paid field.

With 'field whitelisting', you must specify the fields you wish to allow in the Simple Commerce config file.

3| Field Whitelist
6| You may configure the fields you wish to be editable via front-end forms
7| below. Wildcards are not accepted due to security concerns.
9| https://simple-commerce.duncanmcclean.com/tags#field-whitelisting
13'field_whitelist' => [
14 'orders' => [
15 'shipping_name', 'shipping_address', 'shipping_address_line2', 'shipping_city', 'shipping_region',
16 'shipping_postal_code', 'shipping_country', 'use_shipping_address_for_billing', 'billing_name', 'billing_address',
17 'billing_address_line2', 'billing_city', 'billing_region', 'billing_postal_code', 'billing_country',
18 ],
20 'line_items' => [],


Like noted above, you can use the request parameter when creating form tags to specify a Form Request to be used for validation purposes. You can either tell it the full class name (including the namespace) or without it.

1{{## Form Request: app\Http\Requests\CheckoutInformationRequest ##}}
3{{ sc:cart:update request="CheckoutInformationRequest" }}
5{{ /sc:cart:update }}

Although you can specify the request parameter on any form tag, not all of them will actually use it. Here's a list of the forms that do:

  • {{ sc:cart:addItem }}
  • {{ sc:cart:updateItem }}
  • {{ sc:cart:update }}
  • {{ sc:customer:update }}
  • {{ sc:checkout }}

Blade support

At the moment, I've not got any plans to introduce first-party support for Blade (or any similar templating languages for that metter).


If you'd prefer not to use the shorthand of sc in your tags, you can also use simple-commerce which will work the same way.

This could be used to give more context of the tag in use to make it clear it's dealing with Simple Commerce.

1{{ simple-commerce:countries }}