Connect your shop

A shop sends Emailit two kinds of data: the catalog and orders from its backend, with the API, and what visitors do on the site, with the tracking script of Event tracking. Use both for the full picture: the API is the reliable record of orders, and the script adds product views, carts and visitors who arrive from your emails.

Before you begin

• An API key for the backend calls. An Events Only key can send products, orders and carts, the same key that sends events from your backend. It can’t read anything back, so its responses hold only object, id and external_id. Use a Full Access key to also read data, manage coupons or change settings.
• For the tracking script, permission to add a script to your shop’s pages.

Send data from your backend

Products

Send your catalog with Create or update products in bulk, and again whenever products change. Each product is identified by your shop’s product ID, so sending it again updates it.

curl https://api.emailit.com/v2/products/batch \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [{
      "id": "1234",
      "title": "Trail Runner GTX",
      "url": "https://shop.example.com/products/trail-runner",
      "image_url": "https://shop.example.com/images/trail-runner.jpg",
      "price": 139,
      "compare_at_price": 169,
      "currency": "EUR",
      "categories": ["Shoes", "Running"],
      "inventory_quantity": 40
    }]
  }'

Product feeds in emails leave out archived products and products with an inventory of 0, so keep status and inventory_quantity up to date.

Orders

When an order is placed, send it with Create or update an order:

curl https://api.emailit.com/v2/orders \
  -X POST \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "1001",
    "email": "jane@example.com",
    "currency": "EUR",
    "total": 125,
    "shipping": 5,
    "coupon_codes": ["WLC-8K2M4P"],
    "cart_id": "cart_789",
    "items": [{ "product_id": "1234", "title": "Trail Runner GTX", "quantity": 1, "price": 120 }]
  }'

• id is your shop’s order number. Sending the same id again updates the order instead of adding another.
• Emailit credits the order to the email the buyer last clicked or opened. See How orders are credited.
• The buyer becomes a contact if they aren’t one. Add "accepts_marketing": true and an audience_id to also subscribe them, for example when they ticked a newsletter box at checkout. "create_contact": false skips creating a contact. The tracking script’s purchase command never creates or subscribes a contact.
• cart_id marks that cart as converted.

When the order is paid, fulfilled, canceled or refunded, send the change with Update an order, or send the order again with its new status. Canceled orders don’t count toward revenue, and refunds are subtracted.

Past orders

Import your order history with Import orders in bulk, up to 1,000 orders per request. Imports are historical by default: they fill purchase history, metrics and recommendations, but aren’t credited to emails and don’t start automations.

The tracking script

The tracking script records what visitors do on your site: product views, the cart, purchases and visits. It also recognizes visitors who arrive from your emails, so their activity belongs to their contact.

Add the script

1. Create a tracking key. On Email API›Events, open the Tracking tab and select Create tracking key. Under Allowed origins, list your shop’s domains, for example shop.example.com or *.example.com. Leave it empty to accept any site.

2. Add the snippet to every page, before </head>. The Tracking tab shows it with your key filled in:

   HTML

   <script>window.emailit=window.emailit||function(){(window._emailitq=window._emailitq||[]).push(arguments)};</script>
   <script async src="https://js.emailit.com/track/TRACKING_KEY/events.js"></script>

   Tracking keys are public: they can only send events, never read data. If the Emailit forms script is already on the page, keep both.

To also record a page view on every page, add data-autotrack="pages" to the script tag. Page views update when the contact was last active on your site and their time zone; they aren’t stored as events.

Record shop activity

Call these where they happen:

// Product page
emailit("product", { id: "1234", title: "Trail Runner GTX", url: location.href,
  image_url: "https://shop.example.com/images/trail-runner.jpg", price: 139, currency: "EUR",
  categories: ["Shoes", "Running"] });

// Every time the cart changes
emailit("cart", { id: "cart_789", currency: "EUR", checkout_url: "https://shop.example.com/checkout",
  items: [{ product_id: "1234", title: "Trail Runner GTX", quantity: 1, price: 139 }] });

// Order confirmation page
emailit("purchase", { id: "1001", total: 125, currency: "EUR",
  items: [{ product_id: "1234", quantity: 1, price: 120 }], coupon_codes: ["WLC-8K2M4P"] });

Identify visitors

Activity counts for a contact once the script knows who the visitor is:

• From an email link. When a contact clicks a link in a campaign or automation email that leads to your site, the link carries a signed _eit parameter. The script stores it and removes it from the address bar. Links get it when click tracking is on and the link goes to an allowed origin of a tracking key, or, for keys without allowed origins, to your sending domain.

• When they sign in or check out, call identify with their email address or contact ID:

  JavaScript

  emailit("identify", { email: "jane@example.com" });

• When they sign out, call emailit("reset") to forget them on that browser.

Product views and carts from before the visitor was identified are moved to the contact. The script also records the browser’s time zone, which Recipient’s local time sending uses, and when the contact was last active on your site.

emailit("debug", true) logs what the script sends to the browser console.

Where the activity shows up

Shop activity goes to the same event log as your other events. Product views become product.viewed events, new or changed carts cart.updated, and purchases order.placed. You see them on Email API›Events and in the contact’s activity, and webhooks can subscribe to them. product.viewed and cart.updated aren’t part of All events, so subscribe to them by name. See Commerce events.

Verify it worked

• Email Marketing›Commerce shows your products and orders, and Carts shows carts from the script.
• Email API›Events lists product.viewed, cart.updated and order.placed events as visitors browse and buy.
• Open a contact who ordered: the Purchases card shows their orders, total spent and recently viewed products.
• After a campaign, orders credited to it show on its Revenue tab.

Related