Getting started overview

Snipcart facilitates the integration of e-commerce functionality into any website or web application through an embeddable JavaScript library. The core process involves embedding snipcart.js and defining products directly within your HTML markup. Snipcart manages the entire checkout flow, inventory, and order management, while developers retain control over product presentation and website design. The following steps outline the initial setup to achieve a functional shopping cart.

To get started with Snipcart, follow these steps:

  1. Create a Snipcart Account: This provides access to the Snipcart dashboard, where you manage your store, retrieve API keys, and configure settings.
  2. Obtain your Public API Key: This key is essential for initializing the Snipcart JavaScript library on your website.
  3. Embed Snipcart.js: Include the necessary JavaScript and CSS files in your website's HTML.
  4. Define Products: Use specific HTML attributes on your product elements to make them discoverable and purchasable by Snipcart.

This sequence allows for a rapid deployment of basic e-commerce capabilities.

Create an account and get keys

Your first step is to establish a Snipcart account to gain access to the dashboard and obtain the necessary API keys for integration. Snipcart offers a free tier for the first $500 in sales per month, allowing developers to test and implement the service without upfront costs.

To create your account and retrieve API keys:

  1. Navigate to the Snipcart homepage and click on the "Sign Up" or "Get Started Free" option.
  2. Follow the on-screen prompts to register with your email address or a linked account (e.g., GitHub, Google).
  3. Once registered, you will be redirected to your Snipcart dashboard.
  4. From the dashboard, go to Account > API Keys.
  5. Locate your Public API Key. This key is used on your front-end to initialize Snipcart. You will also see a Secret API Key, which is typically used for server-side operations with the Snipcart API reference. For initial client-side integration, only the Public API Key is required.
  6. Copy your Public API Key. You will need to embed this directly into your website's HTML.

It is important to keep your Secret API Key secure and never expose it on the client-side, consistent with API key security best practices.

Your first request

Integrating Snipcart into a webpage involves embedding the JavaScript library and defining a product. This example demonstrates how to set up a basic HTML page that includes Snipcart and a single purchasable item.

Quick Reference: Getting Snipcart Live

Step What to Do Where
1. Create Account Register on Snipcart.com Snipcart.com
2. Get Public API Key Navigate to Account > API Keys in dashboard Snipcart Dashboard
3. Embed Snipcart Add JS/CSS links in your <head> HTML, including your Public API Key Your website's HTML (<head> and <body>)
4. Define Product Add data-item-* attributes to a button or link Your website's HTML (where product button is)

Example HTML Integration

Create an index.html file with the following content. Replace YOUR_PUBLIC_API_KEY with the key you obtained from your Snipcart dashboard.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Snipcart Store</title>

    <!-- Snipcart CSS -->
    <link rel="stylesheet" href="https://cdn.snipcart.com/themes/v3.4.0/default/snipcart.css" />
</head>
<body>

    <h1>Welcome to My Shop!</h1>

    <!-- Product Definition -->
    <div>
        <h2>Awesome Gadget</h2>
        <p>This gadget will improve your life dramatically!</p>
        <button
            class="snipcart-add-item"
            data-item-id="awesome-gadget"
            data-item-price="29.99"
            data-item-url="/"
            data-item-description="A truly awesome gadget"
            data-item-image="https://via.placeholder.com/150"
            data-item-name="Awesome Gadget"
        >
            Add to cart ($29.99)
        </button>
    </div>

    <!-- Snipcart JS -->
    <script
        async
        src="https://cdn.snipcart.com/themes/v3.4.0/default/snipcart.js"
    ></script>
    <div
        hidden
        id="snipcart"
        data-api-key="YOUR_PUBLIC_API_KEY"
        data-config-add-product-behavior="none"
    ></div>

</body>
</html>

Save this file and open it in your web browser. When you click the "Add to cart" button, the Snipcart shopping cart should appear, demonstrating a successful initial integration. The data-item-url="/" attribute specifies the URL Snipcart should use to validate the product; for simple static sites, the root path is often sufficient. More complex setups might specify a dedicated product page URL or an API endpoint.

For a detailed explanation of product definition attributes, consult the Snipcart product definition documentation.

Common next steps

Once you have a basic Snipcart integration functioning, several common next steps can enhance your e-commerce setup:

  • Customize the Cart Appearance: Snipcart allows for extensive customization of its styling to match your website's aesthetic. You can override default CSS or use Snipcart's theming options. Refer to the Snipcart customization guide.
  • Implement Advanced Product Options: For products with variations (e.g., size, color), Snipcart supports defining options using additional HTML attributes. This allows customers to select preferences before adding items to their cart. See Snipcart product options documentation.
  • Configure Payment Gateways: Snipcart integrates with various payment providers. You can enable and configure these through your Snipcart dashboard under Store > Payment Gateways. Popular options include Stripe, PayPal, and Square. Each gateway requires specific credentials and configuration.
  • Set Up Shipping and Taxes: Define shipping methods, rates, and tax rules within the Snipcart dashboard. This ensures accurate calculations during checkout. Explore the Snipcart shipping configuration.
  • Utilize Webhooks: For server-side processing, integrate Snipcart webhooks. These allow your application to receive notifications about events like new orders, order status changes, or abandoned carts, enabling custom backend logic. The Snipcart webhook documentation provides details on setup and event types.
  • Manage Inventory: Configure inventory tracking for your products in the Snipcart dashboard or via the API to prevent overselling.
  • Deploy to Production: Ensure your website is accessible, your API key is correct, and all configurations (shipping, taxes, payment gateways) are finalized before promoting your site.

Troubleshooting the first call

If your Snipcart integration does not function as expected during the initial setup, consider the following common issues and debugging steps:

  • Incorrect API Key: Double-check that the data-api-key attribute in your <div id="snipcart"> element precisely matches your Public API Key from the Snipcart dashboard. Even a single character mismatch will prevent Snipcart from loading.
  • Missing or Incorrect Script/CSS Files: Verify that both the Snipcart CSS (snipcart.css) and JavaScript (snipcart.js) files are correctly linked in your HTML, including the async attribute for the script. Ensure the URLs are correct and accessible.
  • Product Attributes Syntax Errors: Review your product definition HTML attributes (e.g., data-item-id, data-item-price, data-item-name). Incorrect spelling, missing attributes, or invalid values will prevent the item from being added to the cart. For example, data-item-price must be a valid number.
  • Console Errors: Open your browser's developer console (usually F12 or right-click > Inspect > Console tab). Look for JavaScript errors related to Snipcart. These messages often provide specific clues about what went wrong.
  • Network Issues: In the developer console's "Network" tab, check if the Snipcart script and CSS files are loading successfully (HTTP status 200). If they are failing to load, there might be a network issue or an incorrect URL.
  • data-item-url Validation: Snipcart validates product information against the URL specified in data-item-url. If this URL is inaccessible or does not contain the product data Snipcart expects (e.g., an HTML element with the same data-item-id), the product might not be added. For static sites, data-item-url="/" is common, but for dynamic sites, it should point to a valid product page.
  • CORS Policy: While less common for basic Snipcart.js integration, if you are making custom API calls to Snipcart from a different origin, ensure your server-side configuration handles Cross-Origin Resource Sharing (CORS) correctly.
  • Snipcart Dashboard Status: Check your Snipcart dashboard for any alerts or status messages that might indicate issues with your account or configuration.

By systematically checking these points, you can typically identify and resolve most initial integration problems.