# Overview Snipcart for Statamic makes the setup of your Snipcart shop with Statamic a breeze. ## Features * Easy setup of your Snipcart shop * Product blueprint containing all possible Snipcart product attributes * Antlers Tag to automatically create Snipcart product buttons * Complete support of custom fields to create product variants with dropdowns, checkboxes, and more * Multi-Site support with configurable currency, length, and weight units per site ## Requirements * Snipcart Account * Statamic 4 * Laravel 10 * PHP 8.1 ## License Snipcart for Statamic is paid software with an open-source codebase. If you want to use it in production, you’ll need to [buy a license from the Statamic Marketplace](https://statamic.com/addons/aerni/snipcart). ## Credits Developed by[ Michael Aerni](https://www.michaelaerni.ch) # Installation Follow the instructions below to setup Snipcart for Statamic. ## Install Addon Install the addon with Composer: ```bash composer require aerni/snipcart ``` ## Perform Basic Configuration The installation process will automatically publish the addon's config to `config/snipcart.php`. Open the config and perform the following configuration: 1. **Sites:** Add the desired currency, length, and weight units for each of your sites. [Learn more](/getting-started/configuration#sites) 2. **Collections & Taxonomies:** Add the collections and taxonomies you want to use for your products. [Learn more](/getting-started/configuration#collections-and-taxonomies) ## Run Setup Command After configuring your **Sites** and **Collections & Taxonomies,** you may run the `setup` command. This will create all the necessary collections, taxonomies, and blueprints to get you started. ```bash php please snipcart:setup ``` After running the command, make sure to customize the configuration of the created collections and taxonomies to define the sites, templates, routes, etc. ## Add Snipcart API Keys Add your Snipcart API keys to your `.env` file. You can find them in your [Snipcart dashboard](https://app.snipcart.com/dashboard/account/credentials). ```bash SNIPCART_LIVE_KEY=************************ SNIPCART_LIVE_SECRET=************************ SNIPCART_TEST_KEY=************************ SNIPCART_TEST_SECRET=************************ ``` ## Add Script Tag Add the following tag to your layout view. Snipcart recommends adding it directly after the `` element. ```markup {{ snipcart:script }} ``` ## Add Webhook URL Add the absolute URL of the configured Snipcart webhook to your [Snipcart Dashboard](https://app.snipcart.com/dashboard/webhooks), eg. `https://my-shop.com/webhooks/snipcart` You can [customize the webhook route](https://snipcart.docs.michaelaerni.ch/setup/configuration#snipcart-webhook-route) in the config. The default route is `webhooks/snipcart`. # Configuration You can configure Snipcart for Statamic with the configuration options outlined below. ## Sites Set the currency, length, and weight units for each Statamic site. The units will be converted from a product's root entry in a multi-site setup. **Supported currencies:** ISO 4217 letter codes supported by Snipcart, eg. `USD` or `EUR`\ **Supported length units:** `cm`, `m`, `in`, `ft`\ **Supported weight units:** `g`, `kg`, `oz`, `lb` ```php 'sites' => [ 'english' => [ 'currency' => 'USD', 'length' => 'in', 'weight' => 'oz', ], 'german' => [ 'currency' => 'EUR', 'length' => 'cm', 'weight' => 'g', ], ], ``` {% hint style="info" %} Make sure to keep the sites in sync with your Statamic sites. You can do so by [running the sync-sites command](https://snipcart.docs.michaelaerni.ch/setup/commands#sync-sites)[.](/getting-started/commands#sync-sites) {% endhint %} ## Collections & Taxonomies Configure your product collections and taxonomies. ```php 'products' => [ [ 'collection' => 'games', 'taxonomies' => ['genres'], ], [ 'collection' => 'movies', 'taxonomies' => ['genres', 'directors'], ], ], ``` ## Snipcart API Keys Your Snipcart API Keys for the Live and Test Environment. ```php 'live_key' => env('SNIPCART_LIVE_KEY'), 'live_secret' => env('SNIPCART_LIVE_SECRET'), 'test_key' => env('SNIPCART_TEST_KEY'), 'test_secret' => env('SNIPCART_TEST_SECRET'), ``` ## Test Mode Set this to `false` to start processing real transactions. You probably want to do this in production only. ```php 'test_mode' => env('SNIPCART_TEST_MODE', true), ``` ## Snipcart Settings Configure any settings you want to apply to the Snipcart script. Make sure to set the keys exactly as documented, e.g., `LoadCSS`. [All available settings.](https://docs.snipcart.com/v3/setup/installation#settings) ```php 'snipcart_settings' => [ 'version' => '3.5.0', 'loadStrategy' => 'on-user-interaction', ], ``` ## Cart Image Define a [Glide](https://statamic.dev/tags/glide) preset to be applied to the product image in the cart. You may also turn the manipulation off (not recommended). ```php 'image' => [ 'manipulation' => true, 'preset' => ['w' => 240, 'q' => 75], ] ``` ## Snipcart API Cache Lifetime Define the cache lifetime of Snipcart API responses in seconds. The API is used for things like fetching the stock of a product. ```php 'api_cache_lifetime' => 3600, ``` ## Snipcart Webhook Route Define the route where the Snipcart webhook requests will be sent to. Don't forget to [add this URL in your Snipcart Dashboard](https://app.snipcart.com/dashboard/webhooks). Set this to `null` to remove the route. ```php 'webhook' => 'webhooks/snipcart', ``` # Commands There are a couple of commands to help you with the setup of this addon. ## Setup The `setup` command creates all the necessary collections, taxonomies, and blueprints to get you started. The command won't override existing collections, taxonomies, and blueprints. ```bash php please snipcart:setup ``` You can restore the collections, taxonomies, and blueprints to their factory preset by adding the `--force` flag to the command. This will purge all the changes you may have made. ``` php please snipcart:setup --force ``` ## **Sync Sites** The `sync-sites` command syncs your Snipcart sites with your Statamic sites. ``` php please snipcart:sync-sites ``` {% hint style="info" %} Run this command whenever you add or delete a Statamic site or change a site's handle. {% endhint %} # Basics ## Example This is a simple example of a section that displays all products:

<section>
    {{ collection:products }}
        <div>
            <h2>{{ title }}</h2>
            <div>{{ price }}</div>
            <div>{{ snipcart:buy }}</div>
        </div>
    {{ /collection:products }}
</section>

## Multi-Site Snipcart doesn't fully support multiple localizations. The only localizable field supported by Snipcart is a product's price. You may localize a few other fields such as a product's title and description. But those fields are solely for templating purposes and will fall back to the product's root locale when getting the Snipcart button attributes. # Tags There are a couple of useful tags to output HTML elements and data. ## Snipcart Output Snipcart-specific HTML elements like a product button or the total number of items in the cart. {% content-ref url="/pages/-MCaiU\_ZX\_4q4lo2KaUI" %} [Snipcart](/templating/tags/snipcart) {% endcontent-ref %} ## Currency Output data of the currency defined in the config. {% content-ref url="/pages/-MCbDpk65DqmZK25RCwa" %} [Currency](/templating/tags/currency) {% endcontent-ref %} ## Length Output data of the length unit defined in the config. {% content-ref url="/pages/-MCbGEume-KBD-2idMK4" %} [Length](/templating/tags/length) {% endcontent-ref %} ## Weight Output data of the weight unit defined in the config. {% content-ref url="/pages/-MCbFCrDo7RZ6MSMW9r1" %} [Weight](/templating/tags/weight) {% endcontent-ref %} # Snipcart Output Snipcart-specific HTML elements like a product button or the total number of items in the cart. ## Buy Button This tag creates a Snipcart product buy button with all the `data-item-*` attributes according to the product's content. This is arguably the most important tag as it does all the heavy lifting for you. Learn more about [product attributes](https://docs.snipcart.com/v3/setup/products). ```html {{ snipcart:buy }} ``` {% hint style="info" %} The automatic generation of attributes only works on a product page or inside a product collection loop. If you use the tag in any other place, you must manually define each attribute. {% endhint %} ### Manually Defining Attributes You can manually define any accepted attribute directly on the tag. You can also use this to override the values of automatically generated attributes. ```html {{ snipcart:buy id="{{ increment }}" name="{{ some_variable }}" }} ``` ### Customize Button You can also fully customize your buy buttons with your own markup. Use this tag to get the product's data attributes: ```html ``` {% hint style="info" %} Don't forget to add the **snipcart-add-item** class to your custom button. {% endhint %} ## Cart Button A Snipcart cart button. ``` {{ snipcart:cart }} ``` ## Sign-in Button A Snipcart sign-in button. ``` {{ snipcart:signin }} ``` ## Total Items The total number of items in the cart. ``` {{ snipcart:items }} ``` ## Total Price The total price of items in the cart. ``` {{ snipcart:price }} ``` ## Parameters There are a couple of parameters you may use on the tags. | Parameter | Description | Supported By | | --------- | ------------------------------- | ------------------------------------- | | `class` | Add classes to the HTML element | `buy` `cart` `signin` `items` `price` | | `text` | Override the default text | `buy` `cart` `signin` | **Example:** Add some classes to the cart button and override the default text. ``` {{ snipcart:cart class="p-2 bg-gray-100" text="Checkout" }} ``` # Currency Output data of the currency defined in the config. ## Code The code of the currency, e.g. `USD`. ``` {{ currency:code }} ``` ## Name The name of the currency, e.g. `US Dollar`. ``` {{ currency:name }} ``` ## Symbol The symbol of the currency, e.g. `$`. ``` {{ currency:symbol }} ``` # Length Output data of the length unit defined in the config. ## Abbreviation The abbreviation of the length unit, e.g. `cm`. ``` {{ length:short }} ``` ## Singular Name The singular name of the length unit, e.g. `Centimeter`. ``` {{ length:singular }} ``` ## Plural Name The plural name of the length unit, e.g. `Centimeters`. ``` {{ length:plural }} ``` ## Length Name Automatically get the singular or plural name of the length unit according to the product's length, e.g. `Centimeter/Centimeters`. ``` {{ length:lengthName }} ``` ## Width Name Automatically get the singular or plural name of the length unit according to the product's width, e.g. `Centimeter/Centimeters`. ``` {{ length:widthName }} ``` ## Height Name Automatically get the singular or plural name of the length unit according to the product's height, e.g. `Centimeter/Centimeters`. ``` {{ length:heightName }} ``` # Weight Output data of the weight unit defined in the config. ## Abbreviation The abbreviation of the weight unit, e.g. `kg`. ``` {{ weight:short }} ``` ## Singular Name The singular name of the weight unit, e.g. `Kilogram`. ``` {{ weight:singular }} ``` ## Plural Name The plural name of the weight unit, e.g. `Kilograms`. ``` {{ weight:plural }} ``` ## Name Automatically get the singular or plural name of the weight unit according to the product's weight, e.g. `Kilogram/Kilograms`. ``` {{ weight:name }} ``` # Modifiers There are a couple of useful modifiers to help you format variables in your templates. ## Add Operator Use this modifier to prepend the correct operator to a money variable. ```markup {{ price_modifier }} // $1.00 {{ price_modifier | add_operator }} // +$1.00 ``` ## Strip Unit Use this modifier to strip a variable's currency, length, or weight unit. ```markup {{ price }} // $19.99 {{ price | strip_unit }} // 19.99 {{ length }} // 10 in {{ length | strip_unit }} // 10 {{ weight }} // 3.5 oz {{ weight | strip_unit }} // 3.5 ``` # Blueprints ## Customizing Blueprints You may add fields to your product blueprints or rearrange existing ones to customize your experience. You only need to make sure not to delete any pre-existing fields to ensure the addon's functionality. ## Assets Container The asset container for the product images defaults to `assets`. You may change this to any container you want. # Translations You can customize the default translations or add your own. ## Publish Translations To start customizing the translations, you first need to publish them to `lang/vendor/snipcart` using this command: ``` php please vendor:publish --tag=snipcart-translations ``` ## Customize Translations ### Buttons The translation of **buttons** are located in: \ `lang/vendor/snipcart/{language}/buttons.php` ### Currencies The translation of **currencies** are located in: \ `lang/vendor/snipcart/{language}/currencies.php` ### Units The translation of **length** and **weight** units are located in: \ `lang/vendor/snipcart/{language}/units.php` ## Add Translations You can add your own translations by placing them into: `lang/vendor/snipcart/{language}/{filename}.php` # Snipcart API You can leverage the full power of the Snipcart API to further customize your shop integration. ## Configuration Set your [Secret API Keys](https://snipcart.docs.michaelaerni.ch/setup/configuration#snipcart-api-keys) and define the [API Cache Lifetime](https://snipcart.docs.michaelaerni.ch/setup/configuration#api-cache-lifetime). ## Basic Usage Use the underlying package to make Snipcart API calls and do your custom magic. [Read the documentation of Snipcart API](https://github.com/aerni/snipcart-api). # Snipcart Webhooks You can leverage the full power of Snipcart Webhooks to further customize your shop integration. ## Configuration [Define the route](https://snipcart.docs.michaelaerni.ch/setup/configuration#snipcart-webhook-route) of your Snipcart Webhook and [add the absolute URL in your Snipcart Dashboard](https://app.snipcart.com/dashboard/webhooks). ## Basic Usage The underlying package listens to incoming Webhook requests and dispatches Laravel Events accordingly. Create Laravel Event Listeners or Subscribers and do your custom magic. [Read the documentation of Snipcart Webhooks](https://github.com/aerni/snipcart-webhooks).