Synchronize resources between commercetools Projects using the project-sync CLI tool.
Use cases
Project sync is suitable for the following use cases:
- Migrating data from a staging Project to a production Project.
- Keeping a secondary Project up to date with additions and updates from a primary Project.
- Copying data into a new Project for local development or testing.
Project sync only creates and updates supported resources in the target Project. It doesn't delete resources in the target Project when they're removed from the source Project, so the two Projects can diverge over time. Project sync isn't a full backup or disaster-recovery solution.
Supported resources
-s option to select which resources to sync:| Resource | -s value |
|---|---|
| Cart Discounts | cartDiscounts |
| Categories | categories |
| Custom Objects | customObjects |
| Customers | customers |
| Inventory | inventoryEntries |
| Products | products |
| Product Types | productTypes |
| Shopping Lists | shoppingLists |
| States | states |
| Tax Categories | taxCategories |
| Types | types |
By default, project sync runs a delta sync, meaning it only synchronizes resources that changed since the last run. It tracks the last sync timestamp using a Custom Object in the target Project.
The first time you sync a given resource, no last sync timestamp exists yet. That run synchronizes the entire selected data set instead, the same as a full sync, so expect it to take longer than later runs.
--full option to sync the entire data set at any time.Get started
Prerequisites
Before running project sync, complete the following steps:
- Install Docker to run the project-sync Docker image.
- Create an API Client for both the source and target Project.
- Make sure the required identifier fields are set on each resource and subresource you intend to sync.
API Client scopes
manage_project:{projectKey} scope for both API Clients, or narrow the scopes down to only the resources you intend to sync, as shown in the following table. When narrowing scopes, always include one of the Custom Objects scopes for the target Project, because project sync stores its sync timestamps there. For more information about scopes, see Scopes.| Resource | Scope |
|---|---|
| Cart Discounts | manage_cart_discounts:{projectKey} |
| Categories | manage_categories:{projectKey} |
| Custom Objects | manage_products:{projectKey}, manage_orders:{projectKey}, manage_customers:{projectKey}, or manage_key_value_documents:{projectKey} |
| Customers | manage_customers:{projectKey} |
| Inventory | manage_products:{projectKey} |
| Products | manage_products:{projectKey} |
| Product Types | manage_products:{projectKey} |
| Shopping Lists | manage_shopping_lists:{projectKey} |
| States | manage_states:{projectKey} |
| Tax Categories | manage_tax_categories:{projectKey} |
| Types | manage_types:{projectKey} |
Required identifier fields
The following resources and subresources must have these identifier fields set before you sync them:
| Resource | Required fields |
|---|---|
| Product | key |
| Product Variant | key and sku |
| Product Variant Asset | key |
| Product Type | key |
| Type | key |
| Category | key |
| Category Asset | key |
| Cart Discount | key |
| Inventory Entry | sku |
| State | key |
| Tax Category | key |
| Custom Object | container and key |
| Customer | key |
| Customer Address | key |
| Shopping List | key |
| Shopping List Line Item (Product Variant) | sku |
| Shopping List Text Line Item | name |
Set environment variables
SOURCE_PROJECT_KEY and TARGET_PROJECT_KEY values before running project sync. Project sync creates and updates resources in the target Project to match the source Project, so running it with the wrong Project keys can overwrite existing data in that Project.Set the following environment variables with the credentials and URLs of your source and target Projects:
export SOURCE_PROJECT_KEY="source-project-key"
export SOURCE_CLIENT_ID="sourceClientId"
export SOURCE_CLIENT_SECRET="sourceClientSecret"
export SOURCE_AUTH_URL="https://auth.eu-central-1.aws.commercetools.com/oauth/token"
export SOURCE_API_URL="https://api.eu-central-1.aws.commercetools.com"
export SOURCE_SCOPES="manage_project:source-project-key"
export TARGET_PROJECT_KEY="target-project-key"
export TARGET_CLIENT_ID="targetClientId"
export TARGET_CLIENT_SECRET="targetClientSecret"
export TARGET_AUTH_URL="https://auth.eu-central-1.aws.commercetools.com/oauth/token"
export TARGET_API_URL="https://api.eu-central-1.aws.commercetools.com"
export TARGET_SCOPES="manage_project:target-project-key"
Run the Docker image
5.9.1 with the latest available version:docker pull commercetools/commercetools-project-sync:5.9.1
-s option to choose which resources to sync. For example, to sync all supported resources:docker run \
-e SOURCE_PROJECT_KEY \
-e SOURCE_CLIENT_ID \
-e SOURCE_CLIENT_SECRET \
-e SOURCE_AUTH_URL \
-e SOURCE_API_URL \
-e SOURCE_SCOPES \
-e TARGET_PROJECT_KEY \
-e TARGET_CLIENT_ID \
-e TARGET_CLIENT_SECRET \
-e TARGET_AUTH_URL \
-e TARGET_API_URL \
-e TARGET_SCOPES \
commercetools/commercetools-project-sync:5.9.1 -s all
-s option. For example, the following command syncs only Types and Product Types:docker run \
-e SOURCE_PROJECT_KEY \
-e SOURCE_CLIENT_ID \
-e SOURCE_CLIENT_SECRET \
-e SOURCE_AUTH_URL \
-e SOURCE_API_URL \
-e SOURCE_SCOPES \
-e TARGET_PROJECT_KEY \
-e TARGET_CLIENT_ID \
-e TARGET_CLIENT_SECRET \
-e TARGET_AUTH_URL \
-e TARGET_API_URL \
-e TARGET_SCOPES \
commercetools/commercetools-project-sync:5.9.1 -s types productTypes
After the sync completes, the application prints a summary report for each synced resource, including how many resources were created, updated, or failed to sync.