Before you start
Things you need to know:
Only the default name and description for each product are imported as part of the synchronisation. Translations or language variants are not included.
The very top-level product in Centra is not synchronised to Dotdigital. This is because it is not available to customers in the store and has no URL, image, or price that can be used within the Dotdigital platform.
1. Create a Centra API token
To create a token in Centra:
In Centra, go to System > API Tokens.
Select + Create integration API token.
Under General, enter the following token details:
Description:
Name of the integration platform.Organization Name:
Name of the organisation using the integration.Email:
The email address of the organisation.Phone:
The contact phone number of the organisation.Integration Name:
The name of the integration.Expires:
When the integration expires.
Under Restrictions, choose any Restrictions for the token.
You can restrict:
The store types it can connect to.
The stores you are connecting to. This should only be the specific store you are connecting to your Dotdigital account.
Set the following permissions for the token.
Read permissions:
Brand
Category
Customer
Display
Market
NewsletterSubscription
Order
Price
Pricelist
Product
ProductMedia
ProductSize
ProductVariant
Shipment
Store
StorePlugin
2. Set up the Centra integration in Dotdigital
To set up the integration in Dotdigital:
In Dotdigital, go to Connect > Integrations.
Find the Centra integration, then select + ADD.
Select Install.
Read about the integration, then select Next.
For Authentication, enter your Centra Store URL, and your Centra API token. Then select NEXT.
If you haven’t already done this, learn how.For Centra store, expand the Store drop-down menu, then choose the store you want to connect to Dotdigital. Then select NEXT.
For Centra pricelist, expand the Pricelist drop-down menu, then choose the pricelist you want to connect to Dotdigital. Then select NEXT.
For Product URL, enter your product page URL. Then select NEXT.
The product URL is a placeholder URL for products that is dynamically replaced with the correct value. For example, https://example.com/products/{display_url}.
You must include the {display_url} part of the URL.For Sync settings, choose the data you want synchronised from Centra to your Dotdigital account:
Customers
Newsletter subscribers
Orders
Products
Select FINISH.
What the integration does
Contact Sync
All customers with a valid email address are synced into a target ‘Customer’ list in Dotdigital.
Any customers that have opted into the main newsletter subscription in Centra are synced to a target ‘Subscriber’ list in Dotdigital.
Customers are defined as those who have an account in Centra and may be opted in or not opted in for the main newsletter subscription.
Lists follow the below naming conventions:
Dotdigital List Name | Contacts (must have email subscribed in Dotdigital) |
Centra – Customers (Store.name) | All customers within Centra |
Centra – Subscribers (Store.name) | Any customers within Centra that have opted in to the newsletter preference (as defined above) |
Defining Subscribers
A customer’s main newsletter subscription within Centra is mapped to Dotdigital, representing consent for them to be sent marketing emails.
The integration checks the Centra newsletter subscription object to confirm if the isActive field is set to True or False. If set to True, the customer is imported into the Subscribers list in Dotdigital.
If set to False (for example, a user opts out of the newsletter) they are removed from the Subscribers list and the CENTRA_NEWSLETTER data field is updated to indicate their status.
Data field mapping
Centra contact data field | Dotdigital contact data field |
customer.email | |
customer.firstName | Firstname |
customer.lastName | Lastname |
customer.gender | Gender |
customer.billingAddress.address 1 | Billing_Address_1 |
customer.billingAddress.address 2 | Billing_Address_2 |
customer.billingAddress.city | Billing_City |
customer.billingAddress. stateOrProvince | Billing_State |
customer.billingAddress.zipCode | Billing_Postcode |
customer.billingAddress.country | Billing_Country |
customer.birthdate | DOB |
customer.store.name | Store_Name |
customer.language.name | Language_Name |
customer.language.code | Language_Code |
customer.market.name | Market |
customer.websiteUrl | Website_URL |
customer.totalOrders | Total_Orders |
customer.newsletterSubscriptions[productVariant=null].isActive | Centra_Newsletter |
The name of the market that each customer belongs to is synched to the ‘MARKET’ contact data field in Dotdigital. Customers can only ever be associated with a single market in Centra, and email address values are unique to each customer (so a customer in one market cannot use the same email as a customer in another market).
Order Sync
Any Orders placed by your customers in Centra are automatically synced to Dotdigital's ‘orders’ Insight collection.
The order must include a billing address email. This is used as the contact identifier when you import to the 'Orders' Insight collection.
Order data attributes are listed below:
Centra order fields | Dotdigital insight data field |
id | id, key |
number | number |
grandTotal.value | order_total |
totals.shipping.value | delivery_total |
totals.handling.value | handling_total |
totals.discounts.value (absolute value) | discount_amount |
totals.lineValues.value | order_subtotal |
orderDate | purchase_date |
status | order_status |
grandTotal.currency.code | currency |
paymentMethod.name | payment |
Shipments[0].carrierInformation | delivery_method |
billingAddress.email | email, contactIdentity.value (contactIdentity.identity=email) |
billingAddress.address1 | billing_address.billing_address_1 |
billingAddress.address2 | billing_address.billing_address_2 |
billingAddress.city | billing_address.billing_city |
billingAddress.country.name | billing_address.billing_country |
billingAddress.zipCode | billing_address.billing_postcode |
shippingAddress.address1 | delivery_address.delivery_address_1 |
shippingAddress.address2 | delivery_address.delivery_address_2 |
shippingAddress.city | delivery_address.delivery_city |
shippingAddress.country.name | delivery_address.delivery_country |
shippingAddress.zipCode | delivery_address.delivery_postcode |
lines.productSize.SKU | product.sku |
lines.productName | product.name |
lines.productVariantName | product.variantName |
lines.productSize.description | product.size |
lines.unitPrice.value | product.price |
lines.quantity | product.qty |
lines.productNumber | product.parent_id |
lines.productBrand | brand |
market.name | market_name |
market.id | market_id |
pricelist.name | pricelist_name |
pricelist.id | pricelist_id |
Product SKU
The product SKU value for the product in each line item in the order data uses the SKU value at the ‘product size’ level of each Centra order line. This value combines the Centra product number, variant number, and size number (all string values, not numeric).
If there are any null values for certain properties in Centra, it will be reflected in the SKU values that are synced to Dotdigital. This can cause issues with the functionality of the Dotdigital platform. It's important to ensure that the number values for these properties are unique within Centra to avoid creating duplicate SKUs, which can also affect the functionality of the Dotdigital platform. Additionally, the same SKU property is used in the Centra product and display data that is synchronized to Dotdigital product catalogs. If the SKUs are not reliable, it may be necessary to switch back to using frontendItemId instead.
Product name
The 'productName' field, represented by 'lines.productName', refers to the name of the product as displayed to the customer in the web store's user interface. It is important to note that this field does not represent the top-level product details. When mapping and syncing product names in Dotdigital, it is essential to keep this distinction in mind. Additionally, the specific product variant name and size description are also mapped to enhance personalization and segmentation.
Orders
Orders from the selected Centra store are imported to Dotdigital, with the market name and ID stored in corresponding fields.
Product sync
Products
In Centra, what customers see in the store front-end and can purchase as a product is called a Display. A Display can have multiple variants of the top-level product.
Each product variant added to a Display is referred to as a Display item. Since these Display items are what customers see and buy, and what is captured in the order data from Centra, we use Display items as product variants in the Dotdigital product catalog, with the Display serving as the parent product that can be configured.
Catalogs
The products, which include displays and display items, from Centra are synchronized into a Dotdigital account Insight collection called catalog_{store.name}_{market.name} for each market within the connected Centra store. The name of the store being synchronized is represented by {store.name}, and the name of the market being synchronized is represented by {market.name}, with spaces replaced by underscores.
Each product within the catalog_{store.name}_{market.name} account Insight collection will have an attributes object that contains a presentment_prices array. This array stores an array of prices for the product as defined in each store pricelist. Additionally, it includes the primary pricelist price, defined by the user during setup and used for the main 'price' and 'currency' fields in Dotdigital.
Pricing
The following rules are applied during the data mapping process:
If the Centra product variant price (for the pricelist defined as the primary pricelist during setup) is available for each product variant in Dotdigital, it will be used. If not, the price assigned to the display is used.
All Dotdigital products use the primary pricelist currency code as their currency value.
For Centra displays, the first image returned by the API will be used as the configurable product image. If no image exists for the display, then no image is stored for the product in Dotdigital.
For Centra display items, the first product variant image returned by the API will be used as the variant product image. If no image exists for the product variant, the first image associated with the product display will be used. If no image exists for the display, no image will be stored for the product in Dotdigital.
If a Centra display does not have a URI value available, then only the top-level store URL (as defined during setup) is used for the product link.
If a Centra display item has no associated prices, the display prices will be used for the presentment_prices array.
Product Attributes
The mapping for Centra Display fields to Dotdigital Product Insight fields for configurable products is provided below:
Centra Display Field | Dotdigital Insight Field |
id | id, key |
null | parent_id |
name | name |
null | variantName |
description | description |
null | size |
prices[0].price.value | price |
config.store[0].pricelist[0].currency.code (Defined during set-up) | currency |
{store_product_page_url} + uri | url |
id | sku |
media[0].source.url (where media.source.type = ‘IMAGE’) | image_path |
status | status |
“Configurable” (Static value) | type |
product.brand.name | brand |
{store_product_page_url} + product.brand.uri | brand_url |
markets.name (Will vary based on current market being synched) | market_name |
markets.id (Will vary based on current market being synched) | market_id |
categories | categories |
categories.id | categories.id |
prices | attributes.presentment_prices |
prices.price.value | presentment_prices.price.amount |
prices.price.currency.code | presentment_prices.price.currency_code |
prices.pricelist.name | presentment_prices.price.pricelist_name |
prices.pricelist.id | presentment_prices.price.pricelist_id |
N/A (Time of synch in UTC) | updatedAt |
The mapping for Centra Display fields to Dotdigital Product Insight fields for variant products is provided below:
Centra Display Field | Dotdigital Insight Field |
{displayItem.id} + ‘-‘ + {displayItem.productVariant.productSize.id} | id, key |
id | parent_id |
name | name |
displayItem.productVariant.name | variantName |
description | description |
displayItem.productVariant.productSize.description | size |
displayItem.productVariant.prices[0].price.value (or fallback is same as configurable product price) | price |
config.store[0].pricelist[0].currency.code (Defined during set-up) | currency |
{store_product_page_url} + uri | url |
displayItem.productVariant.productSize.SKU | sku |
displayItem.productVariant.media[0].source.url (where media.source.type = ‘IMAGE’) or media[0].source.url (where media.source.type = ‘IMAGE’) | image_path |
displayItem.productVariant.status | status |
“Variant” (Static value) | type |
product.brand.name | brand |
{store_product_page_url} + product.brand.uri | brand_url |
markets.name (Will vary based on current market being synched) | market_name |
markets.id (Will vary based on current market being synched) | market_id |
categories | categories |
categories.id | categories.id |
productVariant.prices | presentment_prices |
productVariant.prices.price.value | presentment_prices.amount |
productVariant.prices.price.currency.code | presentment_prices.currency_code |
productVariant.prices.pricelist.name | presentment_prices.pricelist_name |
productVariant.prices.pricelist.id | presentment_prices.pricelist_id |
N/A (Time of synch in UTC) | updatedAt |
Product SKU for variants
The product SKU value for the product variants in each line item in the order data uses the SKU value at the ‘product size’ level of each Centra order line. This value combines the Centra product number, variant number, and size number (all string values, not numeric).
If certain properties in Centra have null values, this will be reflected in the SKU values that are synced to Dotdigital. This can cause issues with the Dotdigital platform's functionality. It's important to ensure that the number values for these properties are unique within Centra to avoid creating duplicate SKUs, which can also affect the Dotdigital platform's functionality.
Site tracking
To use Dotdigital features, such as Webinsights, Abandoned Cart, and Abandoned Browse, you must install the Dotdigital site tracking scripts on your Centra store front-end by the site administrator.
Learn how to install these scripts with the following articles: