Field mappings
Here are all the data mappings for the Engage - Shopify integration.
Contact data mapping
Engage | Source data (Shopify) | Notes |
Contact.externalId | Customer.id | |
Contact.contactType | "member" or "contact" | Only set on contact creation. according to "Customer contact type" setting |
Contact.firstName | Customer.firstName | |
Contact.lastName | Customer.lastName | |
Contact.email | Customer.email | |
Contact.mobilePhone | Customer.phone | |
Contact.createdInStore | Associated Store for Customer.locale | Based on market configuration in Engage App in Shopify |
Contact.street | Customer.defaultAddress.address1 , Customer.defaultAddress.address2 | |
Contact.city | Customer.defaultAddress.city | |
Contact.country | Customer.defaultAddress.country | |
Contact.countryCode | Customer.defaultAddress.countryCodeV2 | |
Contact.language | ||
Contact.externalId | Shopify internal Id | |
Contact.preferences.acceptsEmail | Customer.emailMarketingConsent.marketingState == SUBSCRIBED | Set on Contact creation and opt-in through an order |
Contact.preferences.acceptsSms | Customer.smsMarketingConsent.marketingState == SUBSCRIBED | Set on Contact creation and opt-in through an order |
Contact.preferences.acceptsPostal | false | Only set on Contact creation. |
Contact.consents[id="hasShopifyAccount"].value | Customer.state == ACTIVE | Set for all customers who have an account online |
Contact.consents[id="hasShopifyAccount"].source | "Shopify" |
Receipt data mapping
Engage | Source data (Shopify) - orders/create | Source data (Shopify) - refunds/create | Notes |
Receipt.contact.matchKey | Associated Contact Voyado Contact ID | ||
Receipt.contact.matchKeyType | "contactId" | ||
Receipt.uniqueReceiptId | Order.id | Refund.order.id | |
Receipt.receiptNumber | Order.number | Refund.order.number | |
Receipt.createdDate | Order.createdAt | Refund.createdAt | |
Receipt.storeExternalId | Associated Store External ID by Customer.locale retrieved from database | Based on market configuration in Engage App in Shopify | |
Receipt.currency | Order.currencyCode | Refund.order.currencyCode | |
Receipt.exchangeRateToGroupCurrency | The exchange rate between "voyado group currency" (see settings) and Order.currencyCode / Refund.order.currencyCode , retrieved from third party service (with 24-hours accuracy) | ||
Receipt.totalGrossPrice | Order.totalPriceSet.shopMoney.amount | Refund.totalRefundedSet.shopMoney.amount | |
Receipt.taxDetails | Order.taxLines | ||
Receipt.taxDetails[].description | Order.taxLines[].title | "Tax refund" | |
Receipt.taxDetails[].value | Order.taxLines[].priceSet.shopMoney.amount | sum(Refund.refundLineItems[].totalTaxSet.shopMoney.amount) | |
Receipt.paymentMethods[].type | Order.transactions[].gateway | Refund.transactions[].gateway | |
Receipt.paymentMethods[].description | Order.transactions[].paymentProvider.name | Refund.transactions[].paymentProvider.name | |
Receipt.paymentMethods[].value | Order.transactions[].amountSet.shopMoney.amount | Refund.transactions[].amountSet.shopMoney.amount | |
Receipt.items[] | Order.lineItems[] | Refund.refundLineItems[] | |
Receipt.items[].type | "PURCHASE" | "RETURN" | |
Receipt.items[].quantity | Order.lineItems[].quantity | Refund.refundLineItems[].quantity | |
Receipt.items[].grossPaidPrice | Order.lineItems[].discountedTotalSet.shopMoney.amount | Refund.refundLineItems[].priceSet.shopMoney.amount | |
Receipt.items[].taxAmount | Sum of Order.lineItems[].taxLines[*].priceSet.shopMoney.amount | Refund.refundLineItems[].totalTaxSet.shopMoney.amount | |
Receipt.items[].sku | Order.lineItems[].sku | Refund.refundLineItems[].lineItem.sku | |
Receipt.items[].articleNumber | Order.lineItems[].sku | Refund.refundLineItems[].lineItem.sku | |
Receipt.items[].discounts[].type | Derived from type of Order.lineItems[].discountAllocations[].discountApplication | See *A1 | |
Receipt.items[].discounts[].description | Derived from type of Order.lineItems[].discountAllocations[].discountApplication | See *A2 | |
Receipt.items[].discounts[].value | Order.lineItems[].discountAllocations[].allocatedAmountSet.shopMoney.amount |
*A1 - Discount type mapping
DiscountApplication type | Engage discount description |
AutomaticDiscountApplication | 235 |
DiscountCodeApplication | 235 |
ManualDiscountApplication | 235 |
ScriptDiscountApplication | 235 |
*A2 - Discount description mapping
DiscountApplication type | Engage discount description |
AutomaticDiscountApplication | "Automatic discount: ${AutomaticDiscountApplication.code}" |
DiscountCodeApplication | "Discount code: ${DiscountCodeApplication.code}" |
ManualDiscountApplication | "Manual discount: ${ManualDiscountApplication.description}" |
ScriptDiscountApplication | "Script discount: ${ScriptDiscountApplication.title}" |
Cart abandonment
Engage | Source |
[].CartReference | AbandonedCheckout.cart_id |
[].Time | AbandonedCheckout.updated_at |
[].ContactId | Identified contact ID |
[].Language | AbandonedCheckout.customer_locale |
[].Url | AbandonedCheckout.abandoned_checkout_url |
[].Items[].Sku | AbandonedCheckout.line_items[].sku |
[].Items[].Quantity | AbandonedCheckout.line_items[].quantity |
Engage order notification
Engage | Source (Shopify) - orders/* | Source (Shopify) - refunds/create | Notes |
contact.matchKey | Order.email or Order.phone (based on customer identification method, see settings.) | ||
contact.matchKeyType | "email" or "phone" (based on customer identification method) | ||
orderStatus | See *B3 | ||
paymentStatus | See *B4 | ||
orderNumber | Order.name | ||
createdDate | Order.createdAt | ||
shippingDate | Order.fulfillments[0]?.createdAt | ||
statusChangedDate | Order.updatedAt | ||
storeId | Associated store ID for Order.customerLocale (see store locale mapping.) | ||
currency | Order.currencyCode | ||
language | Order.customerLocale.split('-')[0] | ||
totalGrossPrice | Order.totalPriceSet.shopMoney.amount | ||
freightFee.value | Order.shippingLine.discountedPriceSet.shopMoney.amount | ||
freightFee.tax | sum(Order.shippingLine.taxLines[].priceSet.shopMoney.amount | ||
totalTax | Order.totalTaxSet.shopMoney.amount | ||
taxDetails[].description | Order.taxLines[].title | ||
taxDetails[].value | Order.taxLines[].priceSet.shopMoney.amount | ||
extraData.CreatedDate | Order.createdAt | ||
extraData.ShippingDate | Order.fulfillments[0]?.createdAt | ||
extraData.ReturnDate | Order.refunds[0]?.createdAt | ||
extraData.TrackingNumber | Order.fulfillments?[0].trackingInfo.number | ||
extraData.TrackingLinkHTML | Order.fulfillments?[0].trackingInfo.url | ||
extraData.ShippingMethod | Order.shippingLine.code | ||
extraData.ShippingAddressFirstName | Order.shippingAddress.firstName | ||
extraData.ShippingAddressLastName | Order.shippingAddress.lastName | ||
extraData.ShippingAddressStreet | Order.shippingAddress.address1 + Order.shippingAddress.address2 | ||
extraData.ShippingAddressZipCode | Order.shippingAddress.zip | ||
extraData.ShippingAddressCity | Order.shippingAddress.city | ||
extraData.ShippingAddressCountry | Order.shippingAddress.countryCodeV2 | ||
extraData.ShippingAddressPhone | Order.shippingAddress.phone | ||
extraData.ShippingAddressEmail | Order.email | ||
extraData.PaymentMethod | Order.paymentGatewayNames.join(',') | ||
extraData.BillingAddressFirstName | Order.billingAddress.firstName | ||
extraData.BillingAddressLastName | Order.billingAddress.lastName | ||
extraData.BillingAddressStreet | Order.billingAddress.address1 + Order.billingAddress.address2 | ||
extraData.BillingAddressZipCode | Order.billingAddress.zip | ||
extraData.BillingAddressCity | Order.billingAddress.city | ||
extraData.BillingAddressCountry | Order.billingAddress.countryCodeV2 | ||
extraData.BillingAddressPhone | Order.billingAddress.phone | ||
extraData.BillingAddressEmail | Order.email | ||
items[] | Order.lineItems[LineItem.refundableQuantity > 0] | Order.refunds[].refundLineItems[] | |
items[].type | "purchase" | "return" | |
items[].sku | Order.lineItems[].sku | Order.refunds[].refundLineItems[].sku | |
items[].quantity | Order.lineItems[].refundableQuantity | Order.refunds[].refundLineItems[].quantity | |
items[].grossPaidPrice | Order.lineItems[].discountedTotalPriceSet.shopMoney.amount | Order.refunds[].refundLineItems[].priceSet.shopMoney.amount | |
items[].taxAmount | sum(Order.lineItems[].taxLines[].priceSet.shopMoney.amount) | Order.refunds[].refundLineItems[].totalTaxAmount.shopMoney.amount | |
items[].description | Order.lineItems[].name | ||
items[].imageUrl | Order.lineItems[].image.src | ||
items[].discounts[].type | Order.lineItems[].discountAllocations[].discountApplication | See *B1 | |
items[].discounts[].description | Order.lineItems[].discountAllocations[].discountApplication | See *B2 | |
items[].discounts[].value | Order.lineItems[].discountAllocations[].allocatedAmountSet.shopMoney.amount |
*B1 - Discount type mapping
DiscountApplication type | Engage discount type |
AutomaticDiscountApplication | 235 |
DiscountCodeApplication | 235 |
ManualDiscountApplication | 235 |
ScriptDiscountApplication | 235 |
*B2 - Discount description mapping
DiscountApplication type | Engage discount description |
AutomaticDiscountApplication | "Automatic discount: ${AutomaticDiscountApplication.code}" |
DiscountCodeApplication | "Discount code: ${DiscountCodeApplication.code}" |
ManualDiscountApplication | "Manual discount: ${ManualDiscountApplication.description}" |
ScriptDiscountApplication | "Script discount: ${ScriptDiscountApplication.title}" |
*B3 - Order status mapping
Condition | Value |
Order.refunds | "REFUNDED" |
Order.fulfillments | "FULFILLED" |
Order.partialFulfillments | "PARTIALLY_FULFILLED" |
Order.cancellations | "CANCELLED" |
Otherwise | "CONFIRMED" |
*B4 - Order payment status mapping
Condition | Value |
Order.fullyPaid | "PAID" |
Order.unpaid | "UNPAID" |
Otherwise | "PARTIALLY_PAID" |