website logo
Navigate through spaces
Chord Commerce
⌘K
Getting Started
CMS
Data
OMS
Integrations
👩‍💻Developer Tools
Shopify
Docs powered by archbee 

OMS / CMS Sync

Overview

Chord offers a tool we call the Sync Service, which enables syncing of product content and data between your Order Management System (OMS) and your Content Management System (CMS).

New features!

We are actively developing new features to help you make content syncing as seamless as possible. Check out our roadmap below for an overview of what's in the pipeline.

Terms

An integration is a service in your stack that has product-related content which can be synced.

This integration can be both an origin and a destination of content changes.

When acting as an origin, the integration will emit a change event when relevant content has changed.

When acting as a destination, an integration may receive changes to its content.

A change event can be a creation, mutation (update) or deletion event triggered in the origin integration.

The Sync Service only supports syncing content between a CMS-and-OMS pair. We do not support CMS-and-CMS, one-to-many or many-to-many integrations.

How does it work?

When a change is detected in the origin integration, a webhook will trigger a sync event in the Sync Service.

Once the service has authorized the event, it will fetch content for the impacted content entity on both origin and destination integrations.

It will then compare them and determine, with the help of your config and options, if a change needs to be synced at destination.

If no mutation is needed, the flow is stopped. For example, this can happen if a product attribute is updated at origin, but is not supported as a syncable attribute.

If a mutation is needed, the service will sync content at destination and trigger a notification to advertise the change.

If an error happens during the sync process, a notification will also be sent out to warn you of the failure.

For more detailed information, check the In Depth section.

What is synced exactly?

Each integration as a pre-determined set of attributes that will map to the corresponding attribute on the Sync Product which will in turn map to the other integration's corresponding attribute.

As an example, a Contentful product slug will map to the Sync Product's slug attribute. For Shopify, it is actually the product handle that will correspond to that slug.

For more information, take a look at each integration's data mapping.

Get Started

Configurations are currently only editable by the Chord team. Please reach out if you need to make any changes.

Environments

The Sync Service can support multiple OMS-and-CMS pairs.

This is typically how we are create multiple environments.

We highly recommend having at least 2 environments: production and staging.

Configuration & Options

Here's a list of the configuration and options needed for all integrations:



Default

Description

Sync Service API Key



The API key given to you by Chord.

Tenant Name



The tenant slug given to you by Chord for a given environment.

Allowed Origins

['contentful']

The list of allowed origins.

Description

false

If the description should sync or not.

Tags

false

If the tags should sync or not.

Debug Mode

false

If debug mode is enabled, the service will run, but will not sync content.

Notes

The tags feature can be used to keep tags between origin and destination in sync. If tags already exist on either integrations when that feature is turned on, it will override the tags at destination for the first sync of content from the origin. Once that first tag sync is achieved, the tags will stay in sync.

Supported Integrations

Contentful

Available as an Origin and a Destination.

Configuration & Options



Default

Description

Space ID



Your Contentful space ID.

Environment ID

master

Your Contentful environment ID.

Management Token

false

Your Contentful management token.

Setup

How to model your content

Contentful has various data models that make up a product. This includes the product itself, variants, product types, option types, and option values. Please take a moment to read over the Content Models portion of this documentation to familiarize yourself with these data models.

How to set up your webhook

Once you have all the necessary configuration in place, you will need to create a webhook in Contentful for each environment you have in your stack.

Here are the specific configuration you will need to use:

  • URL: https://sync.api.chord.co/sync
  • Content events:
    • Entry publish
    • Entry unpublish
  • Filters:
    • Environment ID equals the Contentful environment ID for that environment
    • Content Type ID in product,variant
  • Headers:
    • x-api-key : the API key given to you by Chord
    • x-chord-tenant-name : your tenant name for that environment
  • Payload: use the default payload

Usage

How to sync content from Contentful

If a Contentful product or variant is published (or unpublished), the sync service will attempt to publish it (and its related objects) to the destination.

Data Mapping

Product

@ Contenful

Notes

status

status



name

name



slug

slug



vendor

vendor



productType.name

productType.name



productType.slug

productType.slug



shortDescription

shortDescription



longDescription

longDescription

Note that we only support string or Markdown-like syncing. We do not support syncing rich text content type.

mainImage

mainImage

(see below)

images

images

(see below)

optionTypes

optionTypes

(see below)

tags

metadata.tags.$.sys.id

In Contentful, the tags are a system object. We map the strings from the Sync Product to the corresponding id .

variants

variant[]

(see below)

isGiftCard

giftCard



Variant

@ Contentful

Notes

name

nam



sku

sku

This is required to be an unique value in Contentful.

globalTradeItemNumber

globalTradeItemNumber



shopifyId

shopifyId

This value gets synced from Shopify to Contentful when the variant is created in Shopify. (to be deprecated)

price

price



regularPrice

regularPrice



mainImage

mainImage

(see below)

images

images

(see below)

optionValues

optionValues

(see below)

weight

weight



Image

@ Contentful

Notes

alt

title



fileType

contentType



fileName

fileName



url

url



Option Type

@ Contentful

Notes

name

name



slug

slug



presentation

presentation



optionValues

optionValues

(see below)

Option Value

@ Contentful

Notes

name

name



slug

slug



presentation

presentation



Notes

The Sync Service does not currently support syncing multiple locales in Contentful. This means that only content attached to the default locale will be synced (usually en-US).

Shopify

Available as an Origin and a Destination.



Default

Description

Admin Token



The Shopify Admin API password.

Shop Name



The Shopify shop name (get this from the shop URL before the .myshopify.com).

Sync Mode

denylist

Determine how a product is sync from Shopify to the destination.



If denylist, all products are synced unless they have a chord-no-sync tag.



If allowlist, only products that have a chord-sync tag will be synced.

Setup

How to authorize the Sync Service in Shopify

The Sync Service needs some authorization in Shopify to be able to change your content. This authorization is granted via a custom app.

The necessary permission scopes you will need to set are write_product_listings, read_product_listings, write_products, read_products.

How to add a webhook in Shopify

Your Shopify store will need three webhooks to be created for the service: one for each of the Product update and Product creation events.

The callback URL is https://sync.api.chord.co/sync.

Usage

How to sync content from Shopify

If a Shopify product or variant is saved (or updated), the sync service will attempt to publish it (and its related objects) to the destination.

How to use the allowlist / denylist feature

The Shopify sync mode is not user configurable. Please reach out to Chord if you wish to change the sync mode.

The Sync Service allows you to prevent or allow Shopify products to sync depending on the sync mode enabled.

There are two sync modes:

  • denylist(default): When this mode is enabled, all Shopify products will sync unless they have the chord-no-sync tag.
  • allowlist: When this mode is enabled, Shopify products will only be synced if they have the chord-sync tag.

Read more about adding tags in Shopify here.

Data Mapping

Product

@ Shopify

Notes

status

status



name

name



slug

slug



vendor

vendor



productType.name

productType



productType.slug

-



shortDescription

-


longDescription

descriptionHtml

Note that we only support string or Markdown-like syncing. We do not support syncing rich text or html values.

mainImage

-



variants.$.mainImage.$.file.url

images

Each mainImage of a variant will populate the images array in Shopify and be referenced back on the Shopify variant. Note that images will only sync to Shopify and not from Shopify

optionTypes.$.name

options



tags

tags



variants

variants

(see below)

isGiftCard

giftCard



Variant

@ Shopify

Notes

name

nam



sku

sku

This is required to be an unique value in Contentful.

globalTradeItemNumber

globalTradeItemNumber



shopifyId

shopifyId

This value gets synced from Shopify to Contentful when the variant is created in Shopify. (to be deprecated)

price

price



regularPrice

regularPrice



mainImage

mainImage

(see below)

images

images

(see below)

optionValues

optionValues

(see below)

weight

weight





size

(not supported)

Image

@ Shopify

Notes

alt

title



fileType

contentType



fileName

fileName



url

url



Option Type

@ Shopify

Notes

name

name



slug

slug



presentation

presentation



optionValues

optionValues

(see below)

Option Value

@ Shopify

Notes

name

name



slug

slug



presentation

presentatio



Notes

Images

We currently only sync product and variant images to Shopify and not from Shopify.

Slugs for Product Type, Option Type and Option Value data models

For our Product Type, Option Type and Option Value data models, we include a slug field. However, Shopify has no such field. This means that we need to generate this automatically. The sync service does this by creating a "slugified" version of the Product Type, Option Type or Option Value.

For example, if we create a product in Shopify with a Product Type of "Pants and Shorts", if there is not already a Product Type with a title of "Pants and Shorts" in the CMS, it will be created with a title of "Pants and Shorts" and a slug of "pants-and-shorts".

Slugs for Product Type, Option Type, and Option Value data models aren't overwritten

Since we've stated above that Shopify does not have a slug field for Product Type, Option Type, and Option Value data models, and that the slug is auto-generated, this also brings up the fact that Shopify will not override these slugs.

For example, if a product has a Product Type of "Pants" and a slug of "pants" and the Product Type is changed to "Shorts" in Shopify, the slug will not be affected. To change the slug, you must do this in the CMS itself.

Variant name is only set in CMS if not already set

Our data model includes a Variant Name field, but Shopify has no such field. Because of this, the sync service will populate the Variant Name field with a unique name only if the Variant doesn't already have a Name set in the CMS. This prevents custom Variant Names from being overwritten if you decide to create a custom name for it.

Create products as gift cards

Due to a Shopify limitation, a Gift Card product (GCP) can only be marked as such at product creation. In other words, you can only create a GCP from a CMS if you mark it as such (using the giftCard attribute) before publishing it for the first time.

Sanity

(Coming soon ➡️)

Chord OMS

(Coming soon ➡️)

Notifications

Slack

We allow you to provide a Slack webhook to get notified about successful or failed sync events produced by the Sync Service.

To do so, you will need to add an Incoming Webhooks app to your space and provide the Chord team with the generated URL.

In Depth

Change Detection Flow

Difference Detection Logic

Sync Product Schema

Here's the shape of the Sync Product we use to map changes in between the various integrations we support:

Product

Product

Type

Notes

status

string

The status of the product at origin.

name

string

The name of the product.

slug

string

The slug of the product.

vendor

string

The vendor name.

productType.name

string

The name of the product type.

productType.slug

string

The slug of the product type.

shortDescription

string

A short description of the product.

longDescription

string

A long description of the product.

mainImage

image

(see below)

images

image[]

(see below)

optionTypes

optionTypes

(see below)

tags

string[]

A list of tags.

variants

variant[]

(see below)

isGiftCard

boolean

true if the product is a gift card.

Variant

Variant

Type

Notes

name

string

The name of the variant.

sku

string

The unique SKU for the variant.

globalTradeItemNumber

string

The GTIN number.

shopifyId

string

The ID of the variant in Shopify. (to be deprecated)

price

string

The current price (can be lower than the regular price).

regularPrice

string

The regular price.

mainImage

image

(see below)

images

image[]

(see below)

optionValues

optionValue[]

(see below)

weight

string

A string representing the weight.

Image

Image

Type

Notes

alt

string

The alt string value.

fileType

string

The type of image (ex: image/jpeg )

fileName

string

The filename of the image.

url

string

The absolute URL of the image.

Option Type & Value

Option Type

Type

Notes

name

string

The name of the option type (ex: Color ).

slug

string

The slug of the option type.

presentation

string

The presentation string of the option type.

optionValues

optionValue[]

(see below)

Option Value

Type

Notes

name

string

The name of the option value (ex: Red ).

slug

string

The slug of the option value.

presentation

string

The presentation string of the option type.

Collection

(Considering 🎱)

Metafield

(Coming soon ➡️)

FAQ

Migration Guides

(Coming soon ➡️)

Troubleshoot

(Coming soon ➡️)

Roadmap

Status

Features

Done ✅



In Development 🏗️



Up Next ➡️

- Adding support for Product Metafields - Standardizing support for Chord OMS

- Adding support for Sanity

Considering 🎱

- Adding support for Collections sync - Adding admin dashboard to manage content syncs, edit configs, view historical data, etc.
Updated 10 Jan 2023
Did this page help you?
Yes
No
UP NEXT
Content Models
Docs powered by archbee 
TABLE OF CONTENTS
Overview
Terms
How does it work?
What is synced exactly?
Get Started
Environments
Configuration & Options
Notes
Supported Integrations
Contentful
Configuration & Options
Setup
Usage
Data Mapping
Notes
Shopify
Setup
Usage
Data Mapping
Notes
Sanity
Chord OMS
Notifications
Slack
In Depth
Change Detection Flow
Difference Detection Logic
Sync Product Schema
Product
Variant
Image
Option Type & Value
Collection
Metafield
FAQ
Migration Guides
Troubleshoot
Roadmap