Klaviyo events from GoCommerce

What it does

Configuration

One setting is required: a private API key. Set it in Config — the reference binary’s -klaviyo flag reads KLAVIYO_PRIVATE_KEY — or on the Plugins screen, which wins.

The module reads its Config struct, not the environment. The variable names are the ones the package’s own example or the reference binary uses; in your own main() you choose where each value comes from. Where a setting has a panel label, the admin’s settings drawer can hold it too, and a value typed there wins over Config.

Setting it up

1. Create a private keyIn Klaviyo, a private API key with events:write and profiles:write. Note the six-character public key too, if the storefront will run Klaviyo’s tracking.
2. Install the modulePass klaviyo.New to gocommerce.New, as below, or start the reference binary with -klaviyo and KLAVIYO_PRIVATE_KEY set.
3. Switch it onA private key in Config switches it on. Otherwise enable Klaviyo on the Plugins screen and paste the key there — and the public key, if the storefront needs it.
4. Build flows on the metricsThe six metrics arrive as orders and carts do. GET /api/admin/x/klaviyo/status shows whether it is on, how many events were sent and failed, and the last error.

import (
	"os"

	"github.com/itswadesh/gocommerce/core"
	"github.com/itswadesh/gocommerce/ext/klaviyo"
)

app, err := gocommerce.New(cfg, klaviyo.New(klaviyo.Config{
	PrivateKey: os.Getenv("KLAVIYO_PRIVATE_KEY"),
}))

How it works

• Subscribed, not polled

  The module subscribes to order.* and cart.abandoned on the engine’s event bus and sends as events are dispatched. Order events it has no metric for — edits, returns, reversals — are ignored.

• De-duplicated by Klaviyo

  Each event’s unique_id is the engine’s event id, plus the SKU for Ordered Product, so when the engine redelivers an event Klaviyo treats it as the one it already has.

• Two tries, then a count

  A failed POST is tried once more after a second. A second failure is logged, counted on the status route and dropped — never returned to the engine.

• Values in major units

  The engine holds minor units and Klaviyo wants 19.99, not 1999. The module converts with the currency’s own decimals — none for yen, three for dinar.

• An email or nothing

  An order or cart without an email is skipped, because the profile is keyed on it. Emails are lower-cased, and a name is split at its last space into first and last.

• The public key, for the storefront

  The panel’s public key is marked public, so a storefront can read it from GET /api/plugins and load Klaviyo’s onsite tracking and signup forms.

What it does not do

Read these before an order depends on it. No store is known to run GoCommerce in production yet, so these come from the code, not from anyone’s experience.

• Abandoned carts arrive lateThe engine marks a cart abandoned when it expires — 30 days after it was last changed, by default (Config.CartTTL). Started Checkout waits for that, so a timely abandoned-cart flow needs a shorter CartTTL.
• Placed means createdPlaced Order fires when the order is created, before it is paid — cash-on-delivery orders included. Paid, delivered, edited and returned orders send no event.
• Best effortAn event that fails twice is dropped, not queued for later. The sent and failed counts live in memory and reset on restart.
• No history, no consentOnly events from the moment it is switched on; nothing is backfilled. It posts events and does not subscribe anyone to email or SMS marketing.
• The cart token leaves the storeStarted Checkout carries the cart’s token as CartToken, for a recovery link. The engine treats that token as a credential for the basket, and it now sits in Klaviyo too.
• Config.PublicKey is not readOnly a public key typed on the Plugins screen reaches the storefront. The reference binary reads KLAVIYO_PUBLIC_KEY into Config, where nothing uses it.