Overview

Cartly's integration engine supports two-way catalog synchronization between a shop and an external ERP or inventory-management system. A catalog integration keeps products, stock, prices, images, and option-based variants current in both directions, and exports placed/paid orders back to the source system. This guide documents the configuration model shared by catalog-sync connectors — it applies to any external system, not a specific product.

A catalog integration is registered like any other integration_connector (see the Webhooks and Apps API guides for the base connector model), with catalog-sync settings persisted as a JSON configuration blob on the connector.

Field-Level Sync Control

A catalog connector exposes a set of boolean toggles gating which fields a sync run is allowed to overwrite on an already-imported product:

• name, description
• images
• sku / barcode
• weight
• attributes — master switch for custom attribute→metafield sync

Stock and price are implicitly always synced. Fields left off are never overwritten, so merchant-edited fields in Cartly are not clobbered by the next sync.

Price List Mapping

External systems commonly expose multiple price lists (retail, wholesale, and so on). A catalog connector maps individual price lists to Cartly's three variant price fields:

• Price — variant.price, the storefront selling price
• Compare-at price — variant.compare_at_price, shown struck through on sale
• Cost — variant.cost_price, cost of goods used for margin reporting

Each mapping stores a reference to the source price list; unmapped price fields are left untouched by sync.

Custom Attribute → Metafield Mapping

Custom product attributes from the source system map to Cartly product metafields via a list of mapping entries, each specifying:

• the source attribute name/id
• an enabled flag
• the target metafield namespace and key
• the target metafield value_type (defaults to single_line_text)

Mappings only apply on import when the attributes sync field is enabled and the individual mapping is enabled.

Product Matching on First Import

When a catalog integration is connected to a shop that already has products, the connector matches existing Cartly products to source-system records to avoid duplicates, using either or both:

• Match by SKU
• Match by barcode

Both default to enabled. Records that do not match an existing product by SKU or barcode are created as new products. Products in the source system that use per-attribute modifications (color, size, and so on) are grouped into a single Cartly product with the matching options/variants generated, using the same option/variant model documented in the theme and product APIs.

Order Export

Placed and paid Cartly orders export back to the external system, including tax passed through as a line item or rate depending on the target system's model. The export trigger is configurable per connector: on_placement (as soon as the order is created) or on_payment (only once payment is confirmed) — useful for systems that should not see unpaid orders. Monetary values are converted from Cartly's internal int64 cents to the decimal format the external system expects.

Reliability: Webhooks Plus Scheduled Safety Sync

Catalog integrations receive real-time updates via inbound webhooks from the source system. Because most external systems do not guarantee webhook delivery, a Temporal-scheduled poll runs on a fixed interval (typically every 15–30 minutes) as a safety net, reconciling any changes a webhook may have missed. Poll-fallback activities are idempotent, so a change already applied via webhook is a no-op when the scheduled sync later reprocesses it.

Monitoring

Each connector run is recorded as an integration_execution with success/failure status and error detail, visible on the connector's detail page in the admin. Use this history to diagnose field-mapping issues or transient external-system errors before re-running a sync.