Example use cases

Worked integration scenarios for product, retail, and catalog partners.

These are the implementation patterns most partners start with. Each one uses the same building blocks: customer, connection, consent, events, profile read.

1. In-app personalization

Who: A consumer app that already has logged-in users.

Consent: personalization, analytics

What you send: Views, saves, self-labels, and purchases as events.

What you get back: Resolved facts (favorite_series, recent objects) and habit / outcome intents for that user.

How you use it: Reorder home-shelf modules, highlight a collection the user is completing, or hide objects they have already purchased.

const intents = await swapnice.profiles.intents(customerId, {
  consent_purpose: "personalization",
  category: "habit",
});

const primary = intents.data[0];
if (primary && primary.confidence >= 0.7) {
  return { shelf: "continue_collection", object: primary.object };
}

2. Retail or event checkout

Who: A merch site, POS, or stadium iPad flow.

Consent: Collected at account creation or checkout. Typical purposes: personalization and analytics.

What you send: purchase.completed with SKU, amount, and optional location or storefront context.

What you get back: A high-confidence outcome intent plus a processed event id you can join to the order.

How you use it: Confirm that Swapnice received the conversion, then use later profile reads to see whether the buyer is a completionist, a first-time buyer, or a fandom affiliate.

This is the pattern for a partner that already has Shopify or POS events and wants Swapnice to turn them into consented profile intelligence.

A concrete stadium shape we already design for:

1. Account creation (or a short iPad form) requires Swapnice connect — consent is not a buried toggle
2. JS SDK on the merch site (for example a Shopify storefront) sends views and purchases
3. POS / iPad at the venue sends the same purchase.completed body from the checkout lane
4. The partner app can later show the user “everything you bought from us” using their own orders plus Swapnice intents for what they are likely to complete next

Consent is part of getting the app or completing checkout, not an optional afterthought.

3. Catalog-aware collectibles

Who: A partner whose objects are cards, SKUs, or fandom entries.

What you send: Ontology-backed entries (ygo, pokemon, …) and events that reference those entry ids.

What you get back: Intents keyed to catalog objects, so a completionist on a set is a well-defined profile fact rather than free text.

await swapnice.entries.upsert({
  ontology: "ygo",
  owner_id: "partner_catalog",
  ingestion_origin: "partner_catalog",
  entry_name: "Blue-Eyes White Dragon",
  fields: {
    name: "Blue-Eyes White Dragon",
    yugipedia_uid: "46986414",
    pcid: "2560454",
  },
});

4. Consent change and suppression

Who: Any production integration.

What happens: The user revokes personalization in Swapnice or via the partner.

What you must do:

await swapnice.consentReceipts.revoke(receiptId, {
  purposes: ["personalization"],
  reason: "user_request",
});

Immediately:

• New personalization events are rejected
• Profile reads with consent_purpose=personalization return 403
• The partner product must stop using that customer’s intelligence for the revoked purpose

Implement this path before go-live.

Suggested first slice

For a design-partner pilot, implement one narrow slice rather than every use case:

1. One consent flow (personalization + analytics)
2. One or two event families (purchase.completed and collection.interacted)
3. One profile read in the partner backend
4. One sandbox test user walked through the testing process

That is enough for a productive technical session: your team can bring real payloads and questions instead of reviewing the contract in the abstract.