Integration Guide

This guide is intended for Shopify merchants who are connecting their store to Violet through a Shopify Custom App. During this process, the merchant will create a Custom App in their Shopify dashboard and then provide the generated credentials to Violet through the Violet Connect onboarding tool. The merchant will retain full control of the created Custom App and can modify or remove it at any time from within their Shopify dashboard. Total time for completion is around 3 minutes.

​

Prerequisites:

A merchant must have a minimum Shopify plan of Basic to be able to connect with Violet.

​

Step 1: Creating the Custom App

1. From your Shopify dashboard navigate to Settings → Apps and sales channels → Develop Apps.
2. Click the green Create an app button.
3. In the modal that appears, enter an app name (ex. Violet) and select the user in your system who should be the owner of this app. Typically this is the default selected user.

​

Step 2: Configuring Scopes

From the App development view click on the Configuration tab.

​

Admin API Scopes

Click Configure or Edit in the Admin API integration section.

The following Admin access scopes are the minimum required for Violet to perform all necessary functions against your store. If any additional scopes are required by certain channels within Violet, these will be communicated to you when you enable to channel.

write_customers and read_customers - used to add new customers when perform non-guest checkouts.

write_draft_orders and read_draft_orders - used to populate and submit orders into your system.

read_fulfillments - used to read and communicate order fulfillment statuses to the channel.

read_inventory - used to read inventory data related to your products.

read_locations - used to read inventory location data related to your products.

write_orders and read_orders - used to update and read orders previously submitted by Violet into your system.

read_price_rules - used to understand the pricing rules related to your discounts.

read_discounts - used to understand the combination policies of your discounts.

read_products - used to read your product catalog.

read_shipping - used to understand your shipping policies.

read_​markets - used to understand the regions you ship to.

write_merchant_managed_fulfillment_orders - used to alert you when an order placed through Violet requires additional review before being fulfilled. This can be useful in mitigating fraud.

Optional Admin API Scopes
read_legal_policies - used to understand your refund and return policies.

read_returns - used to discover when a Violet sourced order has been returned.

​

Storefront API Scopes

Click Configure or Edit in the Storefront API integration section.

unauthenticated_write_checkouts - used to create carts without being subjected to Shopify’s rate limits.

unauthenticated_read_product_listings - used to read basic product data when creating carts without being subjected to Shopify’s rate limits.

unauthenticated_read_product_inventory - used to read product inventory data when creating carts without being subjected to Shopify’s rate limits.

​

Step 3: API Credentials

From the app view click API credentials then click Install App

Access Token

This token is used to authenticate requests made by Violet when interacting with your store. Important: this value can only be viewed once. It’s recommended that you copy and paste it into a temporary location until you finish the Violet onboarding process. If you lose this value before completing the Violet onboarding process you must uninstall the create app and start over.

API Key

This key is used in combination with the API Secret Key to verify and authenticate certain actions or events.

API Secret Key

This key is used in combination with the API Key to verify and authenticate certain actions or events.

Storefront API Access Token

An optional key used for authenticating requests to the Storefront API once you’ve enabled Storefront API access.

​

Step 4: Provide Configured App Credentials to Violet

Once your app is fully configured, it’s time to return to the Violet Connect onboarding tool and enter the follow credentials created in the previous steps:

• Access Token
• API Key
• API Secret Key

Once entered, click the Connect button to validate the credentials and complete the connection between your store and Violet. If the credentials are invalid you should check for any spaces or other copy/paste errors and try again.

Upon success you will be redirected back to the channel who first sent you to Violet.

​

Troubleshooting Onboarding Issues

​

Provided store URL is invalid or could not be found.

If you get the error “Provided store URL is invalid or could not be found.” when connecting a Shopify store, the first thing to do is double check that you have the correct URL provided.

1. Go to the Store Admin Page
2. Click on Settings
3. Click on Domains
4. Check for multiple domains listed here, if there is more than one, this is likely the cause of the above error
5. Select the URL that says “Redirects to …” and use this one (include https://) and you should be able to complete onboarding

​

Special Refund Considerations

Beyond the usual process for refunding an order this platform has special limitations and considerations that need to be kept in mind when interacting with orders from Violet:

While Shopify supports the normal Violet Refund process there is one very important call out for when you are canceling a Violet order.

In the cancellation dialogue (seen below) you must select Refund Payments NOW. This option is typically selected by default but this must be selected as that is what triggers the normal Violet Refund process to make sure your shopper is properly refunded when an order is canceled.

Note the “Manual” link indicating that no funds will actually be transferred from you to the shopper directly. Violet will take care of this as part of the normal flow seen here

​

Inventory Location Considerations

When syncing your product data, Shopify will combine the available inventories from all locations for each variant. The available quantity of a variant will be the aggregate of all available quantities across your locations. If you only utilize a single location this will not be an issue, and may not be an issue even when you operate multiple locations if you can fulfill from each one.

If you do however require that inventory is only synced from specific locations this can be accomodated. Please let your channel account representative know that you have this requirement and the inventory location filter will be applied to your account.