CONTRACT-REVIEWED STARTING PATTERNS

Start from the boundary, not a logo wall.

Use the synthetic Shopify and Klaviyo mapping pack plus three reviewed Loyumi patterns while your systems keep credentials, identity, fulfillment, and customer communication authority.

API 1.13.0SDK 2.3.0Mapping status · configuration_required

Download SDK Open Sandbox

SDK 2.3.0 · MERCHANT-OPERATED MAPPING CONFORMANCE

Map Shopify facts to Loyumi, then build Klaviyo requests—without claiming a connector.

The downloadable SDK contains dependency-free Shopify webhook normalizers, Klaviyo request builders, and eight deterministic synthetic contract vectors. The pack performs no network request, looks up no credential, installs no provider app, and leaves provider status configuration_required.

Bundled local conformance transcript

contractVersion       shopify-klaviyo-merchant-mapping.v1
result                passed
vectors               8 / 8 passed
fixtureClass          synthetic_nonfinancial
providerStatus        configuration_required
nextEligibleStatus    api_verified
shopifyApiVersion     2026-07
klaviyoApiRevision    2026-07-15
runner I/O            none
provider credentials  none

Shopify paid order

Maps exact merchandise, discount, tax, shipping, customer or guest identity, source reference, request ID, and replay-stable idempotency evidence from orders/paid.

Shopify refund

Maps exact selected merchandise lines for partial or full-merchandise refunds/create events and fails closed on unsupported adjustments, duties, unsettled transactions, and ambiguous totals.

Consent separation

Discards the Shopify email address and reports an email-marketing withdrawal without silently converting it into Loyumi program-consent withdrawal.

Klaviyo requests

Builds profile-import and lifecycle-event envelopes using external_id only, a stable retry ID, and revision 2026-07-15. It does not add authorization or mutate email or SMS subscriptions.

Exact paid-order controls
shopify_paid_member_exact_totals

Opaque guest identity
shopify_paid_guest_order_scoped_identity

Stable semantic replay
shopify_paid_duplicate_semantic_replay

Exact partial refund
shopify_partial_refund_exact_lines

Exact full refund
shopify_full_merchandise_refund_exact_lines

Separate consent domains
shopify_email_withdrawal_is_not_loyalty_mutation

External-ID-only profile
klaviyo_profile_external_id_only

Stable event retry ID
klaviyo_event_stable_retry_id

MERCHANT GATES

Authority and real evidence

Verify Shopify HMAC against the exact raw webhook body before setting hmacVerified: true.
Complete Shopify protected-customer-data and privacy/compliance review for the fields and topics actually used.
Attach minimum-scope Klaviyo private credentials only inside trusted server infrastructure: profiles:write or events:write.
Run real Sandbox or test-store delivery, retry, return, identity, consent, privacy, and reconciliation checks before Production.

PROVIDER GATES

Current external contracts

Review Shopify webhook topics and versions.
Review Shopify protected customer data and mandatory privacy webhooks.
Review Klaviyo profile import for the pinned revision.
Review Klaviyo Marketplace submission; live-install and API-activity evidence remain external to this package.

STARTER 01 · COMMERCE EARN + RETURN

Use the order as the durable business fact.

The reviewed SDK 2.3.0 pattern keeps credentials on the server, uses integer minor currency units, maps one purchase source reference to one stable idempotency key, and reverses exact original lines when possible.

Server-side commerce starter

import { LoyumiClient } from "@loyumi/sdk";

const loyumi = new LoyumiClient({
  apiKey: process.env.LOYUMI_API_KEY!,
  environment: process.env.LOYUMI_ENVIRONMENT_ID!,
});

await loyumi.postPurchase({
  type: "purchase.completed",
  programId: "prg_rewards",
  externalCustomerId: "customer_123",
  amountMinor: 4599,
  channel: "web",
  sourceReference: "order_10042",
}, { idempotencyKey: "purchase:order_10042" });

await loyumi.postReturn({
  sourceReference: "order_10042",
  returnReference: "return_10042_1",
  items: [{ lineReference: "line_2", quantity: 1 }],
}, { idempotencyKey: "return:return_10042_1" });

MERCHANT OWNS

Commerce truth

Authenticated customer mapping and program consent
Order, currency, line, tax, discount, and return truth
Stable source and line references across retries
Queueing, monitoring, and reconciliation to the order system

LOYUMI GOVERNS

Loyalty effect

Rule evaluation and exact decision evidence
Idempotent award or replay result
Balanced ledger movement and derived balances
Source-linked clawback without deleting history

STARTER 02 · REWARD GIFTING

Gift a recipient-bound outcome—not transferable points.

Reward Gifts lets one enrolled member spend points to offer another enrolled member a choice of one to four catalog entitlements. The resulting entitlement is single-use, noncash, nontransferable, nonreloadable, non-regiftable, and non-resellable.

Invitation-first framework excerpt

const invited = await gifts.createInvitation({
  operationId: "gift:order_10042",
  programId: "prg_rewards",
  rewardIds: ["rew_dinner", "rew_movie"],
  personalization: {
    message: "Thank you for everything.",
    occasion: "A small thank-you",
    theme: "thank_you",
    locale: "en-US",
  },
  delivery: {
    mode: "immediate",
    channel: "email",
    destinationReference: "contact-vault:recipient-42",
  },
  senderContext: authenticatedSenderSession,
  recipientContext: authenticatedInvitation,
}, { onCheckpoint: saveEncryptedCheckpoint });

Open complete Reward Gifts guide Explore customer experience

STARTER 03 · SIGNED WEBHOOKS

Verify raw bytes, then deduplicate before changing state.

SDK 2.3.0 verifies HMAC-SHA256 over the timestamp and exact raw request body, accepts the versioned signature, and rejects stale timestamps by default. Event-ID persistence is still required because timestamp validation alone does not prevent every replay.

Signed webhook receiver

import { verifyWebhookRequest } from "@loyumi/sdk";

export async function POST(request: Request) {
  const valid = await verifyWebhookRequest(request, {
    secret: process.env.LOYUMI_WEBHOOK_SECRET!,
  });
  if (!valid) return new Response("Invalid signature", { status: 401 });

  const eventId = request.headers.get("X-Loyumi-Event-Id");
  if (!eventId || await alreadyProcessed(eventId)) {
    return new Response(null, { status: 204 });
  }
  const event = await request.json();
  await applyOnce(eventId, event);
  return new Response(null, { status: 204 });
}

WHAT VERIFIED MEANS HERE

Contract-reviewed starters, not turnkey connector certification.

reviewed against

Public API 1.13.0, SDK 2.3.0, 121 operations across 106 paths, 40 webhook events, portability schema 1.6.0, Shopify webhook API 2026-07, and Klaviyo revision 2026-07-15.

not claimed

A native or connected provider integration, broad first-party connector catalog, public package-registry presence, merchant adoption, production scale, external certification, SLA coverage, or implementation inside your systems.

before production

Run the starter with your own identity, commerce, delivery, reconciliation, failure, privacy, and support requirements in Sandbox; record the evidence and owners.

Download SDK 2.3.0 Review OpenAPI 1.13.0 Discuss an integration