Archetypes

The @shopimind/integration-kit-js kit is not specialized for one type of product: it is a generic foundation. All integrations rely on the same small set of building blocks — custom data, events, widgets, synchronization (with dedicated sources) and inbound middleware. Here is how four common archetypes combine them.

Archetype	Custom data	Events	Widgets	Sync + withSource	Inbound middleware
Loyalty	✅	✅	✅	—	✅
Reviews	✅	✅	○	—	✅
Point of sale (POS)	○	○	○	✅	○
CRM	✅	○	—	○	✅

✅ central · ○ optional depending on the need · — rarely used

Two clarifications that shape every archetype

• ctx.withSource (dedicated sources) is a catalog primitive — it source-tags the e-commerce bulkSave* writes. It is central to POS and is not used by Loyalty/Reviews/CRM, which work with custom data + events + inbound.
• Contacts are never written directly (there is no contact-write API). A contact is materialized by the customers sync; you then enrich it with custom-data records linked to the contact (relation: { by: 'email' | 'id_contact', value }). So a loyalty profile, a CRM score or a review aggregate is a custom-data record on the contact — read it back with SpmCustomDataRecords.list(ctx.spm, definitionId, query).

Loyalty

A loyalty program enriches the contact profile and reacts to point gains.

• Custom data — a loyalty profile (point balance, tier, expiration date) attached to the contact.
• Events — points_earned, tier_reached… to trigger marketing scenarios.
• Widgets — display the point balance or tier in emails.
• Inbound middleware — when a customer earns points on your side, your app calls an inbound route to reflect it in real time (profile update + triggerEvent).

No native catalog to push: a loyalty integration generally does not declare an e-commerce data source.

Reviews

A review service brings product/merchant reputation back into ShopiMind.

• Custom data — average rating, number of reviews, last review, attached to the contact or to a product.
• Events — review_created, review_replied… to follow up or thank.
• Inbound middleware — push a new review as soon as it is published.
• Widgets (optional) — a rating badge in emails.

Point of sale (POS)

A point of sale pushes the activity of physical points of sale alongside e-commerce. It is the "catalog" archetype, illustrated by the Hiboutik example.

• Multi-source synchronization — customers, orders (and possibly products) of each store, in a per-source SyncStep.
• withSource — each store is a dedicated source; entities are tagged with their id_data_source and their identifiers are namespaced, so they never overwrite the merchant's native catalog.
• Custom data / events (optional) — in-store purchase profile, "checkout" event.

CRM

A CRM synchronizes customer relationship attributes and reacts to changes.

• Custom data — segments, score, lifecycle stage, account owner.
• Synchronization (optional) — regular import of contacts and their attributes.
• Events / inbound middleware — push an update (segment change, new opportunity) in real time.

Compose freely

These archetypes are not closed boxes: a single integration can combine several building blocks (a POS that adds a loyalty program, a CRM that pushes reviews…). The kit lets you enable only what you need — each building block is independent.

Going further

• The integration kit — the full contract.
• Custom data · Events · Widgets
• Synchronize data · Inbound middleware
• Example: Hiboutik POS — the point-of-sale archetype, end to end.