{"templateId":"GuidePage","sharedDataIds":{"sidebar":"sidebar-miniapps/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["callout"]},"type":"markdown"},"seo":{"title":"Sync","description":"Developer API, partner integration, MCP, SDK, and customer help center.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"sync","__idx":0},"children":["Sync"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["E-commerce and catalog MiniApps use the top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sync"]}," block for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["bulk import"]}," (initial and scheduled sync) and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["realtime webhook handlers"]}," that share the same field-mapping vocabulary."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sync"]}," when your integration must keep orders, customers, products, or carts aligned between an external platform and Karzoun — not just fire automation triggers."]},{"$$mdtype":"Tag","name":"Callout","attributes":{"type":"info","title":"See also"},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/miniapps/guides/webhooks"},"children":["Webhooks"]}," — Event extraction, verification, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerExtraction"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/miniapps/examples/salla"},"children":["Salla example"]}," — Full OAuth + webhook + sync pattern"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/miniapps/guides/ecommerce"},"children":["E-commerce overview"]}," — When to use sync vs triggers-only"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"structure","__idx":1},"children":["Structure"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"sync: {\n  baseUrl: 'https://api.example.com/v2',\n  headers: {\n    Authorization: 'Bearer [[accessToken]]',\n    'Content-Type': 'application/json',\n  },\n  syncConfiguration: {\n    enabled: true,\n    batchSize: 200,\n    rateLimitPerSecond: 10,\n    timeout: 30000,\n  },\n  resources: {\n    products: { /* ... */ },\n    customers: { /* ... */ },\n    orders: { /* ... */ },\n  },\n  webhooks: {\n    handlers: {\n      'order.created': { /* same mapping style as resources */ },\n    },\n  },\n},\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Block"},"children":["Block"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["baseUrl"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["headers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Shared prefix for all sync HTTP calls (supports ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["[[accessToken]]"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["syncConfiguration"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Batch size, rate limits, timeouts for bulk jobs"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resources.*"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paginated list/detail endpoints + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiMapping"]}," into Karzoun content types"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooks.handlers"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Realtime create/update mappings keyed by event name"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resource-definition","__idx":2},"children":["Resource definition"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each key under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resources"]}," defines one importable entity:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"products: {\n  name: 'products',\n  displayName: 'Products',\n  description: 'Sync products from your platform',\n  contentType: 'core:product',\n  expandDetails: true,\n  endpoints: {\n    list: { url: '/products', method: 'GET' },\n    details: { url: '/products/{id}', method: 'GET' },\n  },\n  pagination: {\n    paramName: 'per_page',\n    defaultLimit: 60,\n    maxLimit: 1000,\n  },\n  responseMapping: {\n    dataProperty: 'data',\n    totalProperty: 'pagination.total',\n  },\n  apiMapping: {\n    name: 'name',\n    code: { path: 'id', transform: 'toString' },\n    unitPrice: { paths: ['price.amount', 'regular_price.amount'], transform: 'coalesce' },\n    // ...\n  },\n  icon: 'package',\n},\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contentType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Target Karzoun entity (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["core:product"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["core:customer"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ecommerce:orders"]},", …)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endpoints.list"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Paginated collection fetch"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endpoints.details"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional per-record enrichment when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expandDetails: true"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiMapping"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Field mapping rules (paths, transforms, literals) — same schema as webhook handlers"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"mapping-transforms","__idx":3},"children":["Mapping transforms"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common transforms used in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiMapping"]},":"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Transform"},"children":["Transform"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Use"},"children":["Use"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["toString"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Coerce IDs to strings"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["toNumberOrNull"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Numeric fields with null fallback"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["coalesce"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["First non-empty path in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paths"]}," array"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["compute"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fn"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Platform-specific helpers (document custom ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fn"]}," names in your submission)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mapItems"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Line items in orders/carts"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["joinCodes"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Discount/coupon code arrays"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"webhook-handlers-under-sync","__idx":4},"children":["Webhook handlers under sync"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Realtime events use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sync.webhooks.handlers"]}," (preferred over legacy ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook.ecommerce"]},"):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"sync: {\n  // ... resources ...\n  webhooks: {\n    handlers: {\n      'order.created': {\n        recordType: 'order',\n        operation: 'create',\n        mapping: {\n          code: '$.data.id',\n          orderNumber: '$.data.reference_id',\n          status: '$.data.status.name',\n          totalAmount: '$.data.amounts.total.amount',\n          items: { path: '$.data.items', transform: 'mapItems' },\n        },\n      },\n      'order.status.updated': {\n        recordType: 'order',\n        operation: 'update',\n        mapping: {\n          code: '$.data.id',\n          status: '$.data.status.name',\n        },\n      },\n    },\n  },\n},\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Pair every handler event with a matching ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/miniapps/guides/triggers"},"children":["trigger"]}," so automations can react after sync processing."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"bulk-sync-lifecycle","__idx":5},"children":["Bulk sync lifecycle"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tenant installs MiniApp and completes OAuth / API key setup."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Karzoun runs enabled ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["resources"]}," according to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["syncConfiguration"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ongoing changes arrive via provider webhooks → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sync.webhooks.handlers"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Rate limits and batch sizes protect both your API and Karzoun workers."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"submission-checklist","__idx":6},"children":["Submission checklist"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," List + detail endpoints tested with sandbox credentials"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiMapping"]}," covers required fields for each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contentType"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Webhook handler events match ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["triggers[].event"]}," strings exactly"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Pagination ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["responseMapping"]}," matches your provider's JSON shape"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"input","attributes":{"checked":false,"type":"checkbox","readOnly":true},"children":[]}," Sample payloads included in your ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/miniapps/guides/submission"},"children":["submission package"]}]}]}]},"headings":[{"value":"Sync","id":"sync","depth":1},{"value":"Structure","id":"structure","depth":2},{"value":"Resource definition","id":"resource-definition","depth":2},{"value":"Mapping transforms","id":"mapping-transforms","depth":3},{"value":"Webhook handlers under sync","id":"webhook-handlers-under-sync","depth":2},{"value":"Bulk sync lifecycle","id":"bulk-sync-lifecycle","depth":2},{"value":"Submission checklist","id":"submission-checklist","depth":2}],"frontmatter":{"title":"Sync","titleTranslationKey":"sidebar.miniapps.sync","audience":"developer","status":"published","locales":["en"],"template":"GuidePage","seo":{"title":"Sync"}},"lastModified":"2026-06-23T12:06:12.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/miniapps/guides/sync","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}