> For the complete documentation index, see [llms.txt](https://merchant-help.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://merchant-help.violet.io/platform-guides/saleor.md).

# 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 |

6. Click **Create**. The App is now active.
7. 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.

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="info" %}
**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.
{% endhint %}

## 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`).

{% hint style="info" %}
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.
{% endhint %}

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.

{% hint style="warning" %}
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.
{% endhint %}

## 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`               |

3. 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://merchant-help.violet.io/platform-guides/saleor.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.