item_form Tag

The item_form tag allows you to add an item to cart.

Example

theme/templates/pages/item.html.twig

{% item_form product %}
    <input type="hidden" name="fulfillment[fulfillment_type]" value="SHIPMENT" />
    <input type="hidden" name="location_id" value="LOCATION_ID" />

    <h2>{{ product.name }}</h2>

    <img src="{{ product.images[0].absolute_urls[320] }}" width="320" />

    <div>
        <h3>Type</h3>
        <select name="line_item[variation_id]">
            {% for variation in product.variations %}
                <option value="{{ variation.id }}">{{ variation.name }}</option>
                - {{ variation.price.current_formatted }}
            {% endfor %}
        </select>
    </div>

    {% for modifier_list in product.modifier_lists %}
        <h3>{{ modifier_list.name }}</h3>
        {% for modifier in modifier_list.modifiers %}
            <label>
                // Modifier Choice
                <input
                    type="checkbox"
                    name="line_item[modifiers][CHOICE][{{ modifier_list.id }}][choice_selection]"
                    value="{{ modifier.id }}"
                />

                // Text based modifier
                <input
                    type="input"
                    name="line_item[modifiers][TEXT][{{ modifier_list.id }}][text_entry]"
                />

                // Gift wrap modifier
                <input
                    type="checkbox"
                    name="line_item[modifiers][GIFT_WRAP][{{ modifier_list.id }}][choice_selection]"
                    value="{{ modifier.id }}"
                />

                // Gift message modifier
                <input
                    type="input"
                    name="line_item[modifiers][GIFT_MESSAGE][{{ modifier_list.id }}][text_entry]"
                />
                {{ modifier.name }}
            </label>
        {% endfor %}
    {% endfor %}

    <div>
        <h3>Quantity</h3>
        <input type="number" name="line_item[quantity]" min="1" value="1" />
    </div>

    <input type="submit" value="Buy Now" />
    {% if errors.error %}
        <p style="color:red">Something went wrong</p>
    {% endif %}
{% enditem_form %}

{% schema %}
{
    "product": {
        "type": "item"
    }
}
{% endschema %}

Passing an item to the form tag

The first token after {% item_form is an identifier for an item resource. The item resource must be referenced in the template’s schema and the appropriate data must be passed in from either the page json or to the template API.

Required form fields

Three form fields are required for the item_form to work:

name=fulfillment[method]

• values: SHIPMENT, PICKUP, DELIVERY, MANUAL

name=variation_id

• values: the variation id of the item variation to add

name=quantity

• values: the numeric quantity of the item to add to cart

type=submit

• Button to process the form. Adds to cart and redirects to the checkout page

Passing attributes to the form tag

The item_form tag outputs an html form tag. If you want to pass attributes like class or style you do so like this:

{% item_form item, class="a b c" style="color: red;" %}

Everything of the form x=”” will be passed through to the form tag.

Handling modifiers

Modifiers can be optionally provided to the item_form tag given that the item has available modifiers to choose from.

<input
    type="checkbox"
    name="modifiers[{{ modifier.id }}][]"
    value="{{ modifiers.id }}"
/>

Modifiers are available on an item’s modifier_lists attribute. Each entry in that list has its own attribute modifiers which are the choices available to that modifier set.

{
    "modifier_lists": [
        {
            "id": "GEPF7OGDW57XU3MLYEN6W7PH",
            "name": "Color",
            "square_online_item_id": "12",
            "type": "choice",
            "min_selected_modifiers": 0,
            "max_selected_modifiers": 0,
            "modifiers": [
                {
                    "id": "WMQ4TYQ24FRVUWT3K5KAPTKW",
                    "name": "Red",
                    "price_money": {
                        "amount": 0,
                        "currency": "USD"
                    },
                    "ordinal": 1
                },
                {
                    "id": "TRZDAGIKOPEWW4MZPF5YOJ7L",
                    "name": "Blue",
                    "price_money": {
                        "amount": 0,
                        "currency": "USD"
                    },
                    "ordinal": 2
                },
                {
                    "id": "3MHVUSUTUQK4C2OZYKD4O3CY",
                    "name": "Black",
                    "price_money": {
                        "amount": 0,
                        "currency": "USD"
                    },
                    "ordinal": 3
                },
                {
                    "id": "RP2JYLY6QWPRDHMAS6X6VY2C",
                    "name": "Orange",
                    "price_money": {
                        "amount": 3,
                        "currency": "USD"
                    },
                    "ordinal": 4
                }
            ]
        }
    ]
}