Overview

SalesPad 5.6.0 introduces significant updates to the Shopify integration which requires existing users to reconfigure settings for this connector when upgrading.  These changes are necessary as Shopify is ending support for their previous REST API and replacing it with a new GraphQL API which SalesPad 5.6.0 now supports.  The general features and functionality for the Shopify connector are still available, but some fields have been removed and some features have been adjusted to align with Shopify’s updates.

Affected Settings

The Shopify integration has a Settings tab which controls the integration processing.  Most of these mapping, matching, and script settings had required updates to work with Shopify’s GraphQL API.  Some of the settings were changed substantially and will require reconfiguring, while others had smaller changes and may not need to be adjusted.

Inventory Level Export - Matching

Inventory Level Export Location Matching

This setting now works very differently. As a result, its value was reset and must be reconfigured.

Previously, this setting worked like the Inventory Item Matching setting - it allowed users to define rules for how Shopify locations match to GP locations (aka warehouses and sites). Now, the setting is simpler and allows users to directly map GP locations to Shopify locations. To enter a mapping, click the Add button to add a new row, select a GP location, and then select its corresponding Shopify location.

A single GP location should generally only match to a single Shopify location and vice-versa. However, it is possible to match a GP location to multiple Shopify locations. Note that the Inventory Level Export does not have any special handling around this use case and will simply export the GP location’s available item quantities to every matched Shopify location.

Order Import

Financial Status Filter

This setting has a variety of smaller tweaks which will not affect most users. It is generally recommended to leave this setting’s value as ‘Paid’.

This setting’s value can now be empty. If the setting’s value is empty, the Order Import will not filter orders by their financial status.

‘Unpaid’ is no longer an option because it does not correspond to a Shopify financial status. If ‘Unpaid’ was selected for this setting, it will need to be manually removed.

‘Any’ is no longer an option because it has been replaced by leaving the setting blank. If ‘Any’ is still in the setting’s value, the Order Import will still not filter orders by their financial status, just like if the setting is blank.

‘Expired’ is now an option for this setting.

Fulfillment Status Filter

This setting has a variety of smaller tweaks which will not affect most users. It is generally recommended to leave this setting’s value as ‘Unfulfilled’.

This setting’s value can now be empty. If the setting’s value is empty, the Order Import will not filter orders by their fulfillment status. Likewise, while ‘Any’ is no longer an available option in the dropdown, the Order Import will not filter orders if this setting’s value is set to ‘Any’.

‘Partially fulfilled or unfulfilled’ is no longer an option. Please select ‘Partially fulfilled’ and ‘Unfulfilled’ instead.

This setting has new options: In progress, On hold, Open, Pending fulfillment, Request declined, Restocked, and Scheduled.

Users can now select multiple fulfillment statuses. Orders which have any of the selected fulfillment statuses will import. 

Load Order Payment Terms

This new setting controls whether Shopify orders will have a value for their Payment Terms column. This setting defaults to ‘False’, which means that Payment Terms will not load by default. Payment Terms are only needed if the Sales Document Assignment Mapping setting or a similar setting intends to map Payment Terms to a SalesPad field.

This setting can be set to ‘True’, but if it is set to ‘True’, the Order Import will require the ‘read_payment_terms’ access scope. To enable this access scope, follow these steps:

1. Navigate to the admin version of your Shopify store.

2. Go to Settings.

3. Select ‘Apps and sales channels’ and click ‘Develop apps’.

4. Select your SalesPad connector app.

5. Go to Configuration and click Edit.

6. Enable the ‘read_payment_terms’ access scope and click Save.

Number Of Orders To Import Per Page

This setting’s default value is now 25 and its maximum value is now 50. Previously, its default value was 50 and its maximum value was 100. If the setting’s value is above the maximum, the Order Import will use 50 as the page size. While 50 is an acceptable value for this setting, consider reducing it to 25 if the Order Import encounters errors around loading orders from Shopify.

Payment Financial Status Filter

This setting has a variety of smaller tweaks which will not affect most users. It is generally recommended to leave this setting’s value as ‘Paid’.

Previously, the Order Import would always create exactly one GP payment as long as the order’s financial status matched a status selected in this setting. This was the case regardless of whether the order had any transactions at all, which types of transactions they were, and whether the order had multiple transactions.

Now, the Order Import will create one payment for each sale transaction and each capture transaction on the Shopify order. This means that the Order Import will no longer create payments for orders which have no transactions or which only have an authorization transaction. This also means that the Order Import can now create multiple payments for the same sales document.

This setting’s value can now be empty. If the setting’s value is empty, the Order Import will always try to import payments for an order regardless of the order’s financial status.

‘Unpaid’ is no longer an option because it does not correspond to a Shopify financial status. If ‘Unpaid’ was selected for this setting, it will need to be manually removed.

‘Any’ is no longer an option. If ‘Any’ is still in the setting’s value, the Order Import will treat this setting as if it has an empty value.

‘Expired’ is now an option for this setting for the sake of completeness, but it likely does not make sense to select it.

Order Import - Assignment

Orders, line items, customers, and transactions have fewer columns than before. See the Removed Columns section for a full list. If any of the settings in this section use any removed columns, please remove or replace the columns as appropriate.

One way of finding removed columns is to select each cell in the Source column which has a value and click its ‘ƒ’ button. If the mapping uses a removed column, the nested screen will display an ‘Invalid column’ error.

Customer Assignment Mapping, Customer Bill To Assignment Mapping, Customer Ship To Assignment Mapping, Sales Document Assignment Mapping, Sales Document Payment Mapping, and Sales Line Assignment Mapping are all affected by this change. Some of those settings have additional changes which are covered in the following sections.

Sales Document Assignment Mapping

This setting’s default value now maps Freight to Current Shipping Price Set instead of Total Shipping Price Set. This is because the Total Shipping Price Set column included removed shipping fees.

Shopify integrations which were created in older SalesPad versions will not automatically have these mapping updates. Users who want to ensure that freight does not include removed shipping fees should update the Freight mapping to its new default value:

Convert_To_Decimal(Order.CurrentShippingPriceSet.ShopMoney.Amount)

Sales Document Payment Mapping

Previously, the Order Import would always create exactly one GP payment. This was the case regardless of whether the order had any transactions at all, which types of transactions they were, and whether the order had multiple transactions.

Now, the Order Import will create one payment for each sale transaction and each capture transaction on the Shopify order. This means that the Order Import will no longer create payments for orders which have no transactions or which only have an authorization transaction. This also means that the Order Import can now create multiple payments for the same sales document.

This has a large effect on the Sales Document Payment Mapping setting. Transaction columns are now available, and it is now expected that the Amount Paid and Transaction Amount fields map to the transaction’s amount instead of the order’s total price. Otherwise, the Order Import may create duplicate payments if the Shopify order has multiple transactions. There are some safeguards to prevent duplicate payments if the Sales Document Payment Mappings setting was never changed from its previous default value, but it is strongly recommended to update this setting’s mappings.

At the minimum, please map Amount_Paid and Transaction_Amount to [Transaction.AmountSet.ShopMoney.Amount] instead of the order’s total price.

After making that change, scroll down to the Seq_Num field and remove its mapping by deleting whatever is in its Source column. This will tell the Order Import to auto-generate sequence numbers.

The following fields also now have different mappings by default. None of these changes are required. Note that Shopify’s Credit Card Number column masks all but the last 4 digits.

Cardholder_Name: [Transaction.PaymentDetails.CreditCardName]

Auth_Code: [Transaction.Authorization]

Credit_Card_Number: [Transaction.PaymentDetails.CreditCardNumber]

Expiration_Date: DateTimeFromParts([Transaction.PaymentDetails.CreditCardExpirationYear], [Transaction.PaymentDetails.CreditCardExpirationMonth], DaysInMonth([Transaction.PaymentDetails.CreditCardExpirationYear], [Transaction.PaymentDetails.CreditCardExpirationMonth]))

Order Import - Matching

Orders, line items, and customers have fewer columns than before. See the Removed Columns section for a full list. If any of the settings in this section use any removed columns, please remove or replace the columns as appropriate.

One way of finding removed columns is to select each cell in the Expression column and click its ‘ƒ’ button. If the mapping uses a removed column, the nested screen will display an ‘Invalid column’ error.

Customer Bill To Matching, Customer Matching, Customer Ship To Matching, and Item Master Matching are all affected by this change.

Order Update Export - Assignment

Captured Payment Mapping

Orders and transactions have fewer columns than before. See the Removed Columns section for a full list. If any of the settings in this section use any removed columns, please remove or replace the columns as appropriate.

This setting’s default mappings are now different in order to reflect some of the changes to the Sales Document Payment Mapping setting. Shopify integrations which were created in older SalesPad versions will not automatically have these mapping updates.

It is strongly recommended to change Amount_Paid’s mapping to [Transaction.AmountSet.ShopMoney.Amount]. Previously, it mapped to the order’s total price, which can be inaccurate if the captured authorization was not for the order’s full amount or if the order was edited after being created in Shopify.

After making that change, scroll down to the Seq_Num field and remove its mapping by deleting the whatever is in its Source column. This will tell the Order Import to auto-generate sequence numbers.

The following fields also now have different mappings by default. None of these changes are required. Note that Shopify’s Credit Card Number column masks all but the last 4 digits.

Cardholder_Name: [Transaction.PaymentDetails.CreditCardName]

Auth_Code: [Transaction.Authorization]

Credit_Card_Number: [Transaction.PaymentDetails.CreditCardNumber]

Expiration_Date: DateTimeFromParts([Transaction.PaymentDetails.CreditCardExpirationYear], [Transaction.PaymentDetails.CreditCardExpirationMonth], DaysInMonth([Transaction.PaymentDetails.CreditCardExpirationYear], [Transaction.PaymentDetails.CreditCardExpirationMonth]))

Additionally, Transaction_Amount now defaults to [Transaction.AmountSet.ShopMoney.Amount], but its previous default value of [Transaction.Amount] is an alias for that column.

Order Update Export - Matching

Order Update Export Location Matching

This setting now works very differently. As a result, its value was reset and must be reconfigured.

Previously, this setting worked like most other matching settings in that it allowed users to define rules for how Shopify locations match to GP locations. Now, the setting is simpler and allows users to directly map GP locations to Shopify locations. To enter a mapping, click the Add button to add a new row, select a GP location, and then select its corresponding Shopify location.

A GP location can only be mapped to a single Shopify location because the Order Update Export must know which Shopify location to use for each sales line item. However, it is possible to map multiple GP locations to the same Shopify location if desired.

Order Voided Export - Assignment

Order Cancel Options Assignment Mapping

Previously, Refund Amount and Currency were target fields for this setting. These fields allowed users to specify the exact amount to refund. Shopify replaced those fields with a simpler Refund field. If Refund is set to True, canceling an order will refund the customer. If Refund is set to False or is not mapped, canceling an order will not refund the customer.

This setting’s default value sets Refund to True. Shopify integrations which were created in older SalesPad versions will not automatically have this mapping update. Please map the Refund field to either True or False as applicable.

Product Export - Assignment

Product Variant Assignment Mapping

InventoryManagement and Position are no longer target fields. Tracked is now a target field and replaces the main use case of the InventoryManagement field. Note that the Product Export will automatically set Tracked to True for new products.

Scripts

Most scripts will need some tweaks to account for the Shopify integration changes. Please contact Cavallo if any scripts require any non-trivial changes.

Orders, variants, and several other Shopify entities have several fewer columns than before. See the Removed Columns section for a full list. If any scripts use any removed columns, please remove or replace the columns as appropriate.

Orders and their various child entities now use the SalesPad.Shopify namespace instead of ShopifySharp. All existing scripts except the Product Pre Export Script will need to be manually updated to account for this change. For example, most Sales Document Pre Import Scripts will have a line like the following:

In newer SalesPad versions, this line will not work as intended because sourceDoc’s fully qualified type is now SalesPad.Shopify.Order instead of ShopifySharp.Order. That line will work if it is replaced with the following code:

Shopify line items and other child entities also use the SalesPad.Shopify namespace, so additional changes may be required.

Removed Columns

There are fields which were previously available on Shopify entities but are no longer available in Shopify’s GraphQL API.  If these fields are used in the mapping or matching settings, they must be removed or replaced.

Order

• AppId

• CartToken

• CheckoutId

• CheckoutToken

• ClientDetails

• Company

• DeviceId

• DiscountCodes

• Fulfillments

• LandingSite

• Metafields

• Number

• OrderNumber

• ProcessingMethod

• ReferringSite

• Refunds

• ShippingLines

• Orders now have a ShippingLine column which provides a summary of shipping costs and codes on the order. It is recommended to use ShippingLine in mappings and scripts where ShippingLines were previously used. 

• Token

• UserId

Line Item

• AttributedStaffs

• FulfillmentLineItemId

• FulfillmentService

• FulfillmentStatus

• Grams

• PreTaxPrice

• PreTaxPriceSet

• Properties

• TipPaymentGateway

• TipPaymentGatewaySpecified

• TipPaymentMethod

• VariantInventoryManagement

Customer

All of these removed columns except Currency always had empty values because Shopify’s REST API did not populate them when loading an order.

• Addresses

• Currency

• This column was the currency that the customer used when they paid for their last order. Using the imported order’s shop currency can be a replacement for this column.

• LastOrderId

• LastOrderName

• Metafields

• OrdersCount

• TotalSpent

Address

• Default

Transaction

• CurrencyExchangeAdjustment

• DeviceId

• LocationId

• Please use Order.LocationId instead.

• Message

• OrderId

• Please use Order.Id instead.

• PaymentsRefundAttributes

• Source

• SourceName

• UserId

Payment Terms

• amount

• Currency

Payment Schedule

• amount

• Currency

• ExpectedPaymentMethod

Discount Application

• Type

Product Variant

• InventoryManagement

• Position