Saleor

This guide is intended for Saleor merchants who are connecting their store to Violet. During this process, you will create an App in your Saleor Dashboard, copy its authentication token, and provide it to Violet through the Violet Connect onboarding tool. You will retain full control of the App and can revoke it at any time from within your Saleor Dashboard. Total time for completion is around 5 minutes.

Prerequisites

• A Saleor 3.x instance with Dashboard admin access.

• Permission to create Apps in the Saleor Dashboard (Extensions section).

• At least one Channel configured in your Saleor instance (most installations have a default-channel).

Step 1: Create a Saleor App

Violet authenticates with your Saleor instance using an App bearer token. You need to create a dedicated App with the correct permissions.

1. Sign in to your Saleor Dashboard.

2. Navigate to Extensions in the left sidebar.

3. Click Create Custom App.

4. Enter a name for the App (e.g., Violet Integration).

5. In the Permissions section, enable the following permissions:

Permission	Why Violet Needs It
MANAGE_PRODUCTS	Read your product catalog, variants, inventory, and collections
MANAGE_ORDERS	Read orders and create draft orders for checkout
MANAGE_CHECKOUTS	Required by draft order creation to attach line items
MANAGE_USERS	Read customer data associated with orders
MANAGE_APPS	Allow Violet to manage its integration lifecycle and configuration

1. Click Create. The App is now active.

2. After creation, generate an Auth Token for the App:

   • In the App's detail page, locate the Tokens section.

   • Click Create Token.

   • Copy the generated token immediately.

The token is only shown once. If you lose it, you will need to create a new token. The previous token remains valid until explicitly deleted.

Why these permissions? Violet needs end-to-end access to sync your product catalog, process orders through connected channels, and receive real-time updates via webhooks. Each permission maps to a specific set of GraphQL operations Violet performs on your behalf.

Step 2: Identify Your Channel Slug (Optional)

Saleor organizes storefronts into Channels (e.g., default-channel, us-storefront, eu-storefront). Each channel can have its own currency, pricing, and product availability.

If you have multiple channels and want Violet to operate on a specific one:

1. In your Saleor Dashboard, navigate to Configuration > Channels.

2. Locate the channel that corresponds to the storefront you want to connect to Violet.

3. Copy the Channel Slug (e.g., default-channel, us-storefront).

If you leave the Channel Slug blank during onboarding, Violet will default to default-channel. If your Saleor instance only has one channel, you can skip this step.

If you operate multiple channels and want each connected to Violet separately, you will need to complete the onboarding process once per channel, each time specifying a different Channel Slug.

Step 3: Locate Your Saleor Instance URL

Your Saleor instance URL is the base URL of your Saleor backend (not your storefront). It typically follows one of these patterns:

• Saleor Cloud: https://your-store.saleor.cloud

• Self-hosted: https://api.your-domain.com or https://saleor.your-domain.com

You can confirm the correct URL by appending /graphql/ and visiting it in a browser. If it shows a GraphQL Playground, you have the right URL.

Do not enter your storefront URL (e.g., your Next.js or React storefront). Violet needs the URL of the Saleor backend API, not the customer-facing storefront.

Step 4: Provide Credentials to Violet

1. In the Violet Connect onboarding tool, select Saleor as your platform.

2. Enter the following credentials:

Field	What to Enter	Example
Store URL	Your Saleor instance URL from Step 3	https://my-store.saleor.cloud
App Token	The token generated in Step 1	(masked field)
Channel Slug (optional)	The channel slug from Step 2	default-channel

1. Click Connect. Violet will immediately validate your credentials by:

   • Connecting to your Saleor GraphQL API.

   • Verifying the App token authenticates successfully.

   • Confirming the App is active (not deactivated).

   • Checking that all required permissions are granted.

If any step fails, you will see a specific error message. Common issues:

Error	What to Check
"Saleor rejected the supplied App token"	Token was copied incorrectly, or belongs to a deleted/different App
"Saleor App is deactivated"	Re-enable the App in Extensions > [Your App]
"Saleor App is missing required permissions: ..."	Add the listed permissions to the App in Extensions > [Your App]
"Unable to reach Saleor at ..."	Check the URL is correct and the instance is accessible

Upon success, you will be redirected to complete the remaining onboarding steps.

---

Credential Summary

Credential	Required	Where to Find	Example
Store URL	Yes	Your Saleor backend URL	https://my-store.saleor.cloud
App Token	Yes	Extensions > [Your App] > Tokens	(not displayed after creation)
Channel Slug	No	Configuration > Channels > [Your Channel] slug	default-channel

---

How Violet Uses Your Credentials

Violet uses the App Token to authenticate all GraphQL API calls to your Saleor instance. This token is used to:

• Read your product catalog (products, variants, collections, pricing, and inventory) to make your items available for purchase through connected channels.

• Create draft orders when a customer begins checkout through a connected channel, and complete them to place the order.

• Read order and customer data to keep order status synchronized between Saleor and Violet.

• Register webhooks so that Violet is notified in real time when products, orders, or inventory change in your Saleor instance.

Your App Token is stored securely and encrypted at rest. It is never exposed to channels or end customers.

---

Special Considerations

Token Lifecycle

Saleor App tokens are long-lived and do not expire. They remain valid until you explicitly delete them in the Saleor Dashboard. There is no refresh flow. If you need to rotate your token:

1. Create a new token for the same App in Extensions > [Your App].

2. Update the token in Violet (contact support or re-run the onboarding flow).

3. Delete the old token in Saleor.

Revoking Access

To revoke Violet's access to your Saleor instance at any time:

1. Sign in to your Saleor Dashboard.

2. Navigate to Extensions in the left sidebar.

3. Locate the App you created for Violet (e.g., Violet Integration).

4. Either delete the token (to revoke access but keep the App) or delete the App entirely.

Once revoked, all subsequent Violet API calls to your store will fail. Create a new App and provide the new credentials to Violet to restore the connection.

Multi-Channel Setup

If your Saleor instance has multiple channels (e.g., a US storefront and an EU storefront), you can connect each channel separately:

1. Complete the onboarding process once per channel.

2. Use the same Store URL and App Token each time.

3. Enter a different Channel Slug for each connection.

Each channel will appear as a separate merchant in Violet with its own product catalog, pricing, and order stream.

Webhooks

After a successful connection, Violet will automatically register webhooks with your Saleor instance to receive real-time notifications for product, order, collection, customer, and fulfillment events. You do not need to configure webhooks manually.

You can view the registered webhooks in your Saleor Dashboard under Extensions > [Violet App] > Webhooks.

Permissions

If you need to change the App's permissions after onboarding:

1. Navigate to Extensions in your Saleor Dashboard.

2. Select the Violet App.

3. Update the permissions.

4. Save.

Violet will automatically detect the updated permissions on the next API call. If you remove a required permission, the affected operations will fail until the permission is restored.