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).

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.

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.

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:

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

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.

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).

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 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.

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:

(Considering 🎱)

(Coming soon ➡️)

(Coming soon ➡️)

(Coming soon ➡️)