Configuring the Deck Commerce Shopify App

Owned by Craig Dooley (Unlicensed)
Last updated: Feb 16, 2024 by Erwin Orendain
9 min read





Note: When saving configurations, the app will temporarily deactivate the integration, if required, update the settings, and then reactivate. Consider making updates during off-peak times and/or before live traffic is placing orders on the site.



General Behavior

The Shopify app collects input from merchant users to deploy and enable an enterprise-scale integration between Shopify and Deck Commerce OMS. The integration is implemented as “data flows”, each with their own configuration page.

For changes to take effect, you must always click “Save” at the top of a configuration page before navigating away from it. You will see messages indicating that the flow has restarted.

When you are notified that a new version of the app and its integration has been made available, you must restart the flows for the changes to take effect. Simply click “Save” and the app will indicate that the flow is restarting.

Connection Credential Configuration

To enter connection credentials to connect your Shopify store to your provisioned Deck Commerce instance:

  • Navigate to Apps > Deck Commerce to open the app.

  • Click "Settings" under "Connection Settings.

  • Enter the URL, Site Code, and Shared API token provided to you by the Deck Commerce team. Click "Save".

  • Click "Back to Home".



Order Synchronization Configuration

To configure your order sync settings:

  • Click "Settings" under "Order Sync to Deck Commerce".

  •  

    • Enter an optional comma-separated list of “Tags to Require”. These are tags that must be applied on the order in Shopify before the order will sync to the OMS. They allow you to more specifically control the flow of when orders are released to the OMS. The OMS will also add tags to the order that signify successful submission or an error. These tags will prevent an order from processing again.

    • Enter optional mappings for "Order Source". This allows you to define a mapping between values that appear on Shopify’s order “source” to different values in the OMS. You can match to the Shopify order source using a Regular Expression. You may enter various values under “Test a Source Name” to test whether your Regular Expression matches values correctly.

    • Specify which Shopify event should trigger an attempted order sync. Most of the time you want to use orders/updated and control the flow with “Tags to Require”. If you sync orders on orders/paid, it’s recommended that you do not set any “Tags to Require”.

    • If your store transacts using USD, the integration will automatically assign all taxes on orders to "US Sales Tax" in Deck Commerce. In this case no tax type mappings are required. If your store transacts outside of the U.S., see instructions for setting up Non-U.S. tax code mappings

    • All stores must set up mappings for shipping methods to describe how all available shipping methods in Shopify will be recorded in Deck Commerce. Click "View Mappings" and see instructions for setting up shipping method mappings.

    • Deck Commerce and Shopify are both capable of sending out similar email updates regarding the status of orders. Select which system will be responsible for these updates to avoid sending duplicates.

  •  

    • The integration can add meta fields to OMS orders as Custom Attributes. To enable this capability, optionally specify a comma-separated list of Shopify meta field namespaces. All meta fields on an order within that namespace will automatically be added as OMS Custom Fields.

    • By default all Shopify order line item properties (also called “attributes”) will sync to the OMS. Optionally, provide a comma-separated list of the names of line item properties you DO NOT want to sync to the OMS.

    • The integration assumes that gift messages on line items will be set as a line item property/attribute. If you apply gift messages to orders, specify the name of the line item property used for that information.

    • The integration supports the purchase and use of custom gift cards (via third party apps), and it assumes that when purchasing the custom gift card the requisite activation info will be added to the gift card line item as properties. This allows them to sync to the OMS in the appropriate locations. Do not configure this feature if using Shopify’s native gift card capability.

      To support custom gift cards, configure the following:

      • The property name and value to look for that will signify that a line item represents the purchase of a custom gift card.

      • The names of the line item properties that will store the sender and recipient information.

      • The names of the line item properties that will store metadata about the gift card. Dates must be specified in UTC/GMT.


    • The integration also supports the purchase of physical gift cards. Specify the line item property name and value that signify that a line item represents the purchase of a physical gift card product.

    • To enable the flow, click "Enable" at the top of the page. Remember, the action to enable will not take place until the "Save" button is clicked.

    • Click Save. This may require the integration to disable, save, and re-enable, so it may take up to 30 seconds to complete.

    • Click "Back to Home".



Order Update Configuration

To configure order updates settings, to configure how item fulfillment, item cancellations, and order cancellations sync back to Shopify:

  • Click "Settings" under "Order Updates from Deck Commerce".

  •  

    • Enter the Deck Commerce item status codes that should be considered an "Item Fulfilled" status. This will determine when an item is sent back to Shopify as fulfilled. Consult with the Deck Commerce team about this status code. If multiple codes, separate them with a comma.

    • Enter the Deck Commerce order status codes that should be considered an "Entire Order is Cancelled" status. This will determine when an order is sent back to Shopify as cancelled. Consult with the Deck Commerce team about this status code. If multiple codes, separate them with a comma.

    • Select whether you want fully cancelled orders to automatically refund via Shopify.

    • Enter the Deck Commerce item status codes that should be considered an "Item has been Reduced in Quantity/Cancelled" status. This will determine when an item is sent back to Shopify as reduced in quantity cancelled. Consult with the Deck Commerce team about this status code. If multiple codes, separate them with a comma. Note: The app will not automatically refund these transactions via Shopify.

    • Optionally, enter the Deck Commerce status code that should be considered order completed. This is not typically used, and the Deck Commerce team will advise you on when to use it.

    • Occasionally Shopify is unable to correctly map a tracking number to its appropriate carrier code. You can optional specify Regular Expressions to force certain tracking numbers to output specific carrier codes. Use the “Test a Tracking Number” field to validate that your regular expressions map to values correctly.

    • To enable the flow, click "Enable" at the top of the page. Remember, the action to enable will not take place until the "Save" button is clicked.

    • Click Save. This may require the integration to disable, save, and re-enable, so it may take up to 30 seconds to complete.

    • Click "Back to Home".



Inventory Feed Configuration



Inventory Configuration Assumptions

Deck Commerce does not provide SFTP services to support file exchanges.  Therefore, the configuration values shown in these screenshots are examples only and should not be used for any merchant configuration.  Merchants are to provide SFTP services and Deck has provided a method to manage those service settings in this configuration.

Please contact your Deck Commerce professional services team for any clarification or additional guidance.



To configure inventory feed updates from an SFTP location to Shopify:

  • Click "Settings" under "Inventory Feed to Shopify".

  • The inventory feed must come from an SFTP server. Enter the connection credentials to allow the app to connect to that SFTP server.



  • The app will watch in a specific location for files named a certain way. Enter the folder on that SFTP location where inventory files will be dropped and provide a regular expression describing the filenames that are valid inventory files.





  • The app polls the configured location on the SFTP server on a regular time interval to look for new inventory files to ingest. You can either select one of the simple time intervals available in the drop down or enter a cron expression to customize the time interval.

Note: Selecting a "polling frequency" other than "Custom" will automatically update the cron expression to whatever you've selected.

  • To enable the flow, click "Enable" at the top of the page. Remember, the action to enable will not take place until the "Save" button is clicked.

  • Click Save. This may require the integration to disable, save, and re-enable, so it may take up to 30 seconds to complete. If enabled, the app will begin to poll the SFTP location.

  • Click "Back to Home".


Cross-reference mappings must be set up when the value in a field from one system (e.g. Shopify) is related to a value in the compatible field from the other (e.g. Deck Commerce). All merchants will need to set up cross-reference mappings for shipping methods, and some will need to do so for tax types and payment methods.

Payment Transactions Configuration

There are currently no necessary or available configurations for the payment transactions integration flow.

Cross Reference Mapping Configuration

To set up cross-reference mappings:

  • Click "View" under "Cross-Reference Mapping".



  • To edit an existing mapping, click on it. Or to create a new one click "Add Mapping".

  • Select the type of mapping.




The rest of the page will change depending on which type of mapping you are creating or editing.

Shipping Method Mapping Configuration

To set up a shipping method mapping:

  • Enter the shipping method's title as described by Shopify. You can see the title by viewing an order that uses this shipping method in the Shopify admin.


In this example "Standard" is the shipping method title. Do not include the weight amount.

  • Enter the corresponding shipping method ID from your Deck Commerce instance, provided by the Deck Commerce team.

  • Click Save.



Sales Tax Mapping Configuration – Non-US Stores

Stores that transact in currencies other than USD will require non-U.S. Tax Type mappings. To set up a tax type mapping:

  • Enter the tax type's title as described by Shopify. You can see the title by viewing an order that uses this tax type in the Shopify admin.


In this example "QST" is the tax type title. Do not include the percentage amount.

  • Select which of Deck Commerce's available tax types corresponds to the one entered. The app will automatically allocate tax amounts as shipping or non-shipping tax, so both are combined into one selection.

  • Click Save.

Payment Method Cross-Reference Mapping Configuration

Stores that leverage manual payment methods will require cross-reference mappings for those payment methods. You do not need to provide a cross-reference mapping for credit card transactions processed by Shopify Payments, PayPal Express via Shopify, or Bogus Gateway (used for testing). To set up a payment type mapping:

  • Enter the payment type name, as it is configured in Settings > Payments > Manual Payment Types.


In the above example "Cash on Delivery (COD)" is an active manual payment method.