E-commerce and catalog MiniApps use the top-level sync block for bulk import (initial and scheduled sync) and realtime webhook handlers that share the same field-mapping vocabulary.
Use sync when your integration must keep orders, customers, products, or carts aligned between an external platform and Karzoun — not just fire automation triggers.
See also
- Webhooks — Event extraction, verification, and
customerExtraction - Salla example — Full OAuth + webhook + sync pattern
- E-commerce overview — When to use sync vs triggers-only
sync: {
baseUrl: 'https://api.example.com/v2',
headers: {
Authorization: 'Bearer [[accessToken]]',
'Content-Type': 'application/json',
},
syncConfiguration: {
enabled: true,
batchSize: 200,
rateLimitPerSecond: 10,
timeout: 30000,
},
resources: {
products: { /* ... */ },
customers: { /* ... */ },
orders: { /* ... */ },
},
webhooks: {
handlers: {
'order.created': { /* same mapping style as resources */ },
},
},
},| Block | Purpose |
|---|---|
baseUrl + headers | Shared prefix for all sync HTTP calls (supports [[accessToken]]) |
syncConfiguration | Batch size, rate limits, timeouts for bulk jobs |
resources.* | Paginated list/detail endpoints + apiMapping into Karzoun content types |
webhooks.handlers | Realtime create/update mappings keyed by event name |
Each key under resources defines one importable entity:
products: {
name: 'products',
displayName: 'Products',
description: 'Sync products from your platform',
contentType: 'core:product',
expandDetails: true,
endpoints: {
list: { url: '/products', method: 'GET' },
details: { url: '/products/{id}', method: 'GET' },
},
pagination: {
paramName: 'per_page',
defaultLimit: 60,
maxLimit: 1000,
},
responseMapping: {
dataProperty: 'data',
totalProperty: 'pagination.total',
},
apiMapping: {
name: 'name',
code: { path: 'id', transform: 'toString' },
unitPrice: { paths: ['price.amount', 'regular_price.amount'], transform: 'coalesce' },
// ...
},
icon: 'package',
},| Field | Description |
|---|---|
contentType | Target Karzoun entity (core:product, core:customer, ecommerce:orders, …) |
endpoints.list | Paginated collection fetch |
endpoints.details | Optional per-record enrichment when expandDetails: true |
apiMapping | Field mapping rules (paths, transforms, literals) — same schema as webhook handlers |
Common transforms used in apiMapping:
| Transform | Use |
|---|---|
toString | Coerce IDs to strings |
toNumberOrNull | Numeric fields with null fallback |
coalesce | First non-empty path in paths array |
compute + fn | Platform-specific helpers (document custom fn names in your submission) |
mapItems | Line items in orders/carts |
joinCodes | Discount/coupon code arrays |
Realtime events use sync.webhooks.handlers (preferred over legacy webhook.ecommerce):
sync: {
// ... resources ...
webhooks: {
handlers: {
'order.created': {
recordType: 'order',
operation: 'create',
mapping: {
code: '$.data.id',
orderNumber: '$.data.reference_id',
status: '$.data.status.name',
totalAmount: '$.data.amounts.total.amount',
items: { path: '$.data.items', transform: 'mapItems' },
},
},
'order.status.updated': {
recordType: 'order',
operation: 'update',
mapping: {
code: '$.data.id',
status: '$.data.status.name',
},
},
},
},
},Pair every handler event with a matching trigger so automations can react after sync processing.
- Tenant installs MiniApp and completes OAuth / API key setup.
- Karzoun runs enabled
resourcesaccording tosyncConfiguration. - Ongoing changes arrive via provider webhooks →
sync.webhooks.handlers. - Rate limits and batch sizes protect both your API and Karzoun workers.
- List + detail endpoints tested with sandbox credentials
-
apiMappingcovers required fields for eachcontentType - Webhook handler events match
triggers[].eventstrings exactly - Pagination
responseMappingmatches your provider's JSON shape - Sample payloads included in your submission package