Data Synchronisation between Spaaza and Shopify
Contents
- Overview
- Customer data
- Address data
- Order and transaction data
- Voucher and discount code data
- Customer metafields and tags
- Shopify webhooks
Overview
When a Shopify store is connected to Spaaza, data is synchronised between the two platforms to keep customer profiles, transactions, and loyalty rewards in sync. This page describes the data that is exchanged, the direction of synchronisation, and how Spaaza and Shopify field names map to each other.
Data synchronisation happens automatically through Shopify webhooks (Shopify to Spaaza) and through the Shopify Admin API (Spaaza to Shopify). No manual intervention is required once the Spaaza Shopify app is installed and configured.
For more information about the Shopify APIs, see the Shopify developer documentation.
For information about address format differences between the two platforms, see Differences between address format data in Spaaza and Shopify.
Customer data
Customer data is synchronised bi-directionally between Spaaza and Shopify. When a customer is created or updated in Shopify, the corresponding Spaaza user is created or updated. When a customer profile is updated in Spaaza, the changes are pushed to Shopify.
For a full list of Spaaza user fields, see the add-user and alter-user endpoint documentation. For Shopify customer fields, see the Shopify Customer object documentation.
Shopify to Spaaza
When a customer is created or updated in Shopify, the following fields are synchronised to Spaaza:
| Shopify Customer Field | Spaaza User Field | Notes |
|---|---|---|
id | authentication_point_identifier | The Shopify Customer ID, used to link the customer across both platforms |
email | username | The customer's email address, used as the primary identifier in Spaaza |
firstName | first_name | |
lastName | last_name | |
locale | language | The customer's preferred language |
verifiedEmail | registered | Whether the customer has verified their email address in Shopify |
emailMarketingConsent.marketingState | mailing_list_subscribed | SUBSCRIBED maps to true; any other value maps to false |
note | birthday | Only applicable when the store is configured to store birthday in the Shopify customer note field (format: Birthday: YYYY-MM-DD) |
Phone number synchronisation between Shopify and Spaaza is currently disabled. Shopify requires phone numbers to be in E.164 format and enforces uniqueness per store, meaning no two customers in the same store can share the same phone number. Spaaza does not enforce these constraints on the phone_number field, so synchronisation is paused to avoid validation conflicts.
When a customer is deleted in Shopify, all identifiable details for the corresponding Spaaza user are removed (obfuscated).
Spaaza to Shopify
When a customer profile is updated in Spaaza (for example via the alter-user endpoint), the following fields are pushed to Shopify:
| Spaaza User Field | Shopify Customer Field | Notes |
|---|---|---|
first_name | firstName | |
last_name | lastName | |
username | email | Empty email values are not sent to Shopify to prevent disabling the customer account |
mailing_list_subscribed | emailMarketingConsent.marketingState | true maps to SUBSCRIBED; false maps to UNSUBSCRIBED |
language | locale | The customer's preferred language |
birthday | note | Only applicable when the store is configured to store birthday in the Shopify customer note field (format: Birthday: YYYY-MM-DD) |
Address data
Address data is synchronised bi-directionally between Spaaza and Shopify. A Shopify customer can have multiple addresses, but Spaaza only synchronises the customer's default address. Other addresses stored in Shopify are not read or modified by Spaaza.
Because Spaaza and Shopify use different address structures, there are two synchronisation modes. The mode used depends on a per-chain configuration setting. For more information on the differences between address formats, see Differences between address format data in Spaaza and Shopify.
Shopify to Spaaza
Simplified mode (when the chain is configured to use address_line_2 for Shopify addresses):
| Shopify Address Field | Spaaza User Field | Notes |
|---|---|---|
defaultAddress.address1 | address_line_2 | Full street address in a single field |
defaultAddress.city | address_towncity | |
defaultAddress.countryCode | country_code | |
defaultAddress.provinceCode | address_regionstate | |
defaultAddress.zip | address_postalcode |
Granular mode (default):
| Shopify Address Field | Spaaza User Field | Notes |
|---|---|---|
defaultAddress.address1 | address_streetname | |
defaultAddress.address2 | address_housenumber_extension | |
defaultAddress.city | address_towncity | |
defaultAddress.countryCode | country_code | |
defaultAddress.provinceCode | address_regionstate | |
defaultAddress.zip | address_postalcode |
Spaaza to Shopify
When address fields are updated in Spaaza, they are pushed to the Shopify customer's default address:
| Spaaza User Field | Shopify Address Field | Notes |
|---|---|---|
address_streetname or address_line_2 | address1 | Depends on the chain's address mode configuration |
address_housenumber_extension | address2 | Only in granular mode |
address_towncity | city | |
country_code | countryCode | |
address_regionstate | provinceCode | |
address_postalcode | zip |
Order and transaction data
Order data flows one way, from Shopify to Spaaza. When an order is paid in Shopify, it is recorded as a basket in Spaaza. In the Spaaza data model, a basket represents a customer transaction (also referred to as a receipt, cart, or order). For full details on basket fields, see the add-basket endpoint documentation. For Shopify order fields, see the Shopify Order object documentation. Spaaza does not create or modify orders in Shopify.
Order data
| Shopify Order Field | Spaaza Basket Field | Notes |
|---|---|---|
customer.id | user.authentication_point_identifier | Links the order to a Spaaza user |
name | retailer_basket_code | The Shopify order name (e.g. #1001) |
id | supplementary_basket_codes[] | The Shopify order ID |
updated_at | basket_timestamp | |
currency | basket_currency | |
subtotal_price | basket_total_price | |
note | basket_notes | |
total_shipping_price_set.shop_money.amount | shipping_charge | |
tax_lines[].rate | basket_tax[].tax_rate | |
tax_lines[].price | basket_tax[].tax_total | |
discount_codes[].code | basket_vouchers[].shopify_discount_code | Links Shopify discount codes to Spaaza vouchers |
Order line item data
| Shopify Line Item Field | Spaaza Basket Item Field | Notes |
|---|---|---|
line_items[].product_id | retailer_product_code | |
line_items[].variant_id | item_barcode | Default item identifier; can be configured per chain to use sku instead |
line_items[].sku | item_barcode | Used instead of variant_id when the chain is configured to use SKU as the item identifier |
line_items[].title | item_name | |
line_items[].price | item_price | |
line_items[].quantity | item_quantity | |
line_items[].vendor | item_brand | |
line_items[].variant_title | item_colour |
Refund data
When a refund is created in Shopify, it is recorded as a return transaction in Spaaza. The refund line items are mapped using the same field mappings as order line items, with item prices negated to represent the return.
| Shopify Refund Field | Spaaza Basket Field | Notes |
|---|---|---|
id | external_system_refund_id | The Shopify refund ID |
refund_line_items[].line_item.product_id | retailer_product_code | |
refund_line_items[].line_item.variant_id or sku | item_barcode | Same configuration as orders |
refund_line_items[].line_item.title | item_name | |
refund_line_items[].line_item.price | item_price | Negated for returns |
refund_line_items[].line_item.quantity | item_quantity | |
refund_line_items[].line_item.vendor | item_brand | |
refund_line_items[].line_item.variant_title | item_colour |
Voucher and discount code data
When a Spaaza campaign issues a voucher to a customer, Spaaza creates a corresponding discount code in Shopify so that the customer can redeem it at checkout. This synchronisation flows one way, from Spaaza to Shopify.
Discount code creation
Spaaza creates customer-specific, single-use discount codes in Shopify. The type of discount code created depends on the voucher type:
| Voucher Type | Shopify Discount Type | Description |
|---|---|---|
| Monetary (basket) | Basic or App discount code | A fixed-amount discount; App discount codes are used when a Shopify discount function is configured |
| Percentage | Basic discount code | A percentage-based discount |
All discount codes created by Spaaza:
- Are restricted to a single customer
- Have a usage limit of 1
- Have an expiry date based on the campaign's voucher expiry configuration
- Can optionally be restricted to specific Shopify collections (see Discount Code Collection Restrictions)
Discount code lifecycle
- Creation: When a voucher is issued by a campaign, a discount code is created in Shopify and the code is stored on the Spaaza voucher record.
- Redemption: When a Shopify order is received that includes the discount code, Spaaza matches it to the corresponding voucher and marks the voucher as redeemed. The discount code is then deleted from Shopify.
- Deletion/Expiry: If a voucher is deleted or expires in Spaaza, the corresponding discount code is also deleted from Shopify.
Customer metafields and tags
Spaaza writes certain metafields and tags to Shopify customers to support the integration. These flow one way, from Spaaza to Shopify.
Metafields
| Namespace | Key | Type | Description |
|---|---|---|---|
customer | user_hash | string | A hash value used for Shopify user authentication |
spaaza | spaaza_opted_in | boolean | Whether the customer is opted in to the loyalty programme |
Tags
| Tag Format | Description |
|---|---|
spaaza_loyalty_status:{level_name} | The customer's current loyalty level name in Spaaza; updated when the loyalty level changes |
Shopify webhooks
Spaaza subscribes to the following Shopify webhooks to receive real-time updates. These webhooks are registered automatically when the Spaaza Shopify app is installed.
| Webhook Topic | Purpose |
|---|---|
customers/create | Create a new user in Spaaza when a customer is created in Shopify |
customers/update | Update the Spaaza user when customer details change in Shopify |
customers/delete | Remove identifiable details from the Spaaza user |
customers/disable | Acknowledge disabled Shopify customers (no data changes in Spaaza) |
customers/enable | Acknowledge re-enabled Shopify customers (no data changes in Spaaza) |
orders/create | Acknowledge new orders (basket is not created until order is paid) |
orders/paid | Record the transaction as a basket in Spaaza |
orders/updated | Acknowledge order updates |
orders/cancelled | Acknowledge order cancellations |
refunds/create | Record the refund as a return transaction in Spaaza |