OMS / CMS Sync
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.
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.
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.
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.
Configurations are currently only editable by the Chord team. Please reach out if you need to make any changes.
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.
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. |
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.
Available as an Origin and a Destination.
| Default | Description |
Space ID | | Your Contentful space ID. |
Environment ID | master | Your Contentful environment ID. |
Management Token | false | Your Contentful management token. |
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:
- 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
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.
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 | |
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).
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. |
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.
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.
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 | |
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.
(Coming soon ➡️)
(Coming soon ➡️)
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.
Here's the shape of the Sync Product we use to map changes in between the various integrations we support:
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 | 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 | 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 | 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. |
(Considering 🎱)
(Coming soon ➡️)
(Coming soon ➡️)
(Coming soon ➡️)
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. |