# Overview ## Welcome to Violet Merchant Help Welcome to Violet's comprehensive merchant documentation center. Whether you're just getting started or need help managing your existing integration, you'll find everything you need to successfully connect your store and maximize your cross-platform selling potential. ### Getting Started #### New to Violet? If you're here because a channel partner invited you to connect your store, you're in the right place. Violet makes it easy to expand your reach by selling through multiple channels while maintaining control of your inventory, pricing, and customer relationships. **Start Here:** [Understanding Violet Connect](#violet-connect-onboarding) #### Already Connected? If you've already completed onboarding and need help managing your integration, jump straight to: * [Merchant Dashboard Guide](#merchant-dashboard) * [Order Management](#order-management) * [Troubleshooting](#troubleshooting) *** ### Platform Integration Guides Choose your e-commerce platform to get started with a step-by-step integration guide: #### Popular Platforms (5-10 minutes setup) | Platform | Setup Time | Key Features | | ------------------------------------------------ | ----------- | ---------------------------------------------- | | [**Shopify**](/platform-guides/shopify) | \~5 minutes | Custom App creation, comprehensive API access | | [**BigCommerce**](/platform-guides/big-commerce) | \~5 minutes | Store-level API account, native coupon support | | [**WooCommerce**](/platform-guides/woo-commerce) | \~5 minutes | Plugin installation, WordPress integration | #### Enterprise Platforms (15-30 minutes setup) | Platform | Setup Time | Key Features | | --------------------------------------------------------------------------- | ------------ | -------------------------------------------- | | [**Salesforce Commerce Cloud**](/platform-guides/salesforce-commerce-cloud) | \~20 minutes | OCAPI + SCAPI configuration, customer groups | | [**Magento**](/platform-guides/magento) | \~15 minutes | API user creation, scope configuration | | [**CommerceTools**](/platform-guides/commercetools) | \~20 minutes | Project-level API client setup | #### Additional Supported Platforms * [**Prestashop**](/platform-guides/prestashop) - API key generation and webhook setup * [**Swell**](/platform-guides/swell) - Store API configuration * [**Spree**](/platform-guides/spree) - OAuth application setup * [**Vendo**](/platform-guides/vendo) - API credentials and webhook configuration * [**Ecwid**](/platform-guides/ecwid) - App installation and token generation * [**Wix**](/platform-guides/wix) - Business Solutions integration * [**Squarespace**](/platform-guides/squarespace) - Commerce API setup * [**Shoprenter**](/platform-guides/shoprenter) - API Credentials setup * [**Miva Merchant**](/platform-guides/miva) - API Token and signing key setup > **Note:** Each platform guide includes platform-specific requirements, step-by-step setup instructions, and troubleshooting tips. *** ### Violet Connect Onboarding Violet Connect is our streamlined merchant onboarding process that walks you through connecting your store in just a few minutes. #### What You'll Need * Access to your e-commerce platform's admin dashboard * Administrator permissions to create API credentials * Email address for account creation * Banking information for payout setup (if using Violet Payments) #### Onboarding Steps 1. **Platform Selection** - Choose your e-commerce platform 2. **Store URL Entry** - Provide your store's URL 3. **Credential Generation** - Follow platform-specific guide to create API credentials 4. **Credential Input** - Enter credentials in Violet Connect 5. **Payout Setup** - Connect your bank account via Stripe (if applicable) 6. **Commission Rate** - Set your agreed-upon commission rate 7. **Completion** - Get redirected back to your channel partner #### After Onboarding Once connected, you'll receive an email with: * Login credentials for your Merchant Dashboard * Summary of your connection settings * Next steps for managing your integration *** ### Merchant Dashboard Your Merchant Dashboard is your central hub for managing all aspects of your Violet integration. **Access:** [merchant.violet.io](https://merchant.violet.io) #### Dashboard Sections **Overview** * View connected store information * See all connected channels * Manage commission rates by channel * Monitor connection health **Orders (Bags)** * View all orders placed through Violet * Track order status and fulfillment * Add fulfillment and tracking details * Filter by channel, date, or status * Export order data **Catalog (Offers)** * View all synced products * Publish/unpublish products by channel * Filter by availability, status, and tags * Manage product visibility **Payouts** * Review payout history and status * Track distributions across orders * Manage payout account settings * View commission earnings by channel **Communication** * **Messages:** Direct communication with channels * **Notifications:** System alerts and updates * **Commission History:** Track rate changes over time *** ### Order Management #### Order Lifecycle 1. **Order Placement** - Customer places order through channel 2. **Order Sync** - Order appears in your e-commerce platform 3. **Fulfillment** - You fulfill the order as normal 4. **Status Updates** - Violet tracks fulfillment status 5. **Payout** - Commission is calculated and paid out #### Key Considerations by Platform **Shopify** * When canceling orders, always select "Refund Payments NOW" * Inventory syncs from all locations by default * Currency conversion uses real-time rates unless presentment currencies are configured **BigCommerce** * Refunds show as "offline" - this is expected behavior * Use Coupon Codes (not Promotions) for discount integration * Multi-currency pricing supported through contextual pricing **Salesforce Commerce Cloud** * Orders require special customer group (VIOLET\_API) * Payment method configuration needed (VIOLET\_API) * Refund notifications may require engineering integration *** ### Troubleshooting #### Common Connection Issues **"Store URL Invalid" Error** * **Shopify:** Check for multiple domains in Settings → Domains, use the primary domain * **All Platforms:** Ensure URL includes `https://` protocol * **Verification:** URL should match what appears in your admin dashboard **Credential Validation Failures** * Double-check for copy/paste errors and extra spaces * Ensure all required scopes/permissions are enabled * Verify credentials haven't expired or been regenerated * Check that API quotas haven't been exceeded **Missing Shipping Rates** * Configure shipping zones for all target markets * Ensure products have weight/dimensions configured * Verify shipping methods are enabled for your regions * Check for location-based shipping restrictions #### Platform-Specific Issues **Shopify** * **Minimum Plan:** Requires Shopify Basic or higher * **API Notices:** Ignore Shopify API deprecation notices - Violet handles updates * **Inventory Sync:** Contact support if you need location-specific inventory filtering **BigCommerce** * **Offline Refunds:** Expected behavior for Violet orders * **Coupon Issues:** Use Coupon Codes, not Promotions * **Currency:** Enable presentment currencies for multi-currency support **WooCommerce** * **Plugin Issues:** Ensure WordPress/WooCommerce versions are current * **Hosting:** Verify hosting provider allows external API connections * **Permissions:** Check file permissions if plugin installation fails *** ### Advanced Features #### Multi-Currency Support * **Default:** Real-time currency conversion * **Enhanced:** Presentment currency pricing (requires setup) * **Configuration:** Contact your channel partner to enable #### Inventory Management * **Single Location:** Automatic inventory sync * **Multiple Locations:** Combined inventory by default, filtering available * **Real-time Updates:** Inventory changes sync automatically #### Commission Management * **Flexible Rates:** Set different rates per channel * **Rate Changes:** Update anytime through dashboard * **History Tracking:** Full audit trail of rate changes * **Locking:** Channels can lock rates via API if pre-negotiated *** ### Getting Help #### Self-Service Resources * **Platform Guides:** Step-by-step integration instructions * **Dashboard Guide:** Complete merchant dashboard walkthrough * **API Documentation:** Technical reference for developers * **FAQ Section:** Answers to common questions #### Direct Support * **Channel Partner:** Your primary point of contact for business questions, technical issues and platform-specific help * **Merchant Dashboard:** Use Messages tab to communicate with channels * **Documentation:** AI-powered search (Ctrl/Cmd + K) #### Emergency Issues For urgent technical issues affecting order processing: 1. Contact your channel partner immediately 2. Check Violet status page for system-wide issues 3. Use Merchant Dashboard to temporarily unpublish affected products 4. Monitor order queue for processing delays *** ### Next Steps #### If You're Just Getting Started 1. **Choose your platform** from the integration guides above 2. **Follow the step-by-step guide** for your platform 3. **Complete Violet Connect onboarding** with your credentials 4. **Test your integration** with a sample order 5. **Explore your Merchant Dashboard** to familiarize yourself with the tools #### If You're Already Connected 1. **Bookmark your Merchant Dashboard** for easy access 2. **Review your commission rates** across all channels 3. **Set up order notifications** to stay informed 4. **Explore catalog management** to optimize product visibility #### Ready to Scale 1. **Connect additional channels** through the same process 2. **Optimize your product data** for better discoverability 3. **Monitor performance metrics** in your dashboard 4. **Consider advanced features** like presentment currencies *** *This documentation is continuously updated. For the latest information and new platform integrations, check back regularly or contact your channel partner.* # Shopify ## Prerequisites You must have a minimum Shopify plan of `Basic` to be able to connect with Violet. {% hint style="success" %} **Shopify Plan Changes** Shopify subscription plan upgrades and downgrades can happen in place without any interruptions, so long as a minimum plan of `Basic` is maintained. {% endhint %} {% hint style="info" %} **API Version Change Notices from Shopify** If you receive a notice from Shopify about future changes to the Shopify API that may impact Violet's connection to your store, you can ignore those. Shopify sends these out well in advance of deprecations and Violet will always ensure that the connection to your store remains in a healthy state. {% endhint %} *** {% hint style="warning" %} **Important: Channel Pre-Registration Now Available** As of January 2026, Shopify requires all new merchant connections to use single-merchant custom apps. Many channel partners now **pre-register** merchants, which means: * **If you received a Violet Connect link from your channel partner**: Your app is likely already created! Click the link and follow the simple authorization process (2 minutes). * **If you haven't received a link**: Contact your channel partner first - they may need to pre-register you. * **Only follow the manual setup below if**: Your channel partner specifically instructed you to create your own app. [Learn more about the pre-registration process →](https://github.com/violetio/docs/blob/main/channel-docs/ecom-platforms/shopify/merchant-onboarding.md) {% endhint %} {% hint style="warning" %} **Using Global-E for International Orders?** If your store uses Global-E (or Shopify's Managed Markets powered by Global-E) as the Merchant of Record for international orders, please notify your channel partner while onboarding. Orders placed through Violet bypass Global-E's checkout, which means Global-E cannot act as the Merchant of Record for those transactions. Your channel partner will need to configure your integration accordingly to avoid tax compliance gaps. [Learn more about Global-E and Shopify →](https://github.com/violetio/docs/blob/main/channel-docs/ecom-platforms/shopify/global-e.md) {% endhint %} ## Quick Start: Pre-Registered Merchants If your channel partner has pre-registered your store, onboarding takes just 2 minutes: 1. **Click the Violet Connect link** provided by your channel partner 2. **Verify your email** with the verification code sent to you ![Violet Connect Login](/files/QhMU1YepLMN2e0N8uSnv) ![Violet Connect 6-digit Code Authentication](/files/XLjQ2BbbBsim8oHBQdaC) 3. **Confirm your store URL** is correct ![Violet Connect Pre-registration Detected](/files/2uXPQA9CTbsFZk1zsxRI) 4. **Click "Connect to Shopify"** and authorize the app ![Shopify Install App OAuth Handshake](/files/bx0YiVmQIkAUthU3Svgb) ![Shopify OAuth Handshake Redirect to Violet Connect](/files/4lcRoC9IxywNf3AnQMFR) 5. **Complete payout setup** if required That's it! Your store is now connected. The manual setup below is only needed if not pre-registered. *** ## Manual Setup Guide (Advanced) This guide is for merchants who need to manually create a Custom App in their Shopify dashboard. **Most merchants should use the pre-registration method above instead.** During this process, you will create a Custom App in your Shopify dashboard and then provide the generated credentials to Violet through the Violet Connect onboarding tool. You will retain full control of the created Custom App and can modify or remove it at any time from within your Shopify dashboard. *Total time for completion is around 5 minutes.* {% embed url="" %} *** ### 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. {% hint style="info" %} Any topics with a `write_*` scope will automatically include the equivalent `read_*` scope. This is by design from Shopify. {% endhint %} #### 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 the channel. Violet uses these permissions to do three things: (1) sync your product catalog and inventory so channel partners can accurately display your products, (2) submit orders placed on those channels into your store so they appear alongside your other orders, and (3) report fulfillment and refund status back to the channel so shoppers stay informed. {% hint style="success" %} **Only 5 of these scopes involve write access:** four are used exclusively for orders and customer records created through Violet, and one (`write_publications`) publishes your products to the sales channels you connect through Violet. Violet never modifies your existing product data, prices, inventory, discounts, store settings, or theme. {% endhint %} **Products & Inventory (read-only)** | Scope | Why Violet needs it | | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `read_products` | Syncs your product titles, descriptions, images, variants, and prices so channel partners can display and sell them. | | `read_inventory` | Keeps stock levels in sync so channels stop selling an item the moment you run out — preventing oversells. | | `read_locations` | Shopify tracks inventory per location; this lets Violet total available stock across all of your locations. | | `read_metaobject_definitions`, `read_metaobjects` | Products can reference custom data ("metaobjects") such as size charts or material details; this lets that content appear on channel listings. | | `read_locales`, `read_translations` | For multi-language stores, ensures products display in the correct language on each channel. | **Publications** | Scope | Why Violet needs it | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `read_publications` | Reads which sales channels (publications) your products are published to. | | `write_publications` | Publishes your products to the sales channels you connect through Violet, so channel partners can list them. This is the only product-related scope that involves write access. | **Orders & Checkout (used only for orders placed through your connected channels)** | Scope | Why Violet needs it | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `write_draft_orders`, `read_draft_orders` | Draft orders are how Violet calculates shipping and taxes and places an order in your store — the same mechanism as manually creating an order in your admin. | | `write_orders`, `read_orders` | After an order is placed, Violet marks it as paid, records cancellations and refunds, and keeps its status in sync with the channel. Violet only writes to orders it created. | | `write_merchant_managed_fulfillment_orders` | Lets Violet place a **fulfillment hold** on an order it created when the order needs your review (e.g., suspected fraud) — so it isn't shipped before you've checked it. Never used on orders from your other sales channels. | **Customers** | Scope | Why Violet needs it | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `write_customers`, `read_customers` | When a shopper checks out on a channel, Violet creates (or matches by email, to avoid duplicates) the customer record so the order appears in your admin like any other. Violet does not export or sync your customer list. | **Shipping & Fulfillment (read-only)** | Scope | Why Violet needs it | | ------------------- | ------------------------------------------------------------------------------------------------------ | | `read_shipping` | Reads your shipping zones and rates so shoppers see your real shipping options and prices at checkout. | | `read_markets` | Reads the countries and regions you sell to, so checkout only accepts addresses you actually ship to. | | `read_fulfillments` | Reads tracking numbers and fulfillment status so shoppers receive shipping updates from the channel. | **Discounts (read-only)** | Scope | Why Violet needs it | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `read_discounts`, `read_price_rules` | When a shopper enters one of your discount codes at checkout, Violet validates it against your discount rules and applies the correct amount. Violet never creates or edits your discounts. | **Optional Admin API Scopes** | Scope | Why Violet needs it | | --------------------- | -------------------------------------------------------------------------------------------------------- | | `read_legal_policies` | Lets your refund and return policies be shown to shoppers at checkout. | | `read_returns` | Detects when an order placed through Violet is returned, so the channel can process the matching refund. | {% hint style="info" %} Webhook subscriptions should be left in the default state with the latest version being selected. {% endhint %} #### Storefront API Scopes (Optional) Click **Configure** or **Edit** in the `Storefront API integration` section. The Storefront API is the same public API your online store's theme uses — it only exposes data already visible to any shopper on your site. Violet uses it for high-volume cart operations because it scales better than the Admin API. | Scope | Why Violet needs it | | ---------------------------------------- | --------------------------------------------------------- | | `unauthenticated_write_checkouts` | Creates shopping carts as shoppers browse on the channel. | | `unauthenticated_read_product_listings` | Reads public product data while building carts. | | `unauthenticated_read_product_inventory` | Checks stock availability while building carts. | **Summary of access** * All inventory, shipping, and discount scopes are **read-only**, and Violet never edits your existing product data. * Write access is limited to orders and customer records **created through Violet**, plus publishing your products to the sales channels you connect (`write_publications`). * You retain full control: the app can be uninstalled from your Shopify admin at any time, immediately revoking all access. *** ### 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 (Optional)** {% embed url="" %} An optional key used for authenticating requests to the Storefront API once you've enabled Storefront API access. Pass the `Private access token` generated into Violet Connect's `Storefront API Access Token` field *** ### 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 following credentials created in the previous steps: * Access Token * API Key * API Secret Key Once entered, click the **Next** 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 Shopify now requires all merchants to use custom apps for new Violet integrations. If you're having issues during onboarding, check below for solutions. ### 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 {% hint style="info" %} You'll know you are using the correct domain when it matches what is shown in the address bar after `admin.shopify.com/store/[MATCH HERE]/settings/domains` {% endhint %} ![Multiple Domain](/files/GulgSzGqQjFl3UzJIBqz) {% hint style="info" %} A common issue that can happen when integrating a Shopify store is that there are no shipping rates available for a product. For instructions on how to ensure that your products' shipping configuration meets Violet's, you can follow this guide: [Shopify Merchant Shipping Configuration Requirements for Violet](https://github.com/violetio/docs/blob/main/merchant-docs/platform/shopify/platform/shopify/shipping.md) {% endhint %} # Shipping Configuration Requirements When a Merchant creates a new store in Shopify, the default configuration is as follows: * **2 Markets** * US; Domestic: **Active** * Rest Of World; International: **Inactive** ![](/files/X58budhNM9ePtMscIolE) * **1 Location; Inventory Storage** * This typically corresponds to the address you have added to your Shopify store profile. ![](/files/xrj0I2Gjr7fARAy099no) ![](/files/XJkR6W2Nv79WVxzVnsrr) * **Default General Shipping Profile** * Automatically linked to all products * Shipping Zone for all Markets * Shipping Zones tied to all Locations * Shipping Zones with Default Shipping Rates ![Default Shipping View](/files/rKYTEXg0XB3ksCLDskcB) ![Shipping Zones with Default Shipping Rates](/files/KHnvdz1d352CSEWrxvuh) **Configuring Your Store for Regional Shipping** To make your products available for shipping to customers in a specific region, it's essential to ensure that the following settings are configured correctly: * **Market** * To create a Shipping Zone for your customer's address, you must first have an active Market. Please note that it may take approximately 15 minutes for changes in market status (Active/Inactive) to be recognized in the checkout process. ![](/files/t2Rz9eA8cckvbVWTgk2q) * **Shipping Profile** * You need to create a Shipping Profile to house your Shipping Zones. * **Shipping Zone** * You must create a Shipping Zone to which you can attach Shipping Rates. ![](/files/9vXDIEnY1Ll3MhJaluSd) * **Product-Shipping Zone Association** * To display available Shipping Methods during checkout, each product you wish to sell must be associated with a Shipping Zone. Please note that each product can only be linked to one Shipping Profile. * **Shipping Zone Rate** * Ensure that you have defined a Rate for your Shipping Zone to provide customers with Shipping Method options during checkout. ![](/files/S4CHlZN9YvoDMKBGTqhw) ![](/files/0Zvvjb10P0pLXYu9VSGm) ![](/files/wfzwWfYg4aDzV5ohsaYx) * **Inventory Location** * The presence of inventory in the Location attached to your Shipping Zone is not a requirement. As long as there is inventory in any location, your products can be checked out. ![](/files/2ibpF3m0eDMK39z5N6lE) ![](/files/rSlQUS1JgeNFlbkDKVOT) * **Product-Market Association** * It's **not** mandatory to associate your product with a specific market to make it available for checkout through the Violet API. * **Location Priority** * Violet has a global view of inventory across all locations in your Shopify store. This also impacts the shipping rates that a customer is shown during checkout. For this reason, make sure that you update the priority order of locations where products are shipped from. ![](/files/NQI7yGCXY2tM9Ovd0iMV) # Inventory Location Considerations When syncing your product data, Shopify will combine the available inventories from all [locations](https://help.shopify.com/en/manual/fulfillment/setup/locations) for each [variant](https://help.shopify.com/en/manual/products/variants). 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. {% hint style="info" %} *Please note: This filter plays no role in order orchestration. During order creation, Shopify doesn't allow Violet to provide a preferred location ID in our request. Once Violet sends an order to Shopify for creation, it's Shopify who decides which location to actually pull the inventory from; developers have no say in this step.* {% endhint %} # Using Presentment Currencies When operating in a different default currency from the channel(s) you are selling your products through, realtime currency exchange rates will be used by default. If however you define explicit per-currency prices in your Shopify store these can be synced and used through our Contextual Pricing feature. Please notify the channel(s) you are connected to if you wish to have this feature enabled for your store. # Shopware This guide is intended for Shopware 6 merchants who are connecting their store to Violet. During this process, you will create an API Integration in your Shopware Administration, copy the generated credentials, and provide them to Violet through the Violet Connect onboarding tool. You will retain full control of the Integration and can modify or remove it at any time from within your Shopware Administration. *Total time for completion is around 5 minutes.* ## Prerequisites * A Shopware 6 instance with Administration access. * Permission to create Integrations in **Settings > System > Integrations**. * At least one **Sales Channel** configured in your Shopware instance. ## Step 1: Create an Admin API Integration Violet authenticates with your Shopware store using an **Admin API Integration**. This produces a pair of credentials that Violet uses to read your product catalog, pull orders, and register webhooks. 1. Sign in to your **Shopware Administration**. 2. Navigate to **Settings > System > Integrations**. 3. Click **Add integration**. 4. Enter a label for the integration (e.g., `Violet`). 5. Enable the **Administrator** toggle to grant full API access. 6. Click **Save**. After saving, Shopware displays two credentials: * **Access key ID** — begins with `SWIA`. This is the integration's public identifier. * **Secret access key** — a long random string. This is only shown once at creation. Copy both values and store them securely for the next steps. {% hint style="warning" %} **The Secret access key is only displayed once.** If you lose it, you will need to delete the integration and create a new one. The Access key ID can be viewed again at any time. {% endhint %} {% hint style="info" %} **Why Administrator access?** Violet requires broad read access across your store's products, orders, customers, and sales channels, as well as the ability to register webhooks for real-time sync and update order payment states when processing orders through connected channels. The Administrator role grants all of these permissions in a single step and is the fastest way to get connected. {% endhint %} ### Granular Permissions (Alternative to Administrator) If your organization requires more limited access, you can disable the **Administrator** toggle and instead assign a custom ACL role with the following permissions: | Permission | Required | Why Violet Needs It | | -------------------- | -------- | --------------------------------------------------------------------------------------------- | | `sales_channel:read` | Yes | Read sales channel configuration for shop profile | | `product:read` | Yes | Sync your product catalog to connected channels | | `order:read` | Yes | Pull orders for status synchronization | | `order:update` | Yes | Update payment state after order placement (e.g., mark as paid) | | `customer:read` | Yes | Read customer data associated with orders | | `currency:read` | Yes | Resolve currency for product pricing and order submission | | `webhook:create` | Yes | Register webhooks for real-time product, order, and customer updates | | `webhook:read` | Yes | Check for existing webhooks to avoid duplicates | | `system_config:read` | No | Read shop name and contact email; if unavailable, Violet falls back to the sales channel name | {% hint style="warning" %} If any required permission is missing, Violet will report a permissions error during onboarding. You can update the ACL role at any time without recreating the integration. {% endhint %} ## Step 2: Locate Your Sales Channel API Access Key (Optional) If you want Violet to submit orders directly into your Shopware store (Direct Order Submission), you will also need the **Sales Channel API access key**. This is a separate credential from the Admin API Integration created in Step 1. 1. In your Shopware Administration, open the **Sales Channels** section from the left sidebar. 2. Select the sales channel you want to connect to Violet (e.g., your **Storefront**). 3. Scroll down to the **API access** section. 4. Copy the **API access key** — this value begins with `SWSC`. {% hint style="info" %} **This credential is optional.** If you skip it, Violet will still sync your products, orders, and shop data. However, Direct Order Submission (allowing connected channels to place orders into your store) will be unavailable until a Sales Channel API access key is provided. You can add it later by updating your credentials in Violet. {% endhint %} {% hint style="warning" %} **Do not confuse the two keys.** The Admin API Integration credentials (Step 1) begin with `SWIA` and are found under **Settings > System > Integrations**. The Sales Channel API access key (Step 2) begins with `SWSC` and is found under **Sales Channels > \[Your Channel] > API access**. Pasting one into the wrong field will cause validation to fail. {% endhint %} ## Step 3: Identify Your Sales Channel ID (Optional) If your Shopware instance has multiple sales channels, you can specify which one Violet should use as the default for shop profile data (name, currency, language, country) and storefront URL resolution. 1. In your Shopware Administration, open the sales channel you want to connect. 2. The sales channel UUID can be found in the browser URL bar when viewing the channel (e.g., `https://your-shop.com/admin#/sw/sales/channel/detail/a1b2c3d4...`). 3. Copy this UUID value. {% hint style="info" %} If you leave the Sales Channel ID blank, Violet will automatically use the first available sales channel in your store. For most single-channel stores, you can skip this step. {% endhint %} ## Step 4: Provide Credentials to Violet 1. In the Violet Connect onboarding tool, select **Shopware** as your platform. 2. Enter the following credentials: | Field | What to Enter | Example | | --------------------------------------------- | ------------------------------------------------------- | ----------------------------- | | **Store URL** | The base URL of your Shopware store | `https://my-shop.example.com` | | **Access Key ID** | The Admin API Integration Access key ID from Step 1 | `SWIA...` | | **Secret Access Key** | The Admin API Integration Secret access key from Step 1 | *(masked field)* | | **Sales Channel API Access Key** *(optional)* | The Sales Channel API access key from Step 2 | `SWSC...` | | **Sales Channel ID** *(optional)* | The sales channel UUID from Step 3 | `a1b2c3d4-e5f6-...` | 3. Click **Connect**. Violet will immediately validate your credentials by: * Connecting to your Shopware Admin API and exchanging the Access Key ID and Secret Access Key for an authentication token. * Confirming the integration has sufficient permissions by reading your sales channels. * Verifying the Sales Channel API access key resolves to an active sales channel (if provided). If any step fails, you will see a specific error message. Common issues: | Error | What to Check | | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "Admin API integration credentials were rejected" | The Access Key ID or Secret Access Key was copied incorrectly, or the integration was deleted. Verify the values under **Settings > System > Integrations**. | | "Integration lacks the required privileges" | The integration does not have the Administrator role enabled. Edit the integration and enable the **Administrator** toggle, or assign a custom ACL role with the permissions listed in the Granular Permissions table above. | | "Sales Channel API access key is invalid" | The Sales Channel API access key does not resolve to an active sales channel. Verify the key under **Sales Channels > \[Your Channel] > API access**. Ensure you copied the `SWSC` key, not the `SWIA` key from Step 1. | | Invalid store URL error | The Store URL is unreachable. Verify the URL is correct and includes the protocol (e.g., `https://`). Do not include `/api` or `/store-api` at the end. | Upon success you will be redirected back to the channel who first sent you to Violet. *** ## Credential Summary | Credential | Required | Where to Find | Example | | ---------------------------- | -------- | --------------------------------------------------------- | -------------------------------- | | Store URL | Yes | Your Shopware store's base URL | `https://my-shop.example.com` | | Access Key ID | Yes | Settings > System > Integrations > \[Your Integration] | `SWIA...` | | Secret Access Key | Yes | Settings > System > Integrations (shown once at creation) | *(not displayed after creation)* | | Sales Channel API Access Key | No | Sales Channels > \[Your Channel] > API access | `SWSC...` | | Sales Channel ID | No | Sales channel UUID from the browser URL bar | `a1b2c3d4-e5f6-...` | *** ## How Violet Uses Your Credentials Violet uses two sets of credentials to interact with your Shopware store: * **Admin API credentials** (Access Key ID + Secret Access Key) are exchanged for a short-lived authentication token via OAuth2. This token is used to: * **Read your product catalog** (products, variants, pricing, media, categories) to make your items available for purchase through connected channels. * **Read orders** to keep order status synchronized between Shopware and Violet. * **Update order payment states** when payments are collected through connected channels. * **Register webhooks** so that Violet is notified in real time when products, orders, or customers change. * **Read shop configuration** (shop name, email, sales channel settings) to build your merchant profile. * **Sales Channel API access key** (optional) is used to: * **Submit orders** (Direct Order Submission) by creating a guest checkout through the Shopware Store API when a customer purchases through a connected channel. Your credentials are stored securely and encrypted at rest. They are never exposed to channels or end customers. The Admin API token is automatically refreshed and never stored long-term — only the Access Key ID and Secret Access Key are retained. *** ## Special Considerations ### Credential Lifecycle The Admin API Integration credentials (Access Key ID and Secret Access Key) do not expire. They remain valid until you delete the integration in your Shopware Administration. The short-lived OAuth tokens minted from these credentials expire automatically and are refreshed by Violet as needed. If you need to rotate your credentials: 1. Create a new integration in **Settings > System > Integrations**. 2. Update the credentials in Violet (contact support or re-run the onboarding flow). 3. Delete the old integration in Shopware. ### Revoking Access To revoke Violet's access to your Shopware store at any time: 1. Sign in to your **Shopware Administration**. 2. Navigate to **Settings > System > Integrations**. 3. Locate the integration you created for Violet. 4. Click **Delete**. Once deleted, all subsequent Violet API calls to your store will fail. Create a new integration and provide the new credentials to Violet to restore the connection. ### Multiple Sales Channels If your Shopware instance has multiple sales channels, you can connect a specific one by providing its Sales Channel ID during onboarding. The shop profile (name, currency, language, country) will be sourced from that channel. To connect multiple sales channels separately, complete the onboarding process once per channel, providing a different Sales Channel ID and Sales Channel API access key each time. ### Webhooks After a successful connection, Violet will automatically register webhooks with your Shopware instance to receive real-time notifications for product, order, and customer events. You do not need to configure webhooks manually. You can view the registered webhooks in your Shopware Administration under **Settings > System > Integrations** or via the Admin API. ### Direct Order Submission Direct Order Submission (DOS) allows connected channels to place orders directly into your Shopware store. It requires the Sales Channel API access key (Step 2). Without it, Violet operates in read-only mode — products and orders are synced, but new orders cannot be submitted into Shopware. {% hint style="info" %} **Double opt-in guest registration:** If your Shopware store has double opt-in enabled for guest registrations, Direct Order Submission will not work. This is a Shopware configuration that requires email confirmation before a guest account is activated. Contact your Shopware administrator to disable double opt-in for guest accounts if you want to use DOS. {% endhint %} # BigCommerce This guide is intended for BigCommerce merchants who are connecting their store to Violet. During this process, the merchant will create a Store-level API account in their BigCommerce dashboard and then provide the generated credentials to Violet through the Violet Connect onboarding tool. The merchant will retain full control of the created Store-level API account and can modify or remove it at any time from within the BigCommerce dashboard.*Total time for completion is around 5 minutes.* {% embed url="" %} ## Step 1: Creating the Store-level API Account 1. From your BigCommerce dashboard navigate to Settings → API → Store-level API accounts. 2. Click the blue Create API account button. 3. In the modal that appears, enter an account name (ex. Violet) ![](/files/1ZmvNc2KNK2HB04HSgQ2) *** ## Step 2: Configuring Scopes The following OAuth scopes are the minimum required for Violet to perform all necessary functions with your store. `Customers modify` - used to add new customers when performing non-guest checkouts. `Information & settings read-only` - used to read the store profile for plan type, supported currencies, and measurement units. `Orders modify` - used to update and read orders previously submitted by Violet into your system. `Products read-only` - used to read your product catalog. `Carts modify` - used to create carts for checkout. `Checkouts modify` - used to checkout carts. ![](/files/glEuywCtV6YnNGvTKYza) ## Step 3: API Credentials Click **Save** at the bottom of the 'Create account' page. You will be presented with a modal showing generated BigCommerce API credentials. Important: these values 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 these values before completing the Violet onboarding process you must start-over with a new Store-level API account. **Client ID** This key is used to identify Violet as the origin of any API requests made against your BigCommerce store. **Client secret** This key is used to verify the signatures of any data sent from your BigCommerce store to Violet. **Access token** This key is used to authenticate any API requests made by Violet against your BigCommerce store. ![](/files/vLZksMz1LqxfFMleIiuE) ## Step 4: Provide BigCommerce API credentials to Violet Once you have generated the API credentials, it’s time to return to the Violet Connect onboarding tool and enter the following credentials created in the previous steps: * Client ID * Client secret * Access Token Once entered, click the **Next** 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. ![](/files/ti43j1bBPcFA6Eu1fD9c) *** # Refunding Orders When refunding a Violet-sourced order in your BigCommerce dashboard you will see a notice informing you that the refund will be processed "offline" if you continue. This is OK as the payment was processed outside of your BigCommerce store, which BigCommerce calls "offline". When you create the refund in BigCommerce, Violet will automatically be made aware of the refund by BigCommerce and will then refund the shoppers payment. {% hint style="info" %} Orders should always be refunded or cancelled from within your BigCommerce admin dashboard. {% endhint %} # Creating Coupon Codes When creating coupon codes in your BigCommerce dashboard for use in Violet you will want to create true **Coupon Codes** and not **Promotions**. Promotions are intended for use in your BigCommerce storefront and cannot be applied to carts through the BigCommerce API at this time. # Using Presentment Currencies When operating in a different default currency from the channel(s) you are selling your products through, realtime currency exchange rates will be used by default. If however you define explicit per-currency prices in your BigCommerce store these can be synced and used through our Contextual Pricing feature. Please notify the channel(s) you are connected to if you wish to have this feature enabled for your store. # WooCommerce This guide is intended for WooCommerce merchants who are connecting their store to Violet. During this process, the merchant will install and configure the Violet plugin through their WooCommerce dashboard and then generate and provide credentials to Violet through the Violet Connect onboarding tool. Total time for completion is around 5 minutes. ## WooCommerce API Reliability Violet requires that the WooCommerce API functions in the way described by the [WooCommerce API reference](https://woocommerce.github.io/woocommerce-rest-api-docs/#introduction). If another 3rd party plugin is installed that breaks the WooCommerce API it is the merchants responsibility to remove or update that plugin. {% hint style="info" %} For the WooCommerce REST API to function correctly ensure that your Permalink structure is **Post name**. This can be configured by navigating to **Settings** → **Permalinks** in your WordPress admin dashboard. {% endhint %} ## Preview of End to End Onboarding Experience {% embed url="" %} *** ## Step 1: Installing the Violet Plugin 1. From Violet Connect [download the Violet Plugin for WooCommerce.](https://violet-extensions.s3.us-west-2.amazonaws.com/woocommerce/violet-connect.zip) 2. In a separate tab, open the admin dashboard of the Wordpress site where your WooCommerce store is hosted. 3. From the left sidebar, click Plugins. 4. Click the Add New button next to the Plugins title at the top of the page. 5. Click the Upload Plugin button next to the Add Plugins title at the top of the page. 6. Click Choose File and select the violet-connect.zip file that you downloaded in the first step. 7. Click Install Now. 8. Once the plugin has finished installing, click the Activate Plugin button. ![](/files/nssoIEVwW6q7QCiQ7ZHX) ## Step 2: Configuring the Violet Plugin 1. Locate the Violet plugin in the list of installed plugins on the Plugins page. 2. Navigate to the plugin configuration screen by clicking the Settings link associated with the Violet plugin. 3. From the list of available shipping extensions select the extension utilized by your store and click Save. If you do not see an extension listed for your shipping solution please reach out to your account administrator to request it. {% hint style="info" %} If your shipping extension is not listed, you can continue with the onboarding process. Violet will use your connection to implement coverage of your shipping extension after you have completed onboarding. {% endhint %}
WooCommerce Shipping [WooCommerce Shipping](https://woocommerce.com/document/woocommerce-shipping) is the official shipping extension provided by WooCommerce. It can be used to get realtime rates and print labels for USPS, UPS, and DHL directly in WooCommerce. The WooCommerce Shipping plugin must be installed in your WooCommerce store.
ShipStation [ShipStation for WooCommerce](https://woocommerce.com/products/shipstation-integration) allows you to sync your WooCommerce orders into the ShipStation platform where you can fulfill and manage your orders. The ShipStation plugin must be installed in your WooCommerce store.
Printful [Printful: Print on Demand for WooCommerce](https://woocommerce.com/products/printful) allows to sell print and embroider on demand products in WooCommerce while having Printful manage fulfillments. The Printful plugin must be installed in your WooCommerce store.
Pirate Ship The [Pirate Ship](https://www.pirateship.com/integrations/woocommerce) WooCommerce shipping integration allows you to get discounted shipping rates and manage order fulfillments. No plugin is required for Pirate Ship at this time.
Yun Express / Yun Track The [Yun Express](https://www.yunexpress.com) WooCommerce shipping integration provides you with cross-border ecommerce logistics.
![](/files/AchhXwFJHVDy3CsWT9YB) ## Step 3: Generate API Credentials 1. From the left sidebar, hover over WooCommerce then click Settings from the slide out menu. 2. Click the Advanced tab. 3. Click the REST API link just beneath the tabs. 4. Click the Add Key button. 5. Enter a description value that helps you recognize these as the Violet keys. 6. Select a user with an admin role. 7. Select `Read/Write` for the permissions type. 8. Click the Generate API Key button. Your API keys will be generated and should be saved for the next step. ![](/files/taytwjLy0ZpPLwt6dUKV) ## Step 4: Provide Configured Credentials to Violet **Store URL**\ This is the fully formed URL to where you have WooCommerce installed. If you provide any other URL the credentials will be rejected until the correct one is provided. **Consumer Key**\ This key is used in combination with the Consumer Secret to verify and authenticate certain actions or events. **Consumer Secret**\ This key is used in combination with the Consumer Key to verify and authenticate certain actions or events. ![](/files/rZzubNMEQInPLlxTtvoq) 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. # Magento This guide is intended for Magento 2 merchants who are connecting their store to Violet. During this process, the merchant will install and configure the Violet extension through their Magento 2 admin dashboard and then generate and provide credentials to Violet through the Violet Connect onboarding tool. *Total time for completion is around 10 minutes.* ## Step 1: Install the Violet Extension In this step you will obtain the Violet extension and install install it in your Magento store. 1. From the Magento Extension Marketplace grab the free [Violet extension](https://marketplace.magento.com/violet-violetconnect.html) by adding it your cart then completing the checkout. This will connect the extension to your Magento Connect account and immediately make it available for installation on any of your Magento stores. 2. In the following steps you will be using a terminal to connect to your Magento store and install the extension. If you are not familiar with this process you can learn more about it in the [Magento Documentation.](https://experienceleague.adobe.com/docs/commerce-operations/installation-guide/tutorials/extensions.html) 3. Open your terminal and connect to your Magento store. 4. Navigate to the root of your Magento installation. 5. Add the Violet extension to Composer and install it: {% hint style="warning" %} **Composer 2 is required.** Composer 1 has been deprecated and can no longer be used to install packages from Packagist. If you haven't already, [upgrade to Composer 2](https://getcomposer.org/upgrade/UPGRADE-2.0.md) before proceeding. {% endhint %} * Install from the [Magento Marketplace](https://marketplace.magento.com/violet-violetconnect.html): `composer require violet/violetconnect:1.2.0` * Install from [Packagist](https://packagist.org/packages/violetio/magento2): `composer require violetio/magento2:1.4.3` 6. Enable the Violet extension: `php bin/magento module:enable Violet_VioletConnect` 7. Update the database schema to include Violet: `php bin/magento setup:upgrade` 8. Deploy static files: `php bin/magento setup:static-content:deploy -f` 9. Flush the Magento cache: `php bin/magento cache:flush` 10. The Violet extension is now installed in your Magento store. ![](/files/wGh2g2IrQvzsCI8XtvZ1) ## Step 2: EnableStandalone Bearer Tokens (v2.4.4+) Violet requires the use of long-lived access tokens when interacting with your stores backend systems. If you are running Magento 2.4.4 or newer you will need to enable these tokens. For older versions these tokens are enabled by default. 1. Navigate to your Magento admin dashboard and sign in. 2. Navigate to Stores → Configuration → Services → OAuth. 3. In the selector labeled Allow OAuth Access Tokens to be used as standalone Bearer tokens, select `Yes`. 4. Click the Save Config button. ![](/files/R0P4gLS4G0mqYHz9tU49) ## Step 3: API Credentials Violet requires API credentials to authenticate requests when interacting with your stores backend systems. 1. Navigate to your Magento admin dashboard and sign in. 2. From the left sidebar click **Violet**. 3. Click the **Create API Credentials** button. 4. A new API user with the necessary access scopes has now been created. You will provide these credentials to Violet in the next step. ![](/files/77qaDmWdX8KMdlHyAIse) ## Step 4: Provide Configured Credentials to Violet **Store URL**\ This is the fully formed URL to where you have Magento installed. If you provide an incorrect URL the credentials will be rejected until the correct one is provided. **API Key**\ This key is used in combination with the API Secret to verify and authenticate certain actions or events. **API Secret**\ This key is used in combination with the API Key to verify and authenticate certain actions or events. 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. ![](/files/eYdGQ6SdE9kmhPQPUSaF) *** # Uninstalling the Violet Extension To uninstall the Violet extension perform the following steps. 1. Disable the Violet extension:\ `php bin/magento module:disable Violet_VioletConnect --clear-static-content` 2. Remove the Violet extension from Composer:\\ * If installed from Magento Marketplace: `composer remove violet/violetconnect` * If installed from Packagist: `composer remove violetio/magento2` 3. Run Setup Upgrade to reflect the removal of the extension:\ `php bin/magento setup:upgrade` 4. Reploy the static content:\ `php bin/magento setup:static-content:deploy -f` 5. Flush the Magento cache:\ `php bin/magento cache:flush` # Prestashop This guide is intended for Prestashop merchants who are connecting their store to Violet. During this process, the merchant will install and configure the Violet plugin through their Prestashop dashboard and then generate and provide credentials to Violet through the Violet Connect onboarding tool. *Total time for completion is around 10 minutes.* {% hint style="warning" %} **PrestaShop 1.7 or later is required.** The Violet plugin is compatible with PrestaShop version 1.7 and later. Earlier versions of PrestaShop are not supported. {% endhint %} ## Step 1: Installing the Violet Plugin {% hint style="info" %} If you are integrating with an app that does not facilitate checkout or interact with orders you can skip this step and begin with [Step 2](#step-2-generate-api-credentials). {% endhint %} 1. From Violet Connect select Prestashop. 2. In a separate tab, open the admin dashboard of the Prestashop site. 3. Download the [Violet Prestashop Plugin](https://violet-extensions.s3.us-west-2.amazonaws.com/prestashop/violet.zip). 4. From the left sidebar, locate the Improve section. 5. Click Modules then Module Manager. 6. Click the Upload a module button near the top-right corner of the page. 7. The upload modal should now be open. 8. Click Select File and select the violet.zip file that you downloaded in the first part of this step. 9. Once selected the plugin will begin installing. ## Step 2: Generate API Credentials 1. From the left sidebar, locate the Configure section. 2. Click Advanced Parameters then Webservice. 3. Click the Add new webservice key button near the top-right corner of the page. 4. Locate and click the Generate button near the Key field. 5. Enter a key description that will help identify that this key is used by Violet. 6. Ensure that the webservice key is enabled. 7. Configure the permissions so that they match the following values:
ResourceView (GET)Modify (PUT)Add (POST)Delete (DELETE)
addresses✔
carriers✔
cart_rules✔
carts✔✔✔✔
categories✔
combinations✔
configurations✔
contacts✔
content_management_system✔
countries✔
currencies✔
customer_messages✔✔✔✔
customer_threads✔
customers✔✔✔✔
customizations✔
deliveries✔✔✔✔
employees✔
groups✔
guests✔✔✔✔
image_types✔
images✔
languages✔
manufacturers✔
messages✔
order_carriers✔
order_details✔✔✔✔
order_histories✔✔✔✔
order_invoices✔✔✔✔
order_payments✔✔✔✔
order_slip✔✔✔✔
order_states✔✔✔✔
orders✔✔✔✔
price_ranges✔
product_customization_fields✔
product_feature_values✔
product_features✔
product_option_values✔
product_options✔
product_suppliers✔
products✔
search✔
shop_groups✔
shop_urls✔
shops✔
specific_price_rules✔
specific_prices✔
states✔
stock_availables✔
stock_movement_reasons✔
stock_movements✔
stocks✔
stores✔
suppliers✔
supply_order_details
supply_order_histories
supply_order_receipt_histories
supply_order_states
supply_orders
tags✔
tax_rule_groups✔
tax_rules✔
taxes✔
translated_configurations✔
violet_cart*✔✔✔✔
violet_config*✔✔✔✔
warehouse_product_locations✔
warehouses✔
weight_ranges✔
zones✔
{% hint style="info" %} The `violet_cart` and `violet_config` scopes are not required if the app you are integrating with does not facilitate checkout or interact with orders. {% endhint %} For a detailed explanation of why each scope is required, see [Why We Request Each Scope](/platform-guides/prestashop/prestashop-scope-reasons). ## Step 3: Provide Configured Credentials to Violet **Store URL**\ This is the fully formed public URL to your Prestashop store. If you provide any other URL the credentials will be rejected until the correct one is provided. The standard URL format is: ``` https://yourdomain.com/ ``` * Replace ‎\`yourdomain.com\` with your actual PrestaShop store domain. * This is the base endpoint for the PrestaShop Webservice API, which is used for most integrations. **API Token**\ This is the webservice key created in Step 2. # Why We Request Each Scope This section explains why Violet requests each PrestaShop Web Service API permission during merchant onboarding. PrestaShop's Web Service uses API keys with granular per-resource permissions for View (GET), Modify (PUT), Add (POST), and Delete (DELETE) operations. *** ## Product Catalog (Read-Only) These permissions allow Violet to sync the merchant's product catalog into our unified format so that channel partners can display and sell products. | Resource | View | Modify | Add | Delete | Why Violet Needs It | | ---------------------------------- | :--: | :----: | :-: | :----: | ------------------------------------------------------------------------------------------------------------------------------------------ | | **products** | ✔ | | | | Core product sync — retrieves product details (name, description, pricing, status, weight, dimensions) to create Violet Offers. | | **combinations** | ✔ | | | | Retrieves product variants (e.g., size/color combinations) with their individual pricing, stock, and attribute data to create Violet SKUs. | | **product\_options** | ✔ | | | | Reads attribute group definitions (e.g., "Size", "Color") to correctly label variant options on synced offers. | | **product\_option\_values** | ✔ | | | | Reads individual attribute values (e.g., "Red", "Large") to map variant names during product decomposition. | | **product\_features** | ✔ | | | | Reads product feature definitions (e.g., "Material", "Brand") for enriched product metadata. | | **product\_feature\_values** | ✔ | | | | Reads specific feature values associated with products for complete product attribute mapping. | | **product\_customization\_fields** | ✔ | | | | Reads custom field definitions on products (e.g., engraving text, custom image uploads) to understand product personalization options. | | **product\_suppliers** | ✔ | | | | Reads supplier references and pricing for products, used for complete product data mapping. | | **categories** | ✔ | | | | Reads product category hierarchy to classify and tag products within the Violet catalog. | | **images** | ✔ | | | | Retrieves product images (via product associations) to sync media into Violet Offers. | | **image\_types** | ✔ | | | | Reads available image size configurations to select the appropriate image dimensions for syncing. | | **specific\_prices** | ✔ | | | | Reads price overrides and sale pricing rules applied to specific products/combinations for accurate sale price decomposition. | | **specific\_price\_rules** | ✔ | | | | Reads catalog-level pricing rules to understand bulk or conditional pricing that affects product sale prices. | | **price\_ranges** | ✔ | | | | Reads shipping cost price ranges to understand carrier pricing tiers. | | **weight\_ranges** | ✔ | | | | Reads shipping cost weight ranges used in carrier rate calculations and product weight-based pricing. | | **manufacturers** | ✔ | | | | Reads manufacturer/brand information linked to products for brand attribution in the Violet catalog. | | **suppliers** | ✔ | | | | Reads supplier information linked to products for supply chain data mapping. | | **tags** | ✔ | | | | Reads product tags for search and categorization metadata in the synced catalog. | | **customizations** | ✔ | | | | Reads customization data attached to products (customer-submitted personalization) for order context. | | **search** | ✔ | | | | Enables product search capabilities within the PrestaShop catalog for lookup operations. | *** ## Order Management (Full Access) These permissions allow Violet to create orders on behalf of channel partners (Direct Order Submission), track order status changes, process refunds, and manage payment records. | Resource | View | Modify | Add | Delete | Why Violet Needs It | | -------------------- | :--: | :----: | :-: | :----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **orders** | ✔ | ✔ | ✔ | ✔ | **Create**: Submits orders from Violet checkout carts to the merchant's PrestaShop store. **Read**: Retrieves order details for status syncing and refund processing. **Update**: Modifies order properties (e.g., status transitions). **Delete**: Cleanup of failed/test orders. | | **order\_details** | ✔ | ✔ | ✔ | ✔ | **Read**: Retrieves individual line items (product, quantity, price) for order decomposition and refund calculations. **Update**: Modifies line item quantities during partial refund processing. | | **order\_payments** | ✔ | ✔ | ✔ | ✔ | **Read**: Retrieves payment information (amount, method, transaction reference). **Update**: Records Violet's payment transaction ID on the order after successful checkout so the merchant can reconcile payments. | | **order\_histories** | ✔ | ✔ | ✔ | ✔ | **Read**: Retrieves the history of status changes on orders. **Write**: Records status transitions (e.g., marking an order as processing or paid) during order lifecycle management. | | **order\_invoices** | ✔ | ✔ | ✔ | ✔ | **Read**: Retrieves invoice data linked to orders, needed to look up the correct invoice when updating payment records. **Write**: Manages invoice creation/updates during order finalization. | | **order\_slip** | ✔ | ✔ | ✔ | ✔ | **Read**: Retrieves credit memos/refund slips for orders to decompose refund data into Violet's format. **Write**: Creates new refund slips when processing returns or partial refunds through Violet. | | **order\_states** | ✔ | ✔ | ✔ | ✔ | **Read**: Retrieves the list of possible order statuses (e.g., Processing, Shipped, Delivered, Canceled, Refunded) for status mapping. **Write**: Allows management of custom order states if needed. | | **order\_carriers** | ✔ | | | | Reads the carrier/shipping method assigned to an order, used for shipping information in order decomposition. | *** ## Cart & Checkout (Full Access) These permissions power Violet's checkout flow, which creates and manages a PrestaShop cart before converting it to an order. | Resource | View | Modify | Add | Delete | Why Violet Needs It | | --------------- | :--: | :----: | :-: | :----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **carts** | ✔ | ✔ | ✔ | ✔ | **Create**: Initializes a new shopping cart when a customer begins checkout through a Violet channel. **Read**: Retrieves cart contents, totals, and available shipping options. **Update**: Adds/removes products, sets customer, applies addresses, selects shipping method. **Delete**: Cleans up abandoned or failed checkout carts. | | **cart\_rules** | ✔ | | | | Reads discount/promotion rules (coupon codes, automatic discounts) to understand available promotions during cart calculation. | *** ## Customer & Address Management These permissions allow Violet to create or reuse customer and guest records during checkout, and manage shipping/billing addresses. | Resource | View | Modify | Add | Delete | Why Violet Needs It | | ---------------------- | :--: | :----: | :-: | :----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **customers** | ✔ | ✔ | ✔ | ✔ | **Read**: Looks up existing customers by email to avoid duplicates during checkout. **Create**: Creates new customer records when a first-time buyer checks out. **Update**: Updates customer details (e.g., name corrections). **Delete**: Removes customer records created for failed/test orders. | | **guests** | ✔ | ✔ | ✔ | ✔ | **Read/Write**: Manages guest (non-registered) customer sessions during checkout. PrestaShop requires a guest record for anonymous checkouts. | | **addresses** | ✔ | | | | Reads customer address data for order context. | | **customer\_messages** | ✔ | ✔ | ✔ | ✔ | **Read/Write**: Manages customer service messages associated with orders — allows Violet to relay order-related communications between channel partners and the merchant's support system. | | **customer\_threads** | ✔ | | | | Reads customer support conversation threads linked to orders for context when handling order issues. | | **contacts** | ✔ | | | | Reads store contact information (support email, departments) used for customer service routing. | | **groups** | ✔ | | | | Reads customer group definitions (e.g., wholesale, VIP) needed when creating customers to assign the correct default group and pricing tier. | | **employees** | ✔ | | | | Reads employee/admin details during shop profile sync to identify the merchant contact and store administrator information. | | **messages** | ✔ | | | | Reads internal order messages/notes for order context and support handling. | *** ## Shop Configuration & Localization (Read-Only) These permissions allow Violet to understand the merchant's store setup, supported currencies, regions, and localization preferences. | Resource | View | Modify | Add | Delete | Why Violet Needs It | | ------------------------------- | :--: | :----: | :-: | :----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **configurations** | ✔ | | | | Reads critical shop settings: default currency, shop name, shop email, weight/dimension units, locale, language, timezone, and SSL domain. These values drive product sync, order composition, and shop profile creation. | | **translated\_configurations** | ✔ | | | | Reads localized/translated versions of configuration values for multi-language shop support. | | **currencies** | ✔ | | | | Reads currency definitions (ISO codes, symbols, exchange rates) to correctly map pricing between PrestaShop and Violet. Used during product sync, cart calculation, and order processing. | | **countries** | ✔ | | | | Reads country definitions and ISO codes — required during address creation to look up the PrestaShop country ID from an ISO code (e.g., "US" → country ID 21). | | **states** | ✔ | | | | Reads state/province definitions — required during address creation to look up the PrestaShop state ID from an ISO code and country (e.g., "CA" + US → state ID). | | **languages** | ✔ | | | | Reads available languages to handle localized product names, descriptions, and configuration values correctly. | | **zones** | ✔ | | | | Reads geographic zones (e.g., North America, Europe) used in shipping and tax rule calculations. | | **shops** | ✔ | | | | Reads multi-store shop definitions to identify the merchant's store setup and associate data with the correct shop context. | | **shop\_urls** | ✔ | | | | Reads shop domain URLs and SSL configuration — used to construct product URLs, image URLs, and determine the store's public-facing address. | | **shop\_groups** | ✔ | | | | Reads shop group definitions for multi-store setups to understand the merchant's store hierarchy. | | **stores** | ✔ | | | | Reads physical store location data associated with the PrestaShop instance. | | **content\_management\_system** | ✔ | | | | Reads CMS page information (e.g., terms of service, return policy) which may be referenced during checkout or order processing. | *** ## Shipping & Delivery | Resource | View | Modify | Add | Delete | Why Violet Needs It | | -------------- | :--: | :----: | :-: | :----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **carriers** | ✔ | | | | Reads available shipping carriers/methods (name, pricing, dimensions, delivery time) to present shipping options during Violet checkout and map to Violet's shipping model. | | **deliveries** | ✔ | ✔ | ✔ | ✔ | **Read**: Retrieves delivery information (carrier-to-zone price mappings). **Write**: Manages delivery records associated with orders during fulfillment tracking and status updates. | *** ## Tax & Pricing (Read-Only) These permissions allow Violet to correctly calculate and display tax-inclusive pricing. | Resource | View | Modify | Add | Delete | Why Violet Needs It | | --------------------- | :--: | :----: | :-: | :----: | ------------------------------------------------------------------------------------------------------------------- | | **taxes** | ✔ | | | | Reads tax rate definitions for price calculation and tax-inclusive pricing support during product sync. | | **tax\_rules** | ✔ | | | | Reads tax rules that link tax rates to specific countries/states/zones, enabling correct regional tax calculation. | | **tax\_rule\_groups** | ✔ | | | | Reads tax rule group assignments linked to products and carriers, determining which tax rules apply to which items. | *** ## Inventory & Warehousing (Read-Only) | Resource | View | Modify | Add | Delete | Why Violet Needs It | | --------------------------------- | :--: | :----: | :-: | :----: | -------------------------------------------------------------------------------------------------------------------------------------------------- | | **stock\_availables** | ✔ | | | | Reads available stock quantities per product and combination — critical for accurate inventory display and preventing overselling during checkout. | | **stocks** | ✔ | | | | Reads physical stock records across warehouses for complete inventory visibility. | | **stock\_movements** | ✔ | | | | Reads stock movement history (additions, removals, transfers) for inventory change tracking. | | **stock\_movement\_reasons** | ✔ | | | | Reads the reason codes for stock movements (e.g., customer order, return, manual adjustment) for audit context. | | **warehouses** | ✔ | | | | Reads warehouse definitions for merchants using multi-warehouse inventory management. | | **warehouse\_product\_locations** | ✔ | | | | Reads product-to-warehouse location mappings for inventory location tracking. | *** ## Violet Plugin Resources (Full Access) These are custom API resources provided by the Violet PrestaShop plugin, which extends PrestaShop's native Web Service API. | Resource | View | Modify | Add | Delete | Why Violet Needs It | | -------------------- | :--: | :----: | :-: | :----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **violet\_config**\* | ✔ | ✔ | ✔ | ✔ | **Read/Write**: Manages the Violet plugin's configuration on the merchant's store — stores the merchant ID, webhook URL, and integration settings. Created during onboarding and updated when configuration changes. | | **violet\_cart**\* | ✔ | ✔ | ✔ | ✔ | **Read/Write**: Extended cart endpoint provided by the Violet plugin that returns enriched cart data including calculated totals, available shipping methods, and tax breakdowns — data not available through PrestaShop's native cart API. | *\* Requires the Violet PrestaShop plugin to be installed.* *** ### Principle of Least Privilege The permission structure follows the principle of least privilege: * **Product and catalog resources** are read-only — Violet never modifies a merchant's product data. * **Configuration and localization resources** are read-only — Violet reads but never changes shop settings. * **Order and cart resources** require full access because Violet creates and manages the complete checkout-to-order lifecycle. * **Customer resources** require write access because Violet creates customer records during checkout. # Salesforce Commerce Cloud {% hint style="warning" %} Salesforce Commerce Cloud is not a whole ecommerce platform. Merchants typically attach an Order Management System (OMS) and Inventory Management System (IMS) to their SFCC store to create a whole solution. Violet is unable to access these OMS and IMS platforms through the SFCC API so we must integrate directly with these tools as well. We ask that merchants share the name(s) of their OMS and/or IMS tools with the channel they are connecting with so that Violet can ensure that it covers those tools with direct integrations. {% endhint %} This guide is intended for Salesforce Commerce Cloud merchants who are connecting their store to Violet. During the connection process, the merchant will configure their store to connect it to Violet. *Total time for completion is around 20 minutes.* {% embed url="" %} ## Create API Client for OCAPI From the account manager you will create and configured a new API Client for use by Violet. You can learn more about API Clients in the Salesforce Commerce Cloud documentation. The API Client should be created while you are logged into the account who's email address you will be sharing with Violet. 1. Navigate to the [Account Manager](https://account.demandware.com/) and sign in. *The email address used to sign in is the **Account Manager Email Address** value in Violet Connect.* 2. From the left sidebar menu click API Client. 3. Click the **Add API Client** button. 4. Enter a display name that will help you identify this API client with Violet. 5. Enter a secure password. *This is the **OCAPI Client Password** value in Violet Connect.* 6. Ensure that Access Control is Enabled. 7. Add your organization to the client. 8. If you are testing with a Sandbox store follow these steps: a. Search for the `Sandbox API User` role and select the role. b. To assign the role to the API client, click Add. c. Select the filter icon to specify the role scope. d. In the Add Instance Filters tab, select your organization. e. Enter the names of the instances to which you want the API client to have access. f. Select the instances. g. Click **Add**. 9. In the Default Scopes field, enter the following values: `mail` `roles` `tenantFilter` `profile` `openId` 10. Enter the following in the redirect URL field: `https://admin.us01.dx.commercecloud.salesforce.com/oauth2-redirect.html.` 11. In the Token Endpoint Auth Method selector select `client_secret_post`. 12. In the Access Token Format selector select `JWT`. 13. Click the **Save** button. 14. As the new API client is created, an ID will be generated. Keep track of this value as it will be used in the next step. *This is the **OCAPI Client ID** value in Violet Connect.* ## Configure OCAPI Next you will configure the [OCAPI](https://developer.salesforce.com/docs/commerce/b2c-commerce/references/b2c-commerce-ocapi/get-started-with-ocapi.html). This will require you to enter the following code snippets into the OCAPI configuration area of your system for both the [Data](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/OCAPI/current/usage/DataAPIResources.html?cp=0_16_4) and [Shop](https://documentation.b2c.commercecloud.salesforce.com/DOC1/topic/com.demandware.dochelp/OCAPI/current/usage/ShopAPIResources.html?cp=0_16_3) API’s. 1. Navigate to **Administration → Site Development → Open Commerce API Settings.** 2. In the **Type** selector, select `Data`. 3. In the **Context** selector, select `Global`. 4. Add the Violet client by entering the following code snippet into the textarea. If the area is currently empty you can copy/paste the entire snippet. If there is already something entered in the textarea you should should only copy the individual client piece and add to the list of clients already present. 5. Replace the `CLIENT_ID_FROM_PREVIOUS_STEP_HERE` with the ID of the API Client you created in the previous step. ```json { "_v": "23.1", "clients": [ { "client_id": "CLIENT_ID_FROM_PREVIOUS_STEP_HERE", "resources": [ { "resource_id": "/ocapi_configs/*", "methods": ["get"], "read_attributes": "(**)", "write_attributes": "(**)" }, { "methods": ["get", "post", "put", "patch", "delete"], "read_attributes": "(**)", "write_attributes": "(**)", "resource_id": "/**" } ] } ] } ``` 6. Click the **Save** button to save the Data/Global settings. 7. In the **Context** selector, select the value that matches the site you are connecting to Violet. *This is the **Site ID** value in Violet Connect.* 8. In the **Type** Selector select `Shop`. 9. Add the Violet client by entering the following code snippet into the textarea. If the area is currently empty you can copy/paste the entire snippet. If there is already something entered in the textarea you should should only copy the individual client piece and add to the list of clients already present. 10. Replace the `CLIENT_ID_FROM_PREVIOUS_STEP_HERE` with the ID of the API Client you created in the previous step. ```json { "_v": "23.1", "clients": [ { "client_id": "CLIENT_ID_FROM_PREVIOUS_STEP_HERE", "resources": [ { "methods": ["get", "post", "put", "patch", "delete"], "read_attributes": "(**)", "write_attributes": "(**)", "resource_id": "/**" } ] } ] } ``` ## Generating an Access Key Next you will generate an Access Key which acts as a password with access limited only to the OCAPI. Violet will use the key when accessing your system through the OCAPI. 1. In the top right corner of the business manager, click the User Profile icon. 2. Click the **Generate Access Key** button, a modal will open. 3. Select the `Agent User Login and OCAPI` scope and click the **Generate** button. Note: If the `Agent User Login and OCAPI` is not listed it means there is already a key generated with this scope. If you have that key available, you are done with this section. If not you must responsibly delete the existing key and generate a new one. 4. The access key will be exposed in plain text just one time, be sure to store this value for later use. *This is the **Access Key** value in Violet Connect.* ## Configuring the Violet Payment Method Next you will configure a new payment method that will be utilized by Violet when submitting orders back into your system. This will involve creating a new Customer Group, Payment Processor, and Payment Method, each of which will only be utilized by Violet. 1. Navigate to **Merchant Tools → Customers → Customer Groups.** 2. Click the **New** button to create a new customer group for Violet customers. 3. Select `Static` as the type. 4. Enter `VIOLET_API` as the customer group ID. Optionally enter a description indicating that this customer group is for customers created through the Violet API. 5. Click the **Save** button. 6. Navigate to **Merchant Tools → Ordering → Payment Processors**. 7. Click the **New** button to create a new payment processor for Violet orders. 8. Enter `VIOLET_API` as the ID then click the **Apply** button to save it. 9. Navigate to **Merchant Tools → Ordering → Payment Methods**. 10. Click the **New** button to create a new payment method for orders created by Violet. 11. Enter `VIOLET_API` as the payment method ID and `Violet` as the payment method name. 12. Ensure that the Enabled column is set to `Yes`. 13. In the details section, click the **Edit** button next to the Customer Groups label. 14. Select the `VIOLET_API` customer group and click the **Assign** button to apply it to the payment method. This will limit the payment method to only orders created by Violet. 15. In the **Payment Processor** selector, select `VIOLET_API` . 16. Click the **Apply** button to save the payment method. ## Enabling the SCAPI (Optional) Through the OCAPI connection that was configured in the previous steps Violet will be able to provide end-to-end commerce functionalities for the channels connected to your store. There are a few functionalities though that are not available in the OCAPI and can only be enabled through the SCAPI. These include the following: * Marking an Order as ready for export. * Marking an Order as paid. * Marking an Order as confirmed. If the automation of these actions is important to your operations than you will need to perform the following additional steps. 1. Navigate to **Administration → Site Development → Salesforce Commerce API Settings.** 2. If no Short Code is present, click the **Request Short Code** button. *This is the **Short Code** value in Violet Connect.* 3. Following the Short Code is the Organization ID. *This is the **Organization ID** value in Violet Connect.* 4. If you do not know your Realm ID or Instance ID, they can generally be located in the Organization ID. The typical Organization ID is as follows, `f_ecom_[Realm ID]_[Instance ID]`. As an example, if your Organization ID is `f_ecom_aaaa_001` your Realm ID is `aaaa` and your instance ID is `001`. *These are the **Realm ID** and **Instance ID** values in Violet Connect.* From the account manager you will create and configured a new API Client for use by Violet. You can learn more about API Clients in the Salesforce Commerce Cloud documentation. The API Client should be created while you are logged into the account who's email address you will be sharing with Violet. Next you will create a new API Client. Unfortunately SFCC does not allow us to use the same API Client that was created for OCAPI when interacting SCAPI. You will be performing the same actions you did when configuring the OCAPI Client, but with slightly different Roles and Scopes. 1. Navigate to the [Account Manager](https://account.demandware.com/) and sign in. 2. From the left sidebar menu click **API Client**. 3. Click the **Add API Client** button. 4. Enter a display name that will help you identify this API client with Violet. 5. Enter a secure password. *This is the **SCAPI Client Password** value in Violet Connect.* 6. Ensure that Access Control is Enabled. 7. Add your organization to the client. 8. Under Roles perform the following steps: a. Search for the `Salesforce Commerce API` role and select the role. b. To assign the role to the API client, click Add. c. Select the filter icon to specify the role scope (the scope is required by the Salesforce Commerce API). d. In the Add Instance Filters tab, select your organization. e. Enter the names of the instances to which you want the API client to have access. f. Select the instances. g. Click **Add**. 9. In the Default Scopes field, enter the following values: `mail` `roles` `tenantFilter` `profile` `openId` 10. In the Allow Scopes field enter the following vaues: `sfcc.shopper-baskets-orders.rw` `sfcc.orders.rw` `sfcc.catalogs.rw` `sfcc.products.rw` 11. Enter the following in the redirect URL field: `https://admin.us01.dx.commercecloud.salesforce.com/oauth2-redirect.html.` 12. In the Token Endpoint Auth Method selector select `client_secret_post`. 13. In the Access Token Format selector select `JWT`. 14. Click the **Save** button. 15. As the new API client is created, an ID will be generated. Keep track of this value as it will be used in the next step. *This is the **SCAPI Client ID** value in Violet Connect.* As there is no concept of refunds in both the OCAPI and SCAPI, Violet is unable to be notified of refunds or access any refund data. As a temporary workaround, you will need to perform one of the following steps. **Option 1: Mark Order as Cancelled**\ This option requires the least amount of effort. Simply mark any Violet orders as `cancelled` when the order is refunded and Violet will treat it as a refund. **Option 2: Notify Violet of Refunds**\ This option will likely require the involvement of your engineering team. When a refund occurs, you will need to send information about the refund to Violet so that it can process the refund accordingly. If you choose this option, the integration documentation will be shared with you by Violet or the channel that onboarded you. **Whats Next**\ Violet will begin integrating with the order management systems that you connect to your Salesforce Commerce Cloud stores. Once we have an integration with the OMS you use you will be able to remove/skip the above fallback options as Violet will be able to discover refunds automatically. # 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. # Swell This guide is intended for Swell merchants who are connecting their store to Violet. During this process, the merchant will create a Secret Key in the Swell dashboard and then provide the generated credentials to Violet through the Violet Connect onboarding tool. The merchant will retain full control of the created Secret Key and can modify or remove it at any time from within their Swell dashboard. *Total time for completion is around 3 minutes.* ## Step 1: Creating the Secret Key 1. From the navigation sidebar of your Swell dashboard navigate to **Developer → API Keys.** 2. Locate the section labeled **Secret Keys** and click the `Add secret key` button. 3. In the modal that opens, enter a description for the key that will remind you of the reason for creating this key. This can be as simple as "Violet" or the name of the channel you are connecting to. 4. Click the `Create Key` button. Your key will now be created. 5. Once created, you will need to click the small reveal icon to obtain the full key. 6. On this same page, under section labeled API Access locate and obtain your `Store ID`. ## Step 2: Provide App Credentials to Violet Once you have your **Store ID** and **Secret Key**, it’s time to return to the Violet Connect onboarding tool and enter the follow credentials created in the previous steps: 1. When prompted for your store URL, enter the full URL including the protocol. Example - `https://example.com`. 2. Enter your Store ID obtained in the previous steps in the "**Store ID**" field. 3. Enter your Secret Key obtained in the previous steps in the "**Secret Key**" field. 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. # Spree This guide is intended for SpreeCommerce merchants who are connecting their store to Violet. During this process, the merchant will create a new oAuth application in their Spree dashboard and then provide the generated credentials to Violet through the Violet Connect onboarding tool. The merchant will retain full control of the created oAuth application and can modify or remove it at any time from within their Spree dashboard. *Total time for completion is around 3 minutes.* ## Step 1: Creating App Credentials 1. From the left navigation sidebar of your Spree dashboard navigate to **Apps → oAuth Applications**. 2. In the upper right corner click the `New oAuth application` button. 3. Enter a **Name** for the new application that will remind you of the reason for creating this key. This can be as simple as "Violet" or the name of the channel you are connecting to. 4. In the **Scopes** field enter `admin write`. 5. Click the `Create` button. Your application will now be created. 6. The `Client ID` and `Client Secret` for the newly created application will now be revealed. Copy these values and keep them available for Step 2 of this guide. ## Step 2: Provide App Credentials to Violet Once you have your **Client ID** and **Client Secret**, it’s time to return to the Violet Connect onboarding tool and enter the follow credentials created in the previous steps: 1. When prompted for your store URL, enter the full URL including the protocol. Example - `https://yourstore.com`. 2. Enter your `Client ID` obtained in the previous steps in the "Client ID" field. 3. Enter your `Client Secret` obtained in the previous steps in the "Client Secret" field. 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. # Vendo This guide is intended for Vendo merchants who are connecting their store to Violet. During this process, the merchant will create a new oAuth application in their Vendo dashboard and then provide the generated credentials to Violet through the Violet Connect onboarding tool. The merchant will retain full control of the created oAuth application and can modify or remove it at any time from within their Vendo dashboard. *Total time for completion is around 3 minutes.* ## Step 1: Creating App Credentials 1. Within your Vendo admin dashboard navigate to your store settings page. This can be done by clicking on your store name in the upper left corner of the dashboard and then selecting **Settings**. 2. From the store settings page navigate to the **Developers** tab. 3. In the upper right corner click the `New API Key` button. 4. Enter a **Name** for the new application that will remind you of the reason for creating this key. This can be as simple as "Violet" or the name of the channel you are connecting to. 5. In the **Scopes** field enter `admin write`. 6. Click the `Create` button. Your application will now be created. 7. The `Client ID` and `Client Secret` for the newly created application will now be revealed. Copy these values and keep them available for Step 2 of this guide. ## Step 2: Provide App Credentials to Violet Once you have your **Client ID** and **Client Secret**, it’s time to return to the Violet Connect onboarding tool and enter the follow credentials created in the previous steps: 1. When prompted for your store URL, enter your Vendo store URL including the protocol. Example - `https://[yourstore].getvendo.com.` 2. Enter your `Client ID` obtained in the previous steps in the "**Client ID**" field. 3. Enter your `Client Secret` obtained in the previous steps in the "**Client Secret**" field. 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. # Ecwid This guide is intended for Ecwid merchants who are connecting their store to Violet. During the connection process, the merchant will install the Violet app through their Ecwid dashboard. Upon completion Ecwid will automatically provide Violet with the access keys required to sync with the merchants store. *Total time for completion is around 2 minutes.* ## Prerequisites: A merchant must have a minimum Ecwid plan of `Venture` to be able to connect with Violet. ## Step 1: Installing the Violet App 1. From Violet Connect select Ecwid as your platform. 2. Click **Continue**. You will be redirected to Ecwid. 3. Click the **Accept** button to accept the required access scopes. 4. The Violet app will now be installed and the embedded app experience will load. You are now successfully connected to Violet. Upon success you will be redirected back to the channel who first sent you to Violet. ### Refunds As there is no concept of refunds in the Ecwid API, Violet is unable to be notified of refunds or access any refund data. As a temporary workaround, you will need to perform *one* of the following steps. **Option 1: Mark Order as Cancelled**\ This option requires the least amount of effort. Simply mark any Violet orders as `cancelled` when the order is refunded and Violet will treat it as a refund. **Option 2: Notify Violet of Refunds**\ This option will likely require the involvement of your engineering team. When a refund occurs, you will need to send information about the refund to Violet so that it can process the refund accordingly. If you choose this option, the integration documentation will be shared with you by Violet or the channel that onboarded you. The Ecwid platform, as a rule, does not allow for an order placed via the API, as Violet does, to be refunded in the same way that an order placed on the storefront may be refunded.\ This means that for Violet Orders, the Ecwid interface refund button that can typically be used to start a refund is not able to be used. Instead, simply mark any Violet orders as `refunded` or `cancelled` when the order is refunded and Violet will treat it as a full refund. ## Information for Managed Stores In the situation where the merchant does not manage their own store but works with a management agency, here is the configuration information to pass on to the agency: **Webhook URL**: **Webhooks Topics**: * Order (updated, deleted) * Product (created, updated, deleted) * Store profile (updated, subscription plan updated) * Application (subscription status updated, uninstalled) **Scopes**: * read\_store\_profile * read\_store\_limits * read\_catalog * read\_orders * update\_orders * create\_orders * read\_customers * create\_customers * read\_discount\_coupons {% hint style="warning" %} Merchants must have 3rd party cookies enabled and any ad-blockers or browser shields in their browser disabled when using Ecwid. It is recommended that these actions are taken before they begin the connection process. {% endhint %} # Square This guide is intended for Square merchants who are connecting their store to Violet. During the connection process, you will be redirected to Square to authorize the Violet application. Upon completion, Square will automatically provide Violet with the access tokens required to sync with your store. *Total time for completion is around 2 minutes.* ## Prerequisites Your Square account must have at least one **active location** configured. Violet uses your primary location to identify your store and populate your shop profile. ## Step 1: Begin the Connection 1. From Violet Connect, select **Square** as your platform. 2. Click **Continue**. You will be redirected to Square's authorization page. ## Step 2: Authorize Violet 1. Log in to your Square account if prompted. 2. Review the permissions that Violet is requesting (see [Permissions](#permissions-granted-to-violet) below). 3. Click **Allow** to grant Violet access to your store. Upon authorization, Square will redirect you back to Violet Connect and your store will be fully connected. Upon success you will be redirected back to the channel who first sent you to Violet. ## Permissions Granted to Violet During the authorization process, Violet requests the following permissions from your Square account: | Permission | Purpose | | ----------------------- | --------------------------------------------------------------------------- | | `ORDERS_READ` | Read orders placed through Violet to track fulfillment status. | | `ORDERS_WRITE` | Create and update orders in your Square account when a purchase is made. | | `ITEMS_READ` | Read your product catalog to make your items available for purchase. | | `CUSTOMERS_READ` | Read customer data associated with orders. | | `MERCHANT_PROFILE_READ` | Read your merchant profile and location information to identify your store. | ## Access Token Refresh Square access tokens expire every 30 days. Violet automatically refreshes your access token in the background using the refresh token obtained during the initial authorization. No action is required on your part to maintain your connection. # CommerceTools This guide is intended for CommerceTools merchants who are connecting their store to Violet. During this process, the merchant will create a new API Client in their CommerceTools dashboard and then provide the generated credentials to Violet through the Violet Connect onboarding tool. The merchant will retain full control of the created API Client and can remove it at any time from within their CommerceTools dashboard. *Total time for completion is around 3 minutes.* ## Step 1: Creating App Credentials 1. Within your CommerceTools admin dashboard navigate to the **Developer settings** page. This can be done by activating the Settings section in the left sidebar and clicking `Developer settings`. 2. From the **Developer settings** page click the `Create new API client` button. This button is generally located in the upper right corner of the page. 3. Enter a **Name** for the new API Client that will remind you of the reason for creating this client. This can be as simple as “Violet” or the name of the channel you are connecting to. 4. In the **Scopes** section check ensure that each of the following boxes is checked. ![](https://res.cloudinary.com/ddhjp8mca/image/upload/v1695964420/mintlify/violet_commercetools_min_scopes_uql6bg.png) 5. Click the **`Create API client`** button. Your API Client will now be created. 6. The **`Client ID`** and **`Client Secret`** for the newly created application will now be revealed. Copy these values and keep them available for Step 2 of this guide. *Once you close the screen with the credentials you will no longer be able to see them again.* ## Step 2: Provide App Credentials to Violet Once you have your **Client ID** and **Client Secret**, it’s time to return to the Violet Connect onboarding tool and enter the follow credentials created in the previous steps: 1. When prompted for your store URL, enter the URL of the storefront, including the protocol, that is powered by your CommerceTools backend. Example - **`https://yourstore.com`.** 2. Enter your **`Client ID`** obtained in the previous steps in the ”**Client ID**” field. 3. Enter your **`Client Secret`** obtained in the previous steps in the ”**Client Secret**” field. 4. Enter your `**Project Key**` in the “**Project Key**” field. 5. Select the **`Region`** your CommerceTools instance operates in. Available options are: 1. `North America (Google Cloud)` 2. `North America (AWS)` 3. `Europe (Google Cloud)` 4. `Europe (AWS)` 5. `Australia (Google Cloud)` 6. Enter the URL that includes product page path in the “**Product Path URL**” field. This is the part of the URL that precedes the individual page of each product in your store. As an example, if you sell a product called “Purple Shirt” that is located at `https://yourstore.com/products/purple-shirt` your product path URL would be `https://yourstore.com/products`. This is the value you would enter in this field. 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. # Wix This guide is intended for Wix merchants who are connecting their store to Violet. During this process, the merchant will create a new API Key in their Wix dashboard and then provide the generated credentials to Violet through the Violet Connect onboarding tool. The merchant will retain full control of the created API Key and can remove it at any time from within their Wix dashboard. *Total time for completion is around 3 minutes.* {% embed url="" %} ## Step 1: Creating App Credentials 1. Within your Wix admin dashboard navigate to the **Account Settings** page. This can be done by clicking on your profile image in the upper right corner of the Wix dashboard and then selecting `Account Settings` from the menu. 2. From the **Account Settings** page click on `Api Keys` from left sidebar. This page link is generally the last option in the left sidebar menu. 3. Click the `Generate API Key` in the upper right corner of the **API Keys** page. 4. Enter a **Name** for the new API Key that will remind you of the reason for creating this client. This can be as simple as “Violet” or the name of the channel you are connecting to. 5. In the **Scopes** section ensure that each of the following boxes are checked. 1. `Basic permissions` → `Get Sites List` 2. `All account permissions` → `Manage Sites` 3. `All site permissions` → `Wix Stores` 4. `All site permissions` → `Wix Currencies` 5. `All site permissions` → `Business Info` 6. Click the `Save & Close` button. Your `API Key` will now be created. 7. A modal will appear with your `API Key`. Copy this token and keep it available for Step 2 of this guide. *Once you close the screen with the key you will no longer be able to see it again.* 8. Once you close the API Key screen you will be returned to the `API Keys` page that lists your tokens. On the right side of this screen you will find the `Account ID` section. Copy the `Account ID` and keep it available for Step 2 of this guide. 9. Next go to the Home screen of your Wix Dashboard. This can be done by clicking on the Wix logo in the upper left corner of the Wix Dashboard. 10. Once you are on the Home screen, the URL in your browser will contain your Site ID between `/dashboard/` and `/home`. In this example URL, `https://manage.wix.com/dashboard/83749f16-12a9-2109-913e-ed6fed5c7e4d/home`, `83799f16-12a9-4803-963e-ed6fed6c7e4d` is the Site ID. Copy this value and keep it available for Step 2 of this guide. ### Step 2: Provide App Credentials to Violet Once you have your **Client ID** and **Client Secret**, it’s time to return to the Violet Connect onboarding tool and enter the follow credentials created in the previous steps: 1. Enter your `API Key` obtained in the previous steps in the ”**API Key**” field. 2. Enter your `Account ID` obtained in the previous steps in the ”**Account ID**” field. 3. Enter your `Site ID` obtained in the previous steps in the “**Site ID**” field. 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. *** ## Special Considerations ### Mandatory Custom Text Fields Custom text fields are **not** supported at this time as Violet is not able to verify that any freeform text entered by a shopper will meet your requirements. For this reason, any products with **mandatory** custom text fields will be marked as unavailable for purchase. We recommend that you use native Wix variants/options when possible, especially if your custom text fields are limited to a set of possible values. *** # Troubleshooting
The provided merchant credentials are invalid Please make sure you correctly copy and pasted the API Key and Account ID.
{% hint style="info" %} Make sure your Site ID is correct. This should be a GUID like `83799f16-12a9-4803-963e-ed6fed6c7e4d`. If you paste the entire url like `https://manage.wix.com/dashboard/83749f16-12a9-2109-913e-ed6fed5c7e4d/home` you **will** get this error. {% endhint %} # Squarespace This guide is intended for Squarespace merchants who are connecting their store to Violet. During this process, the merchant will create a new API Key in their Squarespace dashboard and then provide the generated credentials to Violet through the Violet Connect onboarding tool. The merchant will retain full control of the created API Key and can remove it at any time from within their Squareapace dashboard. *Total time for completion is around 5 minutes.* ## **Step 1: Creating App Credentials** 1. Within your Squarespace site admin dashboard navigate to the **Settings** page using the left sidebar navigation. 2. From the **Settings** page, expand the Developer Tools section in the left sidebar and click on Developer API Keys. 3. Click the `Generate Key` button on the Developer **API Keys** page. A modal will now open. 4. Enter a **Key Name** for the new API Key that will remind you of the reason for creating this client. This can be as simple as “Violet” or the name of the channel you are connecting to. 5. In the **Permissions** section ensure that each of the following boxes are checked. 1. `Products` → `Read Only` 2. `Inventory` → `Read Only` 3. `Orders` → `Read and Write` (Orders permission is only required if the channel you are connecting to requires it.) 6. Click the **Generate Key** button in the upper right corner of the modal. Your `API Key` will now be created. 7. The modal will refresh and display your new `API Key`. Copy this token and keep it available for Step 2 of this guide. *Once you close the screen with the key you will no longer be able to retreive the key.* ## **Step 2: Provide App Credentials to Violet** Once you have your **API Key**, it’s time to return to the Violet Connect onboarding tool and enter the following credentials created in the previous steps: 1. When prompted for your store URL, enter the full URL including the protocol. Example - `https://example.com`. 2. Enter your `API Key` obtained in the previous steps in the ”**API Key**” field. 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. {% hint style="info" %} **Shipping Rates:** Squarespace does not provide shipping rates through the API. Please use the [Violet merchant dashboard](https://merchants.violet.io) to configure your shipping rates. {% endhint %} # Troubleshooting
The provided merchant credentials are invalid Please make sure you correctly copy and pasted the API Key.
# Shoprenter This guide is intended for Shoprenter merchants who are connecting their store to Violet. During this process, the merchant will obtain the API credentials in their Shoprenter dashboard and then provide the generated credentials to Violet through the Violet Connect onboarding tool. *Total time for completion is around 5 minutes.* ## **Step 1: Obtaining API Credentials** 1. Within your Shoprenter site admin dashboard navigate to the **Settings** page using the left sidebar navigation. 2. From the **Settings** page, click **API User** in the **API settings** block. 3. If no credentials exist yet you will need to create new ones and save them. 4. Ensure that the **API Status** is set to `Authorized`. ## **Step 2: Provide App Credentials to Violet** Once you have your API credentials it’s time to return to the Violet Connect onboarding tool and enter them in their relevant fields: 1. Enter your `API url` in the ”**Store URL**” field. 2. Provide your `Username` in the **API Username** field. 3. Provide your `Password` in the **API Password** field. 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. # Shoplazza This guide is intended for Shoplazza merchants who are connecting their store to Violet. During this process, the merchant will create a Private App in their Shoplazza admin dashboard to generate an Access Token, and then provide it to Violet through the Violet Connect onboarding tool. The merchant will retain full control of the created Private App and can modify or delete it at any time from within their Shoplazza admin dashboard. *Total time for completion is around 5 minutes.* ## Step 1: Creating a Private App The Access Token is **required** to connect your Shoplazza store to Violet. It is generated by creating a Private App in your Shoplazza admin. 1. Log in to your Shoplazza admin dashboard as the store owner. 2. Navigate to **Apps > Manage Private Apps**. 3. Click **"Create App"**. 4. Enter an app name (e.g., "Violet Integration"). 5. Enter an emergency developer email address. 6. Select the Webhook API version (use the default/latest). 7. Grant the following permissions: | Permission | Purpose | | ----------------- | ----------------------------------- | | `read_product` | Sync your product catalog to Violet | | `read_order` | Import order data | | `write_order` | Enable Direct Order Submission | | `read_customer` | Access customer data on orders | | `read_collection` | Sync product collections | | `read_shop` | Access store profile information | 8. Click **Create** to generate the Private App. 9. Copy the **Access Token** that is displayed. {% hint style="warning" %} **Important:** The Access Token may only be fully visible once at creation time. Copy and save it securely before navigating away. If you lose the token, you may need to delete the Private App and create a new one. {% endhint %} {% hint style="info" %} The Access Token is a long-lived, static credential. It does not expire and does not need to be refreshed. {% endhint %} ## Step 2: Provide Credentials to Violet Once you have your Access Token, return to the Violet Connect onboarding tool and enter the following: 1. When prompted for your store URL, enter the full URL of your Shoplazza store including the protocol. Example: `https://mystore.myshoplazza.com`. 2. Enter your **Access Token** obtained in Step 1 in the "Access Token" field. Once entered, click the **Connect** button to validate the credentials and complete the connection between your store and Violet. Violet will verify your Access Token by connecting to your Shoplazza store — if the token is invalid, you will receive an error message. If the credentials are invalid, check for: * Spaces or other copy/paste errors in the Access Token * The store URL is correct (e.g., `https://mystore.myshoplazza.com`) * The Private App has not been deleted * The required permissions were granted when creating the Private App Upon success you will be redirected back to the channel who first sent you to Violet. *** ### Credential Summary | Credential | Required | Where to Find | | ------------ | -------- | ------------------------------------------------------------------ | | Store URL | Yes | Your Shoplazza store URL (e.g., `https://mystore.myshoplazza.com`) | | Access Token | Yes | Shoplazza admin > Apps > Manage Private Apps > Create App | *** ### Special Considerations #### Required Permissions When creating the Private App, you must grant all six permissions listed in Step 1. If any required permission is missing, some Violet features may not work correctly. You can update permissions by editing the Private App in **Apps > Manage Private Apps**. #### Revoking Access You can revoke Violet's access at any time by deleting the Private App in **Apps > Manage Private Apps**. This will immediately disconnect your store from Violet until a new Private App is created and its Access Token is provided. #### Webhooks Violet automatically registers webhooks on your Shoplazza store during the connection process. These webhooks notify Violet of product and order changes in real time. You do not need to configure webhooks manually. # Shoptet This guide is intended for Shoptet merchants who are connecting their store to Violet. Violet supports two onboarding paths depending on your Shoptet plan: * **Premium** — you will create a Private API Token in your Shoptet administration and provide it to Violet. This enables full product sync, order submission, and webhook-driven updates. * **Standard** — you will provide your store URL and a product feed URL. This enables catalog sync via your store's XML feed. No API token is required. During the Violet Connect onboarding process you will be asked to select which tier you are on, and the form will guide you through the appropriate steps. *Total time for completion is around 5-10 minutes.* *** ## Choosing Your Tier When you select Shoptet in Violet Connect, you will be prompted to choose your plan: * Select **Premium** if you have access to the **Connections › Private API** screen in your Shoptet administration. This is available on Shoptet Premium plans and above. * Select **Standard** if you do not have Private API access. Standard tier uses your store's product feed URL to sync your catalog. *** ## Premium Tier ### Step 1: Creating a Private API Token 1. Sign in to your Shoptet administration and navigate to **Connections › Private API**. 2. Click the **Add** button to create a new token. 3. Enter a **description** for the token (e.g. `Violet integration`) so it is easy to identify later. 4. Submit the form. The new token will appear in the token list, with only the first two and last two characters visible. 5. Click the entry in the list and re-enter your administration password when prompted to reveal the full token. 6. Copy the token value — it will be a 38-60 character alphanumeric string with dashes. You will paste this into Violet in **Step 3**. {% hint style="info" %} Each Shoptet eshop allows up to 10 active Private API Tokens. Use a descriptive label so you can rotate or revoke the Violet token without affecting other integrations. {% endhint %} ### Step 2: Locating Your Eshop URL 1. Your Shoptet eshop URL is the public storefront address that customers use to reach your store (e.g. `https://yourstore.myshoptet.com` or your own custom domain). 2. You can confirm the exact URL in your Shoptet administration under **Settings › Basic settings**, or simply copy it from your browser address bar while viewing the storefront. 3. Have this URL ready — you will paste it into Violet in **Step 3** alongside the token. Violet will normalize the value, so trailing slashes, paths, or mixed casing are fine. ### Step 3: Provide Credentials to Violet 1. In the Violet Connect onboarding tool, select **Shoptet** as your platform, then choose **Premium**. 2. Enter your **Eshop URL** and click **Next**. 3. Paste the **Private API Token** from Step 1 into the **Private API Token** field. 4. Submit the form. Violet will immediately validate the token by calling Shoptet's `GET /api/eshop` endpoint. If the token is valid, you will be redirected to the next step of onboarding; if it is rejected, you will see an error message and can retry with a corrected token. Upon success you will be redirected back to the channel who first sent you to Violet. ### Premium Credential Summary | Credential | Required | Where to find it | Example | | ----------------- | -------- | --------------------------------------------- | -------------------------------------- | | Private API Token | Yes | Shoptet admin › **Connections › Private API** | `1a2b3c4d-5e6f-7890-abcd-ef1234567890` | | Eshop URL | Yes | Shoptet admin › **Settings › Basic settings** | `https://yourstore.myshoptet.com` | *** ## Standard Tier Standard tier is for merchants who do not have Private API access. Instead of an API token, you provide a product feed URL that Violet uses to sync your catalog. ### Step 1: Locating Your Eshop URL 1. Your Shoptet eshop URL is the public storefront address that customers use to reach your store (e.g. `https://yourstore.myshoptet.com` or your own custom domain). 2. You can confirm the exact URL in your Shoptet administration under **Settings › Basic settings**, or simply copy it from your browser address bar while viewing the storefront. ### Step 2: Creating Your Product Feed URL 1. In your Shoptet administration, click the **Connection** menu item and then select **XML Feeds**. 2. On the XML Feeds screen, click the **Add** button to create a new feed. 3. Fill in the following fields: * **Name**: Enter a name that you will easily recognize as the feed created for the channel you are connecting to. * **File name**: Choose a name like `violet_feed` or `{channel}_feed`, where `{channel}` is the name of the channel you are connecting to. * **XML header**: Enter the following code. Replace `{store_url}` with your actual store URL. ```xml Google Product Feed {store_url} Google product feed generated by Shoptet ``` * **XML body**: Enter the following code exactly. ```xml #CODE# #NAME# #DESCRIPTION# #URL# #IMG_URL# #PRICE_VAT# CZK #AVAILABILITY_GOOGLE# #ITEM_TYPE_GOOGLE# #MANUFACTURER# #EAN# #PART_NUMBER# #TAG_G_IDENTIFIER_EXISTS_FALSE__IF_NO_EAN# #COMPLETE_PATH_GT# #IMG_ALT_URL1# #IMG_ALT_URL2# ``` * **XML footer**: Enter the following code exactly. ```xml ``` 4. Click the **Save And Exit** button. {% hint style="warning" %} After saving, check the feed list to make sure your new feed is **active**. If the feed shows a grey circle with an **×** icon, it is inactive. Click the grey **×** icon to activate the feed — it should change to a green circle with a **✓** checkmark. The feed must be active for Violet to read your product catalog. {% endhint %} ### Step 3: Enabling Security and Copying Your Feed URL 1. At the top of the feeds list, click the **Security** tab. 2. Locate the checkbox labeled **Deny access from IP addresses that do not use a security hash**. If this box is not checked, check it now. 3. Click the **Save** button. 4. Click back to the **XML Feeds** tab. 5. Copy the feed URL, including the hash value (e.g. `https://mystore.myshoptet.com/violet_feed.xml?hash=mgljmavJYChOqDasYsRlZGf`). ### Step 4: Provide Details to Violet 1. In the Violet Connect onboarding tool, select **Shoptet** as your platform, then choose **Standard**. 2. Paste your **Store URL** from Step 1 into the **Store URL** field. 3. Paste your **Product Feed URL** from Step 3 into the **Product Feed URL** field. 4. Submit the form. No credential validation is performed for standard tier — Violet will accept the URLs and begin syncing your catalog from the feed. Upon success you will be redirected back to the channel who first sent you to Violet. ### Standard Credential Summary | Field | Required | Where to find it | Example | | ---------------- | -------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- | | Store URL | Yes | Shoptet admin › **Settings › Basic settings** | `https://yourstore.myshoptet.com` | | Product Feed URL | Yes | Shoptet admin › **Connection › XML Feeds** (with hash) | `https://mystore.myshoptet.com/violet_feed.xml?hash=mgljmavJYChOqDasYsRlZGf` | ### Standard Tier Limitations Standard tier provides catalog sync only. The following features are **not available** on the standard tier: * Real-time product updates via webhooks * Order submission (checkout / direct order submission) * Shipping rate calculation * Live inventory tracking If you need these capabilities, consider upgrading to a Shoptet Premium plan and connecting via the Premium tier flow above. *** ## Special Considerations ### Token Security (Premium only) Shoptet's Private API Tokens grant **full read access to all data in your eshop**, including customers and orders. Treat the token like a password: * Never share it outside of the secure Violet onboarding form. * Do not embed it in client-side code, screenshots, or support tickets. * If you suspect the token has been compromised, revoke it immediately (see below) and generate a new one. ### Token Expiration (Premium only) Private API Tokens issued by Shoptet **do not expire**. There is no need to schedule periodic rotation, but you can rotate the token at any time by creating a new one in Shoptet, providing it to Violet, and then deleting the old one. ### Revoking Credentials (Premium only) To revoke the token at any time: 1. Sign in to your Shoptet administration and navigate to **Connections › Private API**. 2. Locate the row for your Violet integration token. 3. Click the red **×** in the **Action** column to delete the token. Once revoked, all subsequent Violet API calls to your store will fail with an authorization error. Generate and provide a new token to restore the integration. ### Alternative: Marketplace Addon Installation For merchants who prefer not to manage tokens manually, Violet also supports installation as a Shoptet **marketplace addon**. When this option is available, you can install Violet directly from the Shoptet Addon Store and authorization is handled automatically via OAuth — no token generation required. Reach out to Violet support to check availability of the addon for your region. # Lightspeed eCom This guide is intended for Lightspeed eCom merchants who are connecting their store to Violet. During this process, you will create API credentials in your Lightspeed eCom back office and then provide them to Violet through the Violet Connect onboarding tool. You will retain full control of the created credentials and can revoke them at any time from within your Lightspeed back office. *Total time for completion is around 5 minutes.* ## Step 1: Creating API Credentials 1. Sign in to your Lightspeed eCom back office. 2. Navigate to **Settings › Web extras › API Keys** (or **Apps › API Keys**, depending on your back office version). 3. Click **Add API Key**. 4. Enter a description for the key (e.g. `Violet integration`) so it is easy to identify later. 5. Once created, you will be shown an **API Key** and an **API Secret**. Copy both values — you will paste them into Violet in **Step 3**. {% hint style="warning" %} The API Secret is only shown once at creation time. If you lose it, you will need to delete the key and create a new one. {% endhint %} ## Step 2: Locating Your Store URL 1. Your Lightspeed eCom API base URL is typically in the format `https://api.shoplightspeed.com/en/` or your custom storefront domain. 2. You can confirm the URL by checking the address bar in your Lightspeed back office, or by navigating to **Settings › General › Domains** to see your configured domains. 3. Have this URL ready — you will paste it into Violet in **Step 3**. Violet will normalize the value, so trailing slashes or mixed casing are fine. ## Step 3: Provide Credentials to Violet 1. In the Violet Connect onboarding tool, select **Lightspeed** as your platform. 2. Enter your **Store URL** from Step 2 and click **Next**. 3. Paste the **API Key** from Step 1 into the **API Key** field. 4. Paste the **API Secret** from Step 1 into the **API Secret** field. 5. Submit the form. Violet will immediately validate the credentials by calling the Lightspeed Account endpoint. If the credentials are valid, you will be redirected to the next step of onboarding; if they are rejected, you will see an error message and can retry with corrected values. Upon success you will be redirected back to the channel who first sent you to Violet. ## Credential Summary | Credential | Required | Where to find it | Example | | ---------- | -------- | ------------------------------------------------ | ------------------------------------ | | API Key | Yes | Lightspeed back office › **Settings › API Keys** | `abc123def456...` | | API Secret | Yes | Shown once at API key creation time | `xyz789ghi012...` | | Store URL | Yes | Lightspeed back office › **Settings › Domains** | `https://api.shoplightspeed.com/en/` | ## Special Considerations ### Credential Security Lightspeed API credentials grant access to your store data including products, orders, and customers. Treat them like passwords: * Never share them outside of the secure Violet onboarding form. * Do not embed them in client-side code, screenshots, or support tickets. * If you suspect the credentials have been compromised, revoke them immediately (see below) and generate new ones. ### Credential Expiration Lightspeed eCom API keys **do not expire**. There is no need to schedule periodic rotation, but you can rotate credentials at any time by creating a new key pair in Lightspeed, providing it to Violet, and then deleting the old one. ### Revoking Credentials To revoke your API credentials at any time: 1. Sign in to your Lightspeed eCom back office. 2. Navigate to **Settings › Web extras › API Keys**. 3. Locate the row for your Violet integration key. 4. Delete the key. Once revoked, all subsequent Violet API calls to your store will fail with an authorization error. Generate and provide new credentials to restore the integration. # Medusa This guide is intended for Medusa v2 merchants who are connecting their self-hosted Medusa store to Violet. During this process, the merchant will create a Secret API Key in the Medusa admin dashboard and then provide the generated credentials to Violet through the Violet Connect onboarding tool. The merchant will retain full control of the created credentials and can revoke them at any time from within their Medusa admin dashboard. *Total time for completion is around 5 minutes.* ## Step 1: Creating the Admin API Token (Secret API Key) The Admin API Token is **required** to connect your Medusa store to Violet. It allows Violet to sync your products, manage orders, and access store information on your behalf. 1. Log in to your Medusa admin dashboard. 2. Navigate to **Settings > Secret API Keys**. 3. Click **"Create Secret API Key"**. 4. Enter a title for the key (e.g., "Violet Integration"). 5. Click **Create** and copy the generated secret key. {% hint style="warning" %} **Important:** The full secret key is only displayed once at creation time. Copy and save it securely before closing the dialog. If you lose the key, you will need to create a new one. {% endhint %} {% hint style="info" %} Medusa Secret API Keys provide full admin access and are not granularly scoped. Violet uses this key for product synchronization (`read_products`), order management (`read_orders`, `write_orders`), and store profile access. {% endhint %} ## Step 2: Locating the Store Publishable API Key (Optional) The Store Publishable API Key enables an optimized cart-based checkout flow through Medusa's storefront API, including real-time cart calculations with shipping rates and tax. If not provided, Violet will use an alternative order creation method. 1. In your Medusa admin dashboard, navigate to **Settings > API Key Management** (or **Settings > Publishable API Keys**, depending on your Medusa version). 2. Locate or create a publishable API key for your storefront. 3. Copy the publishable key and keep it available for Step 4. {% hint style="info" %} This key is optional. If you are unsure whether you need it, you can skip this step and add it later. {% endhint %} ## Step 3: Configuring Webhooks (Optional) Webhooks allow your Medusa store to notify Violet of product and order changes in real time. Without webhooks, Violet will still synchronize data, but changes may not appear immediately. Medusa v2 does not provide a built-in admin UI for webhook configuration. Webhooks are configured server-side using a subscriber or notification module in your Medusa project. 1. In your Medusa project codebase, create or update a subscriber that sends HTTP POST requests to the Violet webhook endpoint: ``` https://api.violet.io/v1/sync/external/events/medusa?merchant_id={YOUR_MERCHANT_ID} ``` Your `merchant_id` will be provided after you complete the connection in Step 4. 2. Configure the subscriber to send the following event types: * `product.created` * `product.updated` * `product.deleted` * `order.placed` * `order.updated` * `order.canceled` 3. Include the following headers in each webhook request: * `x-medusa-event`: The event name (e.g., `product.updated`) * `x-medusa-signature`: HMAC-SHA256 signature of the request body using a shared secret {% hint style="info" %} If you need help configuring webhooks, contact Violet support or refer to the [Medusa Subscribers documentation](https://docs.medusajs.com/resources/references/medusa-workflows/subscribers). {% endhint %} ## Step 4: Provide Credentials to Violet Once you have your credentials, return to the Violet Connect onboarding tool and enter the following: 1. When prompted for your store URL, enter the full URL of your Medusa server including the protocol (e.g., `https://store.example.com`). Do not include a trailing slash. 2. Enter your **Admin API Token** (Secret API Key) obtained in Step 1 in the "Admin API Token" field. 3. *(Optional)* Enter your **Store Publishable Key** obtained in Step 2 in the "Store Publishable Key" field. Once entered, click the **Connect** button to validate the credentials and complete the connection between your store and Violet. Violet will verify your Admin API Token by connecting to your Medusa server — if the token is invalid or the server cannot be reached, you will receive an error message. If the credentials are invalid, check for: * Spaces or other copy/paste errors in the API token * The store URL is correct and accessible from the internet * The Secret API Key has not been revoked Upon success you will be redirected back to the channel who first sent you to Violet. *** ### Credential Summary | Credential | Required | Where to Find | | -------------------------------- | -------- | ----------------------------------------------------------------- | | Store URL | Yes | Your Medusa server's base URL (e.g., `https://store.example.com`) | | Admin API Token (Secret API Key) | Yes | Medusa admin > Settings > Secret API Keys > Create Secret API Key | | Store Publishable Key | No | Medusa admin > Settings > API Key Management (Publishable) | *** ### Special Considerations #### Self-Hosted Platform Unlike SaaS platforms, Medusa is self-hosted. This means: * Your store URL is unique to your deployment — there is no standard domain like `.myshopify.com` * Your Medusa server must be accessible from the internet for Violet to connect * Ensure your server's firewall or reverse proxy allows inbound connections from Violet's IP ranges #### Secret API Key Security Medusa Secret API Keys provide full admin access and do not expire. Treat them like passwords: * Do not share them in plain text over email or chat * If you suspect a key has been compromised, revoke it immediately in **Settings > Secret API Keys** and create a new one * Creating a new key and updating it in Violet Connect will restore the connection #### Revoking Credentials You can revoke your Secret API Key at any time by navigating to **Settings > Secret API Keys** in your Medusa admin dashboard and deleting the key. This will immediately disconnect your store from Violet until a new key is provided. # Miva Merchant This guide is intended for Miva merchants who are connecting their store to Violet. During this process, you will create a new API Token in your Miva admin panel and then provide the generated credentials to Violet through the Violet Connect onboarding tool. You will retain full control of the created API Token and can revoke it at any time from within your Miva admin panel. *Total time for completion is around 5-10 minutes.* ## Prerequisites * Your store must be running **Miva 9.12.00 or greater** (with engine 5.32+). * You must have **administrator access** to the Miva admin panel with permission to manage API Tokens under **Settings > User Management > API Tokens**. ## Step 1: Creating an API Token 1. Sign in to your Miva admin panel. 2. Navigate to **Settings > User Management > API Tokens**. 3. Click the button to **add a new API Token**. This will open the **Edit API Token** modal. 4. On the **Settings** tab: * In the **Name** field, enter a name for the token (e.g. `Violet`) so it is easy to identify later. * In the **Allowed IP Address(es)** field, enter the following three IP addresses required for production use: `44.235.99.169`, `44.236.104.65`, `44.236.6.9`. For testing and non-production stores, you may enter `0.0.0.0/0` to allow any IP. * Under **Signature**, select **Require Signature with Key** and click **Generate** to create a signing key. 5. Switch to the **Groups** tab and enable the following three Role-Based Groups. These are required for Violet to sync your products, process orders, and manage customers: * **Customer Service & Sales** — Create and modify orders, manage customer accounts * **Order Processing & Fulfillment** — View and modify existing orders * **Product Management** — Manage products and categories 6. Click **Save** to create the token. 7. Before closing the modal, copy the following three values and keep them available for Step 3 of this guide: * **Access Token** — Your API authentication token. * **Signing Key** — The Base64-encoded key generated in the Signature section, used for HMAC-SHA256 authentication. * **Endpoint URL** — Click **Copy** next to the Endpoint URL field. This is your Store URL and will be needed in Step 3. {% hint style="warning" %} **Important:** You must copy the Access Token, Signing Key, and Endpoint URL before closing this modal. Once closed, the Signing Key will be hidden and you will need to generate a new one if it was not captured. {% endhint %} ## Step 2: Locating Your Store Code 1. In your Miva admin panel, navigate to **Settings > Store Settings**. 2. Under the **Identification** section on the **Store Details** tab, locate the **Store Code** field. This is the unique identifier for your store within Miva. ## Step 3: Provide Credentials to Violet Once you have your **Access Token**, **Signing Key**, **Endpoint URL**, and **Store Code**, it is time to return to the Violet Connect onboarding tool and enter the credentials: 1. In Violet Connect, select **Miva** as your platform. 2. When prompted for your **Store URL**, enter the **Endpoint URL** you copied from the API Token modal in Step 1. Click **Next**. 3. Enter your **Store Code** from Step 2 in the **Store Code** field. 4. Enter your **Access Token** from Step 1 in the **API Key** field. 5. Enter your **Signing Key** from Step 1 in the **Signing Key** field. 6. Click **Next**. Violet will immediately validate the credentials by calling the Miva Store API. If the credentials are valid, you will be redirected to the next step of onboarding; if they are rejected, you will see an error message and can retry with corrected values. Once entered, Violet will validate the credentials and complete the connection between your store and Violet. If the credentials are invalid, 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. ## Credential Summary | Credential | Required | Where to find it | Example | | ------------ | -------- | --------------------------------------------------------------- | ---------------------------------------- | | Endpoint URL | Yes | API Token modal > **Settings** tab > **Endpoint URL** | `https://www.yourstore.com/mm5/json.mvc` | | Access Token | Yes | API Token modal > **Settings** tab > **Access Token** | `a1b2c3d4e5f6...` | | Signing Key | Yes | API Token modal > **Settings** tab > **Signature** section | `aGVsbG93b3JsZA==` (Base64 encoded) | | Store Code | Yes | Miva admin > **Settings > Store Settings** > **Identification** | `MYSTORE` | ## Special Considerations ### API Token Permissions Miva API Tokens have permissions configured via Role-Based Groups in the admin panel. The token you create for Violet must have the **Customer Service & Sales**, **Order Processing & Fulfillment**, and **Product Management** groups enabled. If Violet reports authorization errors after connecting, verify that all three groups are enabled on the token's **Groups** tab. ### Credential Security Miva API credentials grant access to your store data including products, orders, and customers. Treat them like passwords: * Never share them outside of the secure Violet onboarding form. * Do not embed them in client-side code, screenshots, or support tickets. * If you suspect the credentials have been compromised, revoke them immediately (see below) and generate new ones. ### Token Expiration Miva API Tokens **do not expire**. There is no need to schedule periodic rotation, but you can rotate credentials at any time by creating a new token in Miva, providing it to Violet, and then deleting the old one. ### Revoking Credentials To revoke your API credentials at any time: 1. Sign in to your Miva admin panel. 2. Navigate to **Settings > User Management > API Tokens**. 3. Locate the row for your Violet integration token. 4. Delete the token. Once revoked, all subsequent Violet API calls to your store will fail with an authorization error. Generate and provide new credentials to restore the integration. ### Webhook Configuration Miva does not support automated webhook registration through the API. To receive real-time notifications for product and order changes, you will need to configure notifications manually in your Miva admin panel: 1. Navigate to **Utilities > Notifications** in your Miva admin panel. 2. Add notification entries pointing to the Violet webhook gateway for the following topics: * `order.created` * `order.updated` * `product.created` * `product.updated` 3. Your channel partner or Violet support can provide the exact webhook URL to use. {% hint style="info" %} Webhook configuration is optional. Without it, Violet will still sync your catalog and orders, but updates will rely on periodic polling rather than real-time notifications. {% endhint %} # Oracle Commerce Cloud This guide is intended for Oracle Commerce Cloud (OCC) merchants who are connecting their store to Violet. During this process, you will register a server-side integration in your OCC admin dashboard and then provide the generated application key to Violet through the Violet Connect onboarding tool. You will retain full control of the registered integration and can remove it at any time from within your OCC admin. *Total time for completion is around 5 minutes.* ## Prerequisites * An active Oracle Commerce Cloud instance with admin access. * Permission to register server-side integrations in the OCC admin UI. ## Step 1: Registering a Server-Side Integration 1. Sign in to the **OCC Admin UI** for your store (typically at `https://your-store.oracleoutsourcing.com/occs-admin`). 2. Navigate to **Settings > Integrations** (or **Settings > Web APIs**, depending on your OCC version). 3. Click **Register a New Integration** (or **Add Application**). 4. Enter a **Name** for the integration that will help you identify it later (e.g. `Violet` or the name of the channel you are connecting to). 5. Select **Server** as the integration type. This generates a JWT application key for server-to-server communication. 6. Once saved, the **Application Key** will be displayed. Copy this value and keep it available for Step 3 of this guide. {% hint style="warning" %} The Application Key may only be fully visible once at creation time, depending on your OCC version. If you lose it, you may need to delete the integration and create a new one. {% endhint %} ## Step 2: Locating Your Store URL 1. Your OCC store URL is the hostname of your Oracle Commerce Cloud instance (e.g. `https://mystore.oracle.com` or `https://your-store.oracleoutsourcing.com`). 2. You can confirm this by checking the address bar in your OCC admin dashboard. 3. Have this URL ready — you will paste it into Violet in **Step 3**. Violet will normalize the value, so trailing slashes or mixed casing are fine. ## Step 3: Provide Credentials to Violet 1. In the Violet Connect onboarding tool, select **Oracle Commerce Cloud** as your platform. 2. Enter your **Store URL** from Step 2 and click **Next**. 3. Paste the **Application Key** from Step 1 into the **Application Key** field. 4. Submit the form. Violet will immediately validate the credentials by authenticating against your OCC instance. If the credentials are valid, you will be redirected to the next step of onboarding; if they are rejected, you will see an error message and can retry with corrected values. Upon success you will be redirected back to the channel who first sent you to Violet. ## Credential Summary | Credential | Required | Where to find it | Example | | --------------- | -------- | ------------------------------------------------------------ | ---------------------------- | | Application Key | Yes | OCC Admin UI > **Settings > Integrations** (server-side key) | `eyJhbGciOiJSUzI1NiIs...` | | Store URL | Yes | OCC Admin dashboard address bar | `https://mystore.oracle.com` | ## How Violet Uses Your Credentials Violet uses the Application Key to authenticate with your OCC instance via the `/ccadmin/v1/login` endpoint using the `client_credentials` grant type. This returns a short-lived access token (valid for 5 minutes) that Violet uses to: * **Read your product catalog** to make your items available for purchase through connected channels. * **Read and create orders** when a purchase is made through a connected channel. * **Read inventory** to ensure accurate availability information. * **Read shipping methods** to present shipping options during checkout. Access tokens are automatically refreshed as needed. Your Application Key itself is stored securely and encrypted at rest. ## Special Considerations ### Credential Security Your OCC Application Key grants server-level access to your store's Admin API, including products, orders, and customer data. Treat it like a password: * Never share it outside of the secure Violet onboarding form. * Do not embed it in client-side code, screenshots, or support tickets. * If you suspect the Application Key has been compromised, revoke it immediately (see below) and generate a new one. ### Token Expiration OCC access tokens expire after **5 minutes**. Violet handles token refresh automatically in the background — no action is required on your part. The underlying Application Key does not expire unless you revoke it. ### Revoking Credentials To revoke your credentials at any time: 1. Sign in to the **OCC Admin UI**. 2. Navigate to **Settings > Integrations**. 3. Locate the integration you created for Violet. 4. Delete or deactivate the integration. Once revoked, all subsequent Violet API calls to your store will fail with an authorization error. Register a new integration and provide the new Application Key to Violet to restore the connection. ### Permissions OCC effective permissions are derived from the role membership assigned to the integration at registration time, not from per-call requested scopes. Ensure that the integration has sufficient permissions to read products, orders, inventory, and shipping methods. If in doubt, consult your OCC administrator or Oracle's documentation on server-side integration roles. # SAP Commerce Cloud This guide is intended for SAP Commerce Cloud (formerly Hybris) merchants who are connecting their store to Violet. During this process, you will create a dedicated OAuth client in your SAP Commerce Cloud Backoffice and then provide the generated credentials to Violet through the Violet Connect onboarding tool. You will retain full control of the OAuth client and can revoke it at any time from within your Backoffice. *Total time for completion is around 10 minutes.* ## Prerequisites * An active SAP Commerce Cloud instance with Backoffice admin access. * Permission to create OAuth clients via Backoffice or ImpEx. * Your OCC v2 storefront API must be enabled and accessible (typically at `https://api./occ/v2`). ## Step 1: Create an OAuth Client Violet authenticates with your SAP Commerce Cloud instance using the OAuth 2.0 `client_credentials` grant. You need to create a dedicated OAuth client with the correct role and scope. ### Option A: Via Backoffice 1. Sign in to your **SAP Commerce Cloud Backoffice**. 2. Navigate to **System > OAuth > OAuth Clients**. 3. Click **Create** to add a new OAuth client. 4. Configure the following fields: * **Client ID**: A unique identifier (e.g. `violet-integration`). * **Client Secret**: A strong, randomly generated secret. * **Authorities**: Set to `ROLE_TRUSTED_CLIENT`. * **Authorized Grant Types**: Set to `client_credentials`. * **Scopes**: Set to `extended`. 5. Save the client. ### Option B: Via ImpEx If you prefer to create the OAuth client using ImpEx, import the following script in your HAC (Hybris Admin Console) or via a deployment hook: ```impex INSERT_UPDATE OAuthClientDetails ; clientId[unique=true] ; clientSecret ; authorities ; authorizedGrantTypes ; scope ; violet-integration ; ; ROLE_TRUSTED_CLIENT ; client_credentials ; extended ``` {% hint style="warning" %} Replace `` with a strong secret. The client secret is stored hashed in SAP CC — you will not be able to retrieve it later. Keep a copy for Step 4 of this guide. {% endhint %} {% hint style="info" %} **Why `ROLE_TRUSTED_CLIENT`?** Violet needs to create carts and place orders on behalf of customers via the `/users/{userId}/carts` and `/users/{userId}/orders` endpoints. These endpoints require trusted-client authority. A standard `ROLE_CLIENT` will authenticate successfully but fail at checkout time. {% endhint %} ## Step 2: Identify Your Base Site ID SAP Commerce Cloud organizes storefronts into **base sites** (e.g. `electronics`, `apparel-uk`, `powertools`). Violet needs to know which base site to operate against. 1. In Backoffice, navigate to **WCMS > Website** or **Base Commerce > Base Site**. 2. Locate the base site that corresponds to the storefront you want to connect to Violet. 3. Copy the **Site ID** (UID) — for example, `electronics` or `apparel-uk`. Alternatively, you can list your base sites by calling your OCC API directly: ``` GET https://api./occ/v2/basesites ``` ## Step 3: Locate Your OCC API Base URL Your OCC v2 base URL is the root endpoint for all storefront API calls. It typically follows one of these patterns: * `https://api./occ/v2` * `https:///occ/v2` * `https:///rest/v2` You can confirm the correct URL by calling the base sites endpoint from Step 2. If it returns a JSON response with your base sites, you have the correct URL. ## Step 4: Provide Credentials to Violet 1. In the Violet Connect onboarding tool, select **SAP Commerce Cloud** as your platform. 2. Enter the following credentials: | Field | What to enter | Example | | ----------------- | ----------------------------------- | -------------------------------- | | **Store URL** | Your OCC v2 base URL from Step 3 | `https://api.mystore.com/occ/v2` | | **Client ID** | The OAuth client ID from Step 1 | `violet-integration` | | **Client Secret** | The OAuth client secret from Step 1 | *(not displayed)* | | **Base Site ID** | The base site UID from Step 2 | `electronics` | 3. Submit the form. Violet will immediately validate your credentials by: * Requesting an OAuth token from your SAP CC instance. * Confirming that your base site ID exists. * Verifying that the OAuth client has `ROLE_TRUSTED_CLIENT` authority. If any step fails, you will see an error message and can retry with corrected values. Upon success, you will be redirected back to the channel that sent you to Violet. ## Credential Summary | Credential | Required | Where to find it | Example | | ------------- | -------- | ------------------------------------------------- | -------------------------------- | | Store URL | Yes | OCC API base URL | `https://api.mystore.com/occ/v2` | | Client ID | Yes | Backoffice > OAuth Clients (or your ImpEx script) | `violet-integration` | | Client Secret | Yes | Set at OAuth client creation time | *(not displayed)* | | Base Site ID | Yes | Backoffice > Base Sites, or `GET /basesites` | `electronics` | ## How Violet Uses Your Credentials Violet uses the Client ID and Client Secret to request an OAuth access token via the `client_credentials` grant against your instance's `/authorizationserver/oauth/token` endpoint. This token is used to: * **Read your product catalog** to make your items available for purchase through connected channels. * **Create and manage carts** when a customer begins checkout through a connected channel. * **Place orders** by walking the OCC cart pipeline (delivery address, shipping mode, payment, and order placement). * **Read shipping methods** to present delivery options during checkout. * **Read inventory and pricing** to ensure accurate availability and pricing information. Access tokens are automatically refreshed before expiry. Your Client ID and Client Secret are stored securely and encrypted at rest. ## Special Considerations ### Credential Security Your OAuth client credentials grant server-level access to your SAP Commerce Cloud storefront API. Treat them like a password: * Never share them outside of the secure Violet onboarding form. * Do not embed them in client-side code, screenshots, or support tickets. * If you suspect the credentials have been compromised, revoke them immediately (see below) and create a new OAuth client. ### Token Expiration SAP Commerce Cloud access tokens typically expire after **12 hours** (configurable per instance). Violet handles token refresh automatically in the background — no action is required on your part. The underlying OAuth client credentials do not expire unless you revoke them. ### Revoking Credentials To revoke your credentials at any time: 1. Sign in to your **SAP Commerce Cloud Backoffice**. 2. Navigate to **System > OAuth > OAuth Clients**. 3. Locate the OAuth client you created for Violet (e.g. `violet-integration`). 4. Delete or deactivate the client. Once revoked, all subsequent Violet API calls to your store will fail with an authorization error. Create a new OAuth client and provide the new credentials to Violet to restore the connection. ### Webhooks (Optional) SAP Commerce Cloud does not push webhooks by default. If your instance has the optional **Webhook Services** extension installed, Violet will attempt to register webhooks automatically for real-time sync. If the extension is not present, you can configure outbound webhooks manually in Backoffice pointing at Violet's webhook endpoint. Contact your Violet representative for the webhook URL and setup instructions. ### Permissions The OAuth client's effective permissions are controlled by its `authorities` and `scope` configuration. Ensure the client has: * **`ROLE_TRUSTED_CLIENT`** — required for cart and order operations on behalf of customers. * **`scope=extended`** — required for write access to carts, orders, and payment details. If the OAuth client is configured with only `ROLE_CLIENT`, authentication will succeed but order-related operations will fail with 401/403 errors. # Centra This guide is intended for Centra merchants who are connecting their store to Violet. During this process, the merchant will create API credentials in their Centra AMS dashboard and then provide them to Violet through the Violet Connect onboarding tool. The merchant will retain full control of the created credentials and can revoke them at any time from within their Centra AMS dashboard. *Total time for completion is around 5-10 minutes.* ## Step 1: Creating an Integration API Token The Integration API Token is **required** to connect your Centra store to Violet. It allows Violet to sync your products and manage orders on your behalf. 1. Within your Centra AMS dashboard, navigate to **System > Api Tokens**. 2. Click **"+ Integration API TOKEN"**. 3. Enter a description for the token (e.g., "Violet integration"). 4. Select the required permissions — at minimum: **Products**, **Orders**, **Customers**, and **Markets**. 5. Set the token expiration. The default is 30 days; for production use, set a longer expiration or no expiration. 6. Click **Create** and copy the generated token. *Keep this token available for Step 4 of this guide.* {% hint style="warning" %} Use minimal permissions in production. You can monitor `extensions.permissionsUsed` in API responses during testing to identify exactly which permissions are needed. {% endhint %} For more details, see [Authorization | centra.dev](https://centra.dev/docs/integration-api/authorization). ## Step 2: Locating Your Checkout API Shared Secret (Optional) The Checkout API Shared Secret enables real-time cart calculations including shipping rates and tax. If not provided, Violet will fall back to local cart calculation. 1. In your Centra AMS dashboard, navigate to the **Checkout API plugin** in the plugin list. 2. Open the plugin settings. 3. Locate the **"Shared Secret"** field. 4. Copy the shared secret value and keep it available for Step 4 of this guide. For more details, see [Storefront API Plugin Setup | centra.dev](https://centra.dev/storefront-api/plugin-setup). ## Step 3: Configuring Webhooks (Optional) Webhooks allow Centra to notify Violet of changes to your products, orders, and other data in real time. The Webhook Endpoint Secret ensures these notifications are authentic. 1. In your Centra AMS dashboard, navigate to the **Webhook plugin** in the plugin list. 2. Set the **Webhook URL** to the Violet webhook endpoint provided during onboarding. 3. Enter or generate an **Endpoint Secret** and copy the value for Step 4 of this guide. 4. Configure the event types to send: * **Integration API events:** Order, Shipment, Customer, Account, Check First, Allocation Request, Return * **Storefront API events:** Display Items, Categories, Pricelists, Markets, Collections, Brands, Languages, Campaign Sites, Affiliates, Brick and Mortars 5. Recommended settings: Max events = 10, Timeout = 5s, Retries = 2. For more details, see [Centra Webhooks | centra.dev](https://centra.dev/docs/services/centra-webhooks). ## Step 4: Provide Credentials to Violet Once you have your credentials, return to the Violet Connect onboarding tool and enter the following: 1. When prompted for your store URL, enter your Centra instance URL including the protocol (e.g., `https://yourbrand.centra.com`). 2. Enter your **Integration API Token** obtained in Step 1 in the "Integration API Token" field. 3. *(Optional)* Enter your **Checkout API Shared Secret** obtained in Step 2 in the "Checkout API Shared Secret" field. 4. *(Optional)* Enter your **Webhook Endpoint Secret** obtained in Step 3 in the "Webhook Endpoint Secret" field. 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. *** ## Credential Summary | Credential | Required | Where to Find | | -------------------------- | -------- | ---------------------------------------------------------------- | | Store URL | Yes | Your Centra AMS admin URL (e.g., `https://yourbrand.centra.com`) | | Integration API Token | Yes | System > Api Tokens > + Integration API TOKEN | | Checkout API Shared Secret | No | Checkout API plugin settings > Shared Secret | | Webhook Endpoint Secret | No | Webhook plugin settings > Endpoint Secret | *** ## Special Considerations ### Token Expiration Integration API tokens default to a 30-day expiration. If your token expires, the connection to Violet will stop working until a new token is provided. For production use, we recommend setting a longer expiration or no expiration when creating the token. ### Revoking Credentials You can revoke your Integration API token at any time by navigating to **System > Api Tokens**, selecting the token, and clicking **Revoke**. This will immediately disconnect your store from Violet. # Cartpanda This guide is intended for Cartpanda merchants who are connecting their store to Violet. During this process, the merchant will locate their API Token in the Cartpanda dashboard and then provide it to Violet through the Violet Connect onboarding tool. The merchant will retain full control of the created credentials and can regenerate or revoke them at any time from within their Cartpanda dashboard. *Total time for completion is around 3 minutes.* ## Step 1: Locating Your API Token The API Token is **required** to connect your Cartpanda store to Violet. It allows Violet to sync your products, manage orders, and access store information on your behalf. 1. Log in to your Cartpanda dashboard. 2. Click your **avatar** (profile icon) in the top-right corner of the dashboard. 3. Navigate to your **Profile** or **Account Settings**. 4. Locate the **API Token** section. 5. Copy the API token value. {% hint style="warning" %} **Important:** Keep your API token secure. Do not share it in plain text over email or chat. If you suspect it has been compromised, regenerate it immediately from your Cartpanda dashboard. {% endhint %} ## Step 2: Locating Your Webhook Signing Secret (Optional) The Webhook Signing Secret enables secure verification of real-time event notifications from your Cartpanda store. If not provided, Violet will use your API Token for webhook verification instead. 1. In your Cartpanda dashboard, navigate to your **Webhook** or **Integrations** settings. 2. If you have configured a webhook signing secret, copy it and keep it available for Step 3. {% hint style="info" %} This secret is optional. If you have not configured a custom webhook signing secret in your Cartpanda dashboard, you can safely skip this step. {% endhint %} ## Step 3: Provide Credentials to Violet Once you have your API Token, return to the Violet Connect onboarding tool and enter the following: 1. When prompted for your store URL, enter the full URL of your Cartpanda store including the protocol. Example: `https://mystore.mycartpanda.com`. 2. Enter your **API Token** obtained in Step 1 in the "API Token" field. 3. *(Optional)* Enter your **Webhook Signing Secret** obtained in Step 2 in the "Webhook Signing Secret" field. Once entered, click the **Connect** button to validate the credentials and complete the connection between your store and Violet. Violet will verify your API Token by connecting to your Cartpanda store — if the token is invalid, you will receive an error message. If the credentials are invalid, check for: * Spaces or other copy/paste errors in the API token * The store URL is correct (e.g., `https://mystore.mycartpanda.com`) * The API token has not been revoked or regenerated Upon success you will be redirected back to the channel who first sent you to Violet. *** ### Credential Summary | Credential | Required | Where to Find | | ---------------------- | -------- | ------------------------------------------------------------------ | | Store URL | Yes | Your Cartpanda store URL (e.g., `https://mystore.mycartpanda.com`) | | API Token | Yes | Cartpanda dashboard > Avatar > Profile / Account Settings | | Webhook Signing Secret | No | Cartpanda dashboard > Webhook / Integrations settings | *** ### Special Considerations #### Default Currency Cartpanda stores default to BRL (Brazilian Real). Ensure your Violet channel is configured to handle BRL if applicable. #### Revoking Credentials You can regenerate or revoke your API Token at any time from your Cartpanda dashboard profile settings. Revoking the token will immediately disconnect your store from Violet until a new token is provided. # Catalog Feeds The Feeds API lets you upload, manage, and monitor product catalog feeds. Feeds are processed asynchronously — after you upload a feed file, it is validated, parsed, and transformed into standardized product offers. **Base URL:** `https://api.violet.io` ## Authentication All requests require a merchant API key passed as a Bearer token in the `Authorization` header. ``` Authorization: Bearer msk_{merchant_id}{uuid} ``` API keys follow the pattern `msk_` + your numeric merchant ID + a 32-character UUID. For example, if your merchant ID is `12345`: ``` Authorization: Bearer msk_12345abc11094a44800d84017c593e22 ``` The service extracts your merchant ID from the key automatically. You do not need to pass it separately. ## Endpoints | Method | Path | Description | | ------ | -------------------- | -------------------------------------------------------------------- | | `POST` | `/v1/feeds` | [Upload a product catalog feed](/feeds/feeds-overview/upload-feed) | | `GET` | `/v1/feeds/{feedId}` | [Get details for a specific feed](/feeds/feeds-overview/get-feed) | | `GET` | `/v1/feeds` | [List all feeds for your merchant](/feeds/feeds-overview/list-feeds) | ## Feed Statuses A feed progresses through these statuses during its lifecycle: | Status | Description | | ------------ | ------------------------------------------------------------------------------ | | `PENDING` | The feed has been uploaded and is waiting for processing to start. | | `PROCESSING` | The feed is currently being processed (parsed, validated, transformed). | | `ACTIVE` | Processing completed successfully. Products are available. | | `ERROR` | Processing failed. Check the `errors` array on the feed details for specifics. | ## Error Response Format All error responses follow the same structure: ```json { "code": "ERROR_CODE", "message": "Human-readable description of what went wrong", "timestamp": "2024-03-15T10:30:00Z" } ``` | Field | Type | Description | | ----------- | ----------------- | --------------------------------- | | `code` | string | Machine-readable error code. | | `message` | string | Human-readable error description. | | `timestamp` | string (ISO 8601) | When the error occurred. | ### HTTP Status Codes | Status | Meaning | | --------------------------- | ---------------------------------------------------- | | `200 OK` | Request succeeded. | | `202 Accepted` | Request accepted; processing started asynchronously. | | `400 Bad Request` | Invalid parameters or validation failure. | | `401 Unauthorized` | Invalid API credential. | | `403 Forbidden` | Attempting to access an unpermitted resource. | | `404 Not Found` | Feed not found or not accessible for your merchant. | | `413 Payload Too Large` | File exceeds the 2 GB size limit. | | `500 Internal Server Error` | Unexpected server error. | # Managing API Credentials This guide walks you through how to find, create, and manage your API credentials in the Violet Merchant Dashboard. ## Finding the API Credentials Page 1. Log in to your [**Merchant Dashboard**](https://merchant.violet.io). 2. Click your **name** in the bottom-left corner of the sidebar to open your profile menu. 3. Click **Settings**. 4. In the settings sidebar on the left, look under the **Merchant** heading and click **API Credentials**. You are now on the API Credentials page, where you can generate and manage your API keys for feed uploads and integration. *** ## Generating Your First API Key If you have not yet created an API key, you will see a message that reads "No Active API Key Generated." 1. Click the **Generate New API Key** button. 2. A confirmation dialog will appear reminding you to treat your API key like a password. Click **Generate Key** to proceed. 3. Wait a few seconds while your key is generated. 4. Your new API key will be displayed on screen. **This is the only time the full key will be shown.** Click **Copy** to copy it to your clipboard. 5. Store the key in a secure location (for example, a password manager or secrets vault) before navigating away from the page. > **Important:** If you leave or refresh the page without copying your key, you will not be able to view the full key again. You would need to rotate your key to generate a new one. *** ## Viewing Your Current API Key Once you have an active API key, the API Credentials page displays a **Current API Key** card with the following details: * **Key value** (masked for security after the initial generation) * **Created Date** -- when the key was generated * **Last Used** -- when the key was last used, or "Never" if it hasn't been used yet * **Version** -- the version number of your key * **Status** -- the current state of your key (e.g., ACTIVE) *** ## Rotating Your API Key If you need a new key -- for example, if your current key may have been exposed -- you can rotate it. Rotation creates a new key while keeping the old one active for a limited grace period so you have time to update your integrations. 1. On the API Credentials page, click the **Rotate Key** button on your current key card. 2. Read the confirmation message, then click **Confirm & Rotate**. 3. Wait a few seconds while the new key is generated. 4. Your new API key will be displayed. Click **Copy** to copy it, and store it securely. 5. Your old key will appear in a separate **Rotated API Key** card below, showing how much time remains in the grace period (e.g., "Expires in: 2d 5h remaining"). 6. Update your integrations to use the new key before the grace period ends. Once the grace period expires, the old key will stop working automatically. > **Note:** You cannot rotate your key while a previous rotation is still in its grace period. If you need to immediately stop an old key from working, revoke it first. *** ## Revoking an API Key Revoking a key **immediately and permanently** disables it. Use this if a key has been compromised or is no longer needed. 1. On the API Credentials page, click the **Revoke Key** button on the key you want to revoke. You can revoke either your current key or an old key that is still in its grace period. 2. A confirmation dialog will appear warning you that this action cannot be undone. 3. Type **REVOKE** in the confirmation field. 4. Click the **Revoke Key** button to confirm. 5. Wait a few seconds while the key is revoked. After revocation, any system using that key will immediately lose access. If you revoke your only active key, the page will return to the initial state where you can generate a new one. > **Warning:** Revoking a key is irreversible. Make sure any systems relying on the key have been updated before you proceed. *** ## Quick Reference | Action | When to use it | | ------------ | ------------------------------------------------------------- | | **Generate** | You don't have an active key and need to create one | | **Rotate** | You want a new key but need time to migrate your integrations | | **Revoke** | You need to immediately disable a key | *** ## Frequently Asked Questions **Can I have more than one active key at the same time?** Only during a rotation grace period. When you rotate, both the new key and the old key will work until the grace period ends or you revoke the old key. **What happens if I lose my API key?** The full key is only displayed once, at the time it is generated or rotated. If you lose it, use the **Rotate Key** option to generate a new one. **Where should I store my API key?** Store it in a secure location such as a password manager, environment variable, or secrets management system. Never share your key publicly or commit it to source control. # Upload Feed ``` POST /v1/feeds Content-Type: multipart/form-data ``` Upload a product catalog feed file for processing. The file is validated, stored, and processed asynchronously through a workflow pipeline. The response is returned immediately with a `202 Accepted` status while processing continues in the background. ## Request **Headers** | Header | Required | Description | | --------------- | -------- | -------------------------------- | | `Authorization` | Yes | `Bearer msk_{merchant_id}{uuid}` | | `Content-Type` | Yes | `multipart/form-data` | **Form Parts** | Part | Type | Required | Description | | -------------- | ------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `file` | binary | Yes | The feed file. Max size: 2 GB. Accepted formats: Google Product Feed XML (`application/xml` or `text/xml`). | | `feedName` | string | Yes | A human-readable name for this feed. Example: `"Summer 2024 Product Catalog"` | | `feedType` | string | Yes | Must be `CATALOG` or `INVENTORY`. | | `parentFeedId` | string | Only for `INVENTORY` | The `feed_id` of the parent catalog feed. Required when `feedType` is `INVENTORY`. Example: `"cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890"` | **Feed Types** | Type | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `CATALOG` | A full product catalog containing product information, pricing, and availability. Generates a feed ID prefixed with `cat_`. | | `INVENTORY` | An inventory update for an existing catalog feed. Must reference a parent catalog feed via `parentFeedId`. Generates a feed ID prefixed with `inv_`. | ## Example Requests ### Catalog Feed ```bash curl -X POST https://api.violet.io/v1/feeds \ -H 'Authorization: Bearer msk_12345abc11094a44800d84017c593e22' \ -F 'file=@products.xml' \ -F 'feedName=Summer 2024 Product Catalog' \ -F 'feedType=CATALOG' ``` ### Inventory Feed Inventory feeds update stock levels for products in an existing catalog feed. The XML uses the same Google Product Feed format, but only ``, ``, and inventory fields are required per item — the service matches items to existing products by their ``. ```bash curl -X POST https://api.violet.io/v1/feeds \ -H 'Authorization: Bearer msk_12345abc11094a44800d84017c593e22' \ -F 'file=@inventory-update.xml' \ -F 'feedName=Daily Inventory Update' \ -F 'feedType=INVENTORY' \ -F 'parentFeedId=cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890' ``` **Example `inventory-update.xml`:** ```xml Daily Inventory Update https://www.example.com Inventory feed TSHIRT-WHT-S in stock 48 TSHIRT-WHT-M in stock 12 TSHIRT-BLK-S out of stock 0 ``` ## Response **`202 Accepted`** — Feed uploaded successfully. Processing has started asynchronously. ```json { "feed_id": "cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "status": "PENDING", "message": "Feed uploaded successfully and processing initiated", "timestamp": "2024-03-15T10:30:00Z", "merchant_id": 12345, "workflow_id": "feed-upload-cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "uploaded_at": "2024-03-15T10:30:00Z" } ``` ### Response Fields | Field | Type | Description | | ------------- | ----------------- | ----------------------------------------------------------------------------------------------------- | | `feed_id` | string | Unique identifier for the feed. Prefixed with `cat_` for catalog feeds or `inv_` for inventory feeds. | | `status` | string | Processing status. Will be `PENDING` immediately after upload. | | `message` | string | Human-readable description of the operation result. | | `timestamp` | string (ISO 8601) | When the upload completed. | | `merchant_id` | integer | Your merchant ID. | | `workflow_id` | string | ID of the processing workflow. Can be used to track async processing. | | `uploaded_at` | string (ISO 8601) | When the file was uploaded to storage. | ## Error Responses **`400 Bad Request`** — Validation failed. ```json { "code": "INVALID_FEED_TYPE", "message": "feedType must be CATALOG or INVENTORY", "timestamp": "2024-03-15T10:30:00Z" } ``` Common error codes: | Code | Description | | ------------------------ | ------------------------------------------------- | | `INVALID_FEED_TYPE` | `feedType` must be `CATALOG` or `INVENTORY`. | | `MISSING_PARENT_FEED` | `parentFeedId` is required for `INVENTORY` feeds. | | `INVALID_FILE` | The uploaded file is empty. | | `MISSING_AUTHENTICATION` | No `Authorization` header provided. | **`413 Payload Too Large`** — File exceeds the 2 GB limit. ```json { "code": "FILE_TOO_LARGE", "message": "File size exceeds 2GB limit", "timestamp": "2024-03-15T10:30:00Z" } ``` # Get Feed by ID ``` GET /v1/feeds/{feedId} ``` Retrieve full details for a specific feed, including processing status, statistics, and any errors encountered. ## Request **Headers** | Header | Required | Description | | --------------- | -------- | -------------------------------- | | `Authorization` | Yes | `Bearer msk_{merchant_id}{uuid}` | **Path Parameters** | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------------------- | | `feedId` | string | Yes | The feed identifier. Format: `cat_{uuid}` or `inv_{uuid}`. | ## Example Request ```bash curl -X GET https://api.violet.io/v1/feeds/cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890 \ -H 'Authorization: Bearer msk_12345abc11094a44800d84017c593e22' ``` ## Response **`200 OK`** ```json { "feed_id": "cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "merchant_id": 12345, "merchant_name": "Acme Electronics", "feed_name": "Summer 2024 Product Catalog", "description": "Complete product catalog with seasonal items", "feed_type": "CATALOG", "status": "ACTIVE", "upload_method": "FILE_UPLOAD", "original_filename": "catalog.xml", "file_size_bytes": 2048576, "total_products": 1250, "date_created": "2024-03-15T10:30:00Z", "date_last_processed": "2024-03-15T10:45:00Z", "date_last_modified": "2024-03-15T10:45:00Z", "processing_stats": { "total_products": 1250, "successful_products": 1200, "failed_products": 50, "processing_duration_ms": 45000, "processing_started_at": "2024-03-15T10:30:05Z", "processing_completed_at": "2024-03-15T10:45:00Z" }, "errors": [ { "error_code": "MISSING_PRICE", "message": "Price missing for product ID: ABC123", "field": "ABC123", "severity": "WARNING", "timestamp": "2024-03-15T10:35:00Z", "product_id": "ABC123" } ], "configuration": { "auto_approve_products": true, "enable_inventory_tracking": true, "low_stock_threshold": 10, "feed_processing_notifications": true, "duplicate_product_handling": "MERGE", "price_validation_enabled": true, "refresh_frequency_minutes": 360, "retention_policy_days": 90, "default_currency": "USD", "default_country": "US", "default_language": "en_US", "timezone": "America/New_York", "removal_detection": { "enabled": true, "action": "ARCHIVE", "bulk_removal_threshold_percent": 50, "grace_period_versions": 0, "notify_on_removal": true, "notify_removal_threshold": 1 } } } ``` ### Response Fields | Field | Type | Description | | --------------------- | ----------------- | ------------------------------------------------------------------------------------- | | `feed_id` | string | Unique feed identifier. | | `merchant_id` | integer | Merchant who owns this feed. | | `merchant_name` | string | Merchant display name. | | `feed_name` | string | Human-readable feed name. | | `description` | string | Optional feed description. | | `feed_type` | string | `CATALOG` or `INVENTORY`. | | `status` | string | Current processing status (see [Feed Statuses](/feeds/feeds-overview#feed-statuses)). | | `upload_method` | string | How the feed was uploaded: `FILE_UPLOAD`, `URL_SYNC`, or `SFTP_UPLOAD`. | | `original_filename` | string | Original name of the uploaded file. | | `file_size_bytes` | integer | File size in bytes. | | `total_products` | integer | Total number of products in the feed. | | `date_created` | string (ISO 8601) | When the feed was first created. | | `date_last_processed` | string (ISO 8601) | When the feed was last processed. | | `date_last_modified` | string (ISO 8601) | When the feed was last modified. | | `parent_feed_id` | string | Parent catalog feed ID (only for inventory feeds). | | `processing_stats` | object | Processing performance metrics (see below). | | `errors` | array | List of processing errors and warnings (see below). | | `configuration` | object | Feed configuration settings (see below). | ### Processing Stats | Field | Type | Description | | ------------------------- | ----------------- | -------------------------------------- | | `total_products` | integer | Total products processed. | | `successful_products` | integer | Products processed successfully. | | `failed_products` | integer | Products that failed processing. | | `processing_duration_ms` | integer | Total processing time in milliseconds. | | `processing_started_at` | string (ISO 8601) | When processing started. | | `processing_completed_at` | string (ISO 8601) | When processing completed. | ### Errors | Field | Type | Description | | ------------ | ----------------- | ---------------------------------------------------- | | `error_code` | string | Machine-readable error code (e.g., `MISSING_PRICE`). | | `message` | string | Human-readable error description. | | `field` | string | Field or product ID where the error occurred. | | `severity` | string | `INFO`, `WARNING`, `ERROR`, or `CRITICAL`. | | `timestamp` | string (ISO 8601) | When the error was detected. | | `product_id` | string | Product ID associated with the error. | ### Configuration | Field | Type | Description | | ---------------------------- | ------- | ---------------------------------------------------------------------------- | | `auto_approve_products` | boolean | Whether products are auto-approved without manual review. Default: `true`. | | `enable_inventory_tracking` | boolean | Whether inventory levels are tracked. Default: `true`. | | `low_stock_threshold` | integer | Items below this quantity are considered low stock. Default: `10`. | | `duplicate_product_handling` | string | How duplicates are handled: `MERGE`, `SKIP`, or `REPLACE`. Default: `MERGE`. | | `price_validation_enabled` | boolean | Whether price validation rules are enforced. Default: `true`. | | `refresh_frequency_minutes` | integer | How often the feed is refreshed, in minutes. Default: `360`. | | `default_currency` | string | Default currency code. Default: `USD`. | | `default_country` | string | Default country code. Default: `US`. | | `removal_detection` | object | Item removal detection settings (see below). | ### Removal Detection | Field | Type | Description | | -------------------------------- | ------- | ------------------------------------------------------------------------------------------ | | `enabled` | boolean | Whether removal detection is active. Default: `true`. | | `action` | string | Action for removed items: `ARCHIVE`, `MARK_FOR_REVIEW`, or `IGNORE`. Default: `ARCHIVE`. | | `bulk_removal_threshold_percent` | integer | If more than this percentage of items are removed, flag for review instead. Default: `50`. | | `grace_period_versions` | integer | Number of feed versions an item can be missing before archival. Default: `0`. | | `notify_on_removal` | boolean | Whether to send notifications on item removal. Default: `true`. | | `notify_removal_threshold` | integer | Minimum removed items to trigger a notification. Default: `1`. | ## Error Responses **`404 Not Found`** — No feed with the given ID exists for your merchant. ```json { "code": "FEED_NOT_FOUND", "message": "Feed not found or access denied", "timestamp": "2024-03-15T10:30:00Z" } ``` # List Feeds ``` GET /v1/feeds ``` Retrieve a paginated list of all feeds for your merchant. Results are ordered by creation date, newest first. ## Request **Headers** | Header | Required | Description | | --------------- | -------- | -------------------------------- | | `Authorization` | Yes | `Bearer msk_{merchant_id}{uuid}` | **Query Parameters** | Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ------- | ---------------------------------------------------------------- | | `page` | integer | No | `0` | Page number (0-based). | | `size` | integer | No | `20` | Number of feeds per page. Min: 1, Max: 100. | | `status` | string | No | — | Filter by status: `PENDING`, `PROCESSING`, `ACTIVE`, or `ERROR`. | ## Example Requests List all feeds: ```bash curl -X GET 'https://api.violet.io/v1/feeds?page=0&size=20' \ -H 'Authorization: Bearer msk_12345abc11094a44800d84017c593e22' ``` List only active feeds: ```bash curl -X GET 'https://api.violet.io/v1/feeds?status=ACTIVE' \ -H 'Authorization: Bearer msk_12345abc11094a44800d84017c593e22' ``` ## Response **`200 OK`** ```json { "feeds": [ { "feed_id": "cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "feed_name": "Summer 2024 Product Catalog", "feed_type": "CATALOG", "upload_method": "FILE_UPLOAD", "status": "ACTIVE", "product_count": 1250, "file_size": 2048576, "date_created": "2024-03-15T10:30:00Z", "date_last_modified": "2024-03-15T10:45:00Z", "error_count": 5, "merchant_id": 12345 }, { "feed_id": "inv_b2c3d4e5-f6a7-8901-bcde-f23456789012", "feed_name": "Daily Inventory Update", "feed_type": "INVENTORY", "upload_method": "FILE_UPLOAD", "status": "PROCESSING", "product_count": 500, "file_size": 512000, "date_created": "2024-03-15T09:15:00Z", "date_last_modified": "2024-03-15T09:15:00Z", "parent_feed_id": "cat_a1b2c3d4-e5f6-7890-abcd-ef1234567890", "error_count": 0, "merchant_id": 12345 } ], "pagination": { "current_page": 0, "page_size": 20, "total_elements": 45, "total_pages": 3, "is_first": true, "is_last": false, "has_next": true, "has_previous": false } } ``` ### Feed Fields | Field | Type | Description | | -------------------- | ----------------- | ---------------------------------------------- | | `feed_id` | string | Unique feed identifier. | | `feed_name` | string | Human-readable feed name. | | `feed_type` | string | `CATALOG` or `INVENTORY`. | | `upload_method` | string | `FILE_UPLOAD`, `URL_SYNC`, or `SFTP_UPLOAD`. | | `status` | string | Current processing status. | | `product_count` | integer | Number of products in this feed. | | `file_size` | integer | File size in bytes. | | `date_created` | string (ISO 8601) | When the feed was created. | | `date_last_modified` | string (ISO 8601) | When the feed was last modified. | | `parent_feed_id` | string | Parent catalog feed ID (inventory feeds only). | | `error_count` | integer | Number of processing errors. | | `merchant_id` | integer | Merchant ID. | ### Pagination | Field | Type | Description | | ---------------- | ------- | --------------------------------------- | | `current_page` | integer | Current page number (0-based). | | `page_size` | integer | Number of items per page. | | `total_elements` | integer | Total number of feeds across all pages. | | `total_pages` | integer | Total number of pages. | | `is_first` | boolean | Whether this is the first page. | | `is_last` | boolean | Whether this is the last page. | | `has_next` | boolean | Whether a next page exists. | | `has_previous` | boolean | Whether a previous page exists. | ## Error Responses **`400 Bad Request`** — Invalid filter or pagination parameters. ```json { "code": "VALIDATION_FAILED", "message": "Invalid status filter. Must be one of: PENDING, PROCESSING, ACTIVE, ERROR", "timestamp": "2024-03-15T10:30:00Z" } ``` # XML Format Guide Feeds must conform to the [Google Product Feed](https://support.google.com/merchants/answer/7052112) XML format. The file is an RSS 2.0 document with product data inside `` elements under a ``. Google-specific fields use the `g:` namespace prefix (`http://base.google.com/ns/1.0`). ## Basic Structure ```xml My Product Catalog https://www.example.com Product feed ``` Each `` represents a single product variant (SKU). The service parses every item, groups them by `item_group_id` into offers, and transforms them into standardized Violet platform products. ## Supported Fields All Google-namespaced fields use the `g:` prefix. The `` and `<description>` elements can appear with or without the prefix. ### Product Identity | XML Element | Required | Type | Description | | ------------------- | -------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `<g:id>` | **Yes** | string | Unique identifier for this product variant (SKU). Each item in the feed must have a distinct ID. This becomes the SKU's `external_id` in the Violet platform. | | `<title>` | **Yes** | string | Product title. Used as both the offer name and SKU name. Keep it descriptive but concise (e.g., `"Nike Air Max 90 - Black/White - Size 10"`). | | `<g:item_group_id>` | No | string | Groups multiple items into a single parent product (offer). All items sharing the same `item_group_id` become SKU variants under one offer. See [Grouping Items Under a Parent Product](#grouping-items-under-a-parent-product). | ### Description & Links | XML Element | Required | Type | Description | | ---------------- | -------- | ------------ | ---------------------------------------------------------------------------------------------------- | | `<description>` | No | string | Detailed product description. Mapped to the offer's description field. | | `<link>` | No | string (URL) | URL to the product page on your website. Mapped to the offer's `external_url`. | | `<g:image_link>` | No | string (URL) | URL of the main product image. Should be a high-quality image (at least 800x800 pixels recommended). | ### Pricing Prices are specified as a decimal value followed by a space and a 3-letter ISO 4217 currency code (e.g., `79.99 USD`). European decimal format is also supported (e.g., `79,99 EUR`). Prices are converted to integer cents internally (e.g., `79.99 USD` becomes `7999`). | XML Element | Required | Type | Description | | ----------------- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `<g:price>` | **Yes** | string | The current selling price. Format: `{amount} {currency}` (e.g., `"29.99 USD"`, `"1,234.56 CAD"`). If no `sale_price` is provided, this value is used as both the retail price and sale price. | | `<g:sale_price>` | No | string | A discounted price. When present, this becomes the SKU's sale price and the `price` field becomes the retail (original/MSRP) price. Same format as `price`. | | `<g:offer_price>` | No | string | An alternative offer price. Parsed but reserved for future use. | **Supported currency codes:** `USD`, `EUR`, `GBP`, `CAD`. Currency symbols (`$`, `€`, `£`) are also recognized. If no currency is specified, `USD` is assumed. **Pricing examples:** ```xml <!-- Simple pricing: one price for everything --> <g:price>49.99 USD</g:price> <!-- Sale pricing: show original price crossed out --> <g:price>49.99 USD</g:price> <g:sale_price>34.99 USD</g:sale_price> <!-- Result: retail_price = 4999, sale_price = 3499 --> ``` ### Availability & Inventory | XML Element | Required | Type | Description | | ------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `<g:availability>` | **Yes** | string | Stock status. Accepted values: `in stock`, `in_stock`, `out of stock`, `out_of_stock`, `preorder`. Items with `in stock` or `in_stock` are marked as available. | | `<g:inventory>` | No | integer | Exact quantity available. When provided, enables inventory tracking with precise stock counts. Takes priority over `<stock>` and `<g:availability>` for quantity. | | `<stock>` | No | string | Custom stock quantity field. Supports formats like `"5"`, `"3+"`, `"10+"`. Used as a fallback when `<g:inventory>` is not present. Note: this field does **not** use the `g:` namespace. | **Inventory resolution order:** The service determines stock quantity using the first available source: 1. `<g:inventory>` — Exact quantity, enables inventory tracking 2. `<stock>` — Parsed quantity (the `+` suffix is stripped), enables inventory tracking 3. `<g:availability>` — Binary in-stock/out-of-stock only, no quantity tracking ### Product Identifiers | XML Element | Required | Type | Description | | ----------- | -------- | ------ | ------------------------------------------------------------------------------------ | | `<g:gtin>` | No | string | Global Trade Item Number (UPC, EAN, ISBN, or JAN). Mapped to the SKU's `gtin` field. | | `<g:mpn>` | No | string | Manufacturer Part Number. Mapped to the SKU's `upc` field. | | `<g:brand>` | No | string | Product brand or manufacturer name. Mapped to the offer's `vendor` field. | ### Condition | XML Element | Required | Type | Description | | --------------- | -------- | ------ | ----------------------------------------------------------------------------------------------------- | | `<g:condition>` | No | string | Product condition. Accepted values: `new`, `refurbished`, `used`. Parsed and stored on the feed item. | ### Categorization | XML Element | Required | Type | Description | | ----------------------------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `<g:google_product_category>` | No | string | Google product taxonomy category. Takes priority over `product_type` for categorization. Example: `"Apparel & Accessories > Shoes > Athletic Shoes"`. | | `<g:product_type>` | No | string | Your own product categorization. Used as a fallback when `google_product_category` is not set. Example: `"Men's Footwear > Running Shoes"`. | ### Variant Attributes These fields define how product variants differ from each other. When items are grouped by `item_group_id`, these attributes become selectable variant options on the offer (e.g., a color picker or size dropdown). | XML Element | Required | Type | Description | | -------------- | -------- | ------ | ---------------------------------------------------------------------------------------------------- | | `<g:color>` | No | string | Product color. Creates a "Color" variant on the offer. Example: `"Navy Blue"`. | | `<g:size>` | No | string | Product size. Creates a "Size" variant on the offer. Example: `"10"`, `"Medium"`, `"32W x 30L"`. | | `<g:material>` | No | string | Primary material. Creates a "Material" variant on the offer. Example: `"Leather"`, `"Cotton Blend"`. | | `<g:pattern>` | No | string | Product pattern or print. Creates a "Pattern" variant on the offer. Example: `"Striped"`, `"Plaid"`. | ### Demographic Attributes These fields are stored as offer-level metadata rather than variant attributes. | XML Element | Required | Type | Description | | --------------- | -------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- | | `<g:age_group>` | No | string | Target age group. Accepted values: `newborn`, `infant`, `toddler`, `kids`, `adult`. Stored as offer metadata with key `age_group`. | | `<g:gender>` | No | string | Target gender. Accepted values: `male`, `female`, `unisex`. Stored as offer metadata with key `gender`. | ## Grouping Items Under a Parent Product Use `<g:item_group_id>` to group multiple items (SKUs) into a single offer. This is how you represent a product that comes in multiple sizes, colors, or other variants. **How it works:** 1. All items with the same `item_group_id` are grouped into one offer 2. Each item becomes a separate SKU under that offer 3. Variant attributes (`color`, `size`, `material`, `pattern`) on each item become selectable options 4. The first item in the group provides the offer-level details (title, description, link, brand, category) 5. Pricing is aggregated across all SKUs — the offer tracks the min and max price **Items without an `item_group_id`** are treated as standalone offers with a single SKU. The item's `<g:id>` is used as the group key. ### Example: T-Shirt with Color and Size Variants ```xml <!-- White T-Shirt, Small --> <item> <g:id>TSHIRT-WHT-S</g:id> <g:item_group_id>TSHIRT-001</g:item_group_id> <title>Classic Cotton T-Shirt Comfortable everyday cotton tee https://www.example.com/products/classic-tshirt https://www.example.com/images/tshirt-white.jpg 24.99 USD in stock 50 ExampleBrand new White S Cotton unisex adult Apparel & Accessories > Clothing > Shirts & Tops 012345678901 TSHIRT-WHT-M TSHIRT-001 Classic Cotton T-Shirt Comfortable everyday cotton tee https://www.example.com/products/classic-tshirt https://www.example.com/images/tshirt-white.jpg 24.99 USD in stock 35 ExampleBrand new White M Cotton 012345678902 TSHIRT-BLK-S TSHIRT-001 Classic Cotton T-Shirt Comfortable everyday cotton tee https://www.example.com/products/classic-tshirt https://www.example.com/images/tshirt-black.jpg 24.99 USD out of stock 0 ExampleBrand new Black S Cotton 012345678903 ``` This produces **one offer** (`TSHIRT-001`) with: * **3 SKUs**: `TSHIRT-WHT-S`, `TSHIRT-WHT-M`, `TSHIRT-BLK-S` * **Variant "Color"**: White, Black * **Variant "Size"**: S, M * **Variant "Material"**: Cotton * **Price range**: min = 2499, max = 2499 ## Handling Images Each item supports a single `` for its main product image. To associate different images with different variants, provide a unique `image_link` per item. ```xml SHOE-RED-10 SHOE-001 https://www.example.com/images/shoe-red.jpg Red SHOE-BLU-10 SHOE-001 https://www.example.com/images/shoe-blue.jpg Blue ``` > **Note:** The `` element from the Google Product Feed specification is not currently supported. Only the primary `` is processed per item. ## Standalone Products (No Variants) Products that don't come in multiple variants can omit ``. Each item becomes its own offer with a single SKU. ```xml GADGET-042 Wireless Bluetooth Speaker Portable speaker with 12-hour battery life https://www.example.com/products/bt-speaker https://www.example.com/images/speaker.jpg 59.99 USD in stock 120 SoundTech new 098765432109 Electronics > Audio > Speakers ``` This produces **one offer** with **one SKU**, both using `GADGET-042` as their external ID. ## Sale Pricing Example To show a discounted price alongside the original price, provide both `` (the original/MSRP) and `` (the current discounted price). ```xml JACKET-SALE-01 Winter Puffer Jacket 199.99 USD 129.99 USD in stock ``` **Result:** `retail_price = 19999` (cents), `sale_price = 12999` (cents). When only `` is provided (no ``), the same value is used for both `retail_price` and `sale_price`. ## Minimal Valid Feed The smallest valid feed requires at minimum ``, ``, `<g:price>`, and `<g:availability>` on each item: ```xml <?xml version="1.0" encoding="UTF-8"?> <rss version="2.0" xmlns:g="http://base.google.com/ns/1.0"> <channel> <title>My Store https://www.example.com Product feed PROD-001 Example Product 19.99 USD in stock ``` ## Complete Feed Example A full-featured feed with grouped variants, sale pricing, inventory tracking, and all supported fields: ```xml Acme Electronics - Summer 2024 https://www.acme-electronics.com Complete product catalog CHARGER-USB-C 65W USB-C Fast Charger GaN technology fast charger compatible with laptops and phones https://www.acme-electronics.com/products/usb-c-charger https://cdn.acme-electronics.com/images/charger-usbc.jpg 39.99 USD 29.99 USD in stock 500 new Acme 012345678905 ACME-CHG-65W Electronics > Electronics Accessories > Power Chargers > USB-C CASE-BLK-14 CASE-PRO ProShield Phone Case Military-grade drop protection phone case https://www.acme-electronics.com/products/proshield-case https://cdn.acme-electronics.com/images/case-black.jpg 29.99 USD in stock 200 new Acme Black Polycarbonate unisex adult Electronics > Communications > Telephony > Mobile Phone Accessories > Mobile Phone Cases CASE-NAV-14 CASE-PRO ProShield Phone Case Military-grade drop protection phone case https://www.acme-electronics.com/products/proshield-case https://cdn.acme-electronics.com/images/case-navy.jpg 29.99 USD in stock 150 new Acme Navy Polycarbonate CASE-CLR-14 CASE-PRO ProShield Phone Case Military-grade drop protection phone case https://www.acme-electronics.com/products/proshield-case https://cdn.acme-electronics.com/images/case-clear.jpg 34.99 USD in stock 75 new Acme Clear TPU ``` This feed produces: * **Offer 1** (`CHARGER-USB-C`): Standalone charger, 1 SKU, sale price $29.99 (retail $39.99) * **Offer 2** (`CASE-PRO`): Phone case group, 3 SKUs, variant "Color" (Black, Navy, Clear), variant "Material" (Polycarbonate, TPU), price range $29.99–$34.99 ## Field-to-Platform Mapping Reference This table shows how each XML field maps to the Violet platform's Offer and SKU models. **Offer-level fields** (set from the first item in a group): | XML Element | Offer Field | Notes | | ------------------------------- | ------------------------ | -------------------------------------------------- | | `` or `` | `external_id` | Group ID if present, otherwise item ID | | `` | `name` | | | `<description>` | `description` | | | `<link>` | `external_url` | | | `<g:brand>` | `vendor` | | | `<g:google_product_category>` | `source_category_name` | Priority over `product_type` | | `<g:product_type>` | `source_category_name` | Fallback if no Google category | | `<g:availability>` | `available` | `true` if "in stock" or "in\_stock" | | `<g:price>` | `min_price`, `max_price` | Aggregated across all SKUs in the group (in cents) | | `<g:age_group>` | metadata `age_group` | Stored as offer metadata | | `<g:gender>` | metadata `gender` | Stored as offer metadata | **SKU-level fields** (set per item): | XML Element | SKU Field | Notes | | ------------------ | ---------------------------- | -------------------------------------------------------------------------- | | `<g:id>` | `external_id` | | | `<title>` | `name` | | | `<g:price>` | `sale_price`, `retail_price` | Converted to cents. Both set to same value unless `sale_price` is provided | | `<g:sale_price>` | `sale_price` | Overrides `price` as sale\_price; `price` then becomes `retail_price` only | | `<g:gtin>` | `gtin` | | | `<g:mpn>` | `upc` | Mapped to UPC field | | `<g:inventory>` | `qty_available` | Enables `inventory_tracked = true` | | `<g:availability>` | `in_stock` | Fallback when no `inventory` or `stock` field | | `<g:color>` | variant value "Color" | | | `<g:size>` | variant value "Size" | | | `<g:material>` | variant value "Material" | | | `<g:pattern>` | variant value "Pattern" | | ## Unmapped Fields and SKU Metadata The Google Product Feed specification includes fields beyond those listed above. Any additional Google Product Feed fields that do not have a one-to-one mapping to existing properties on the Violet Offer or SKU models are captured as metadata on each SKU. For example, fields like `<g:shipping_weight>`, `<g:custom_label_0>`, or `<g:energy_efficiency_class>` do not map directly to a dedicated Offer or SKU property. Instead, they are stored as key-value metadata entries on the SKU, preserving the original field name as the key and the element's text content as the value. This means you can include any valid Google Product Feed field in your XML and the data will not be lost — it will be accessible through the SKU's metadata collection even if it doesn't appear in the mapping tables above. # Getting Paid ## 💰 Getting Paid {% hint style="info" %} 💜 **Get paid automatically** - Set up your payout account once and receive earnings from all connected channels seamlessly through Stripe. {% endhint %} Getting paid through Violet is straightforward and secure. We use Stripe Connect to handle all payout processing, ensuring you receive your earnings reliably while maintaining full transparency over your transactions. ### 🚀 Quick Start {% tabs %} {% tab title="🆕 New to Violet" %} **First-time setup:** 1. Complete merchant onboarding through Violet Connect 2. Set up your Stripe payout account during onboarding 3. Complete KYC verification with Stripe 4. Start receiving automatic payouts {% endtab %} {% tab title="✅ Already Connected" %} **Manage your payments:** 1. View payout history in your Merchant Dashboard 2. Update payout account settings 3. Track distributions across orders 4. Export financial data for accounting {% endtab %} {% endtabs %} ### 📋 Essential Guides #### 🔧 **Setting up a Payout Account** *First-time payout account configuration* **What you'll learn:** * How to create your Stripe Express account during onboarding * KYC verification requirements and process * Choosing between Express vs. Standard Stripe accounts * Account activation and verification steps {% hint style="info" %} ⏱️ **Setup Time:** 5-10 minutes | **Required:** Bank account details and business information {% endhint %} [**→ Start Setup Guide**](/interacting-with-violet/getting-paid/setting-up-a-payout-account) *** #### 📊 **Managing Payout Accounts in the Merchant Dashboard** *Complete account management and monitoring* **What you'll learn:** * Accessing your payout settings and history * Viewing transaction details and distributions * Exporting payout data for accounting * Managing multiple payout accounts per channel {% hint style="success" %} 🎯 **Best for:** Ongoing account management and financial tracking {% endhint %} [**→ View Management Guide**](/interacting-with-violet/getting-paid/managing-payout-accounts) *** #### 💵 **Understanding Payouts and Distributions** *How money flows through the Violet system* **What you'll learn:** * The difference between payouts and distributions * How commission rates affect your earnings * Payout timing and processing schedules * Refund and chargeback handling {% hint style="info" %} 📚 **Essential reading** for understanding your earnings and payment flow {% endhint %} [**→ Learn About Payouts**](/interacting-with-violet/getting-paid/understanding-payouts) *** #### 🔄 **Connecting a New Stripe Account for Payouts** *Advanced account management and switching* **What you'll learn:** * When and why to create additional payout accounts * Switching between personal and business Stripe accounts * Managing multiple accounts per sales channel * Handling account transitions and historical data {% hint style="danger" %} **Advanced Feature:** Only needed when switching accounts or managing multiple channels {% endhint %} [**→ Advanced Account Setup**](/interacting-with-violet/getting-paid/connecting-new-stripe-accounts) *** ### 🔍 Quick Reference #### Account Types Comparison | Feature | Stripe Express | Stripe Standard | | -------------------- | ----------------- | --------------------- | | **Setup Complexity** | 🟢 Simple | 🟡 Moderate | | **Dashboard Access** | Express Dashboard | Full Stripe Dashboard | | **Best For** | New merchants | Existing Stripe users | | **Cross-border** | ✅ Supported | ❌ Limited | | **Onboarding** | Violet-hosted | Self-managed | #### Payout Timeline {% code overflow="wrap" %} ``` Order Placed → Transfer to Stripe → Settlement (Pending→Available) → Stripe Payout → Bank Deposit ↓ ↓ ↓ ↓ ↓ Instant ~30 seconds 2-3 business days Per schedule 1-2 days ``` {% endcode %} {% hint style="info" %} **Understanding "Pending" funds:** After the transfer posts to your Stripe account, funds may show as "pending" for 2-3 business days. This is Stripe's standard card settlement window. The money is already in your Stripe account—it just isn't available for bank payout yet. {% endhint %} #### Common Questions <details> <summary>💰 <strong>When do I get paid?</strong></summary> Payouts follow Stripe's standard schedule: * **New accounts:** 7-day rolling basis after first sale * **Established accounts:** 2-day rolling basis * **Custom schedules:** Available for high-volume merchants </details> <details> <summary>🌍 Can I receive payments in different currencies?</summary> Yes! Violet supports: * Multi-currency payouts through Stripe * Automatic currency conversion * Presentment currency pricing (advanced feature) </details> <details> <summary><strong>🔒 How secure are my banking details?</strong></summary> Your banking information is handled entirely by Stripe: * PCI DSS Level 1 compliant * Bank-grade security * Violet never stores your banking details </details> ### 🆘 Need Help? #### Quick Solutions * **Account Issues:** Check your Stripe Express dashboard for verification status * **Missing Payouts:** Verify your bank account details in payout settings * **Commission Questions:** Review your commission rates in the Merchant Dashboard #### Get Support * **📞 Technical Issues:** Contact your channel partner for account setup problems * **💬 Business Questions:** Reach out to your channel partner for commission discussions * **📧 Stripe Issues:** Use your Stripe Express dashboard for payment-related questions {% hint style="info" %} 🎯 **Pro Tip:** Use your Merchant Dashboard Messages tab to communicate directly with your connected channels about payout questions. {% endhint %} *** *💜 Ready to get started? Most merchants complete payout setup in under 10 minutes during onboarding.* # Setting up a Payout Account ## Receiving Payments If you're a merchant, to receive payments for orders placed through Violet, you’ll need to connect a bank account via Stripe. Connected apps leverage Stripe Connect to make the onboarding process seamless. You can either create a **Stripe Connect Express account** specifically for handling transactions through your connected app's payment platform or link your existing **Stripe Standard account** via OAuth. {% hint style="info" %} Setting up your payout account is required to receive payments from orders. Make sure to complete this step before accepting orders. {% endhint %} ![Creating a Payout Account in Violet Connect](https://res.cloudinary.com/violet/image/upload/v1745867621/docs/violet_connect/VC-Create-Payout-Account.png) ## Choosing Your Stripe Account Type ### Stripe Express Account A **Stripe Express account** is a fast and easy way to set up payouts. Companies like DoorDash, Lyft, and Shopify use Stripe Express for their payment processes. With this setup, you can: * Quickly onboard with streamlined **KYC (Know Your Customer)** verification. * Manage your **payout schedule** directly from Stripe. * Keep all **sensitive data securely** stored within Stripe. This account is dedicated to handling your payouts from Violet and **cannot** be used for external transactions. On the Stripe dashboard, they can click on the transactions tab to see payments from Violet as well Stripe Payouts to their bank account.\ They can filter by date and export the data to CSV. ### Stripe Standard Account {% hint style="info" %} Some Channels may restrict the use of Stripe Standard accounts. In these cases, you'll need to use a Stripe Express account to receive payouts. {% endhint %} If you already have a **Stripe Standard account**, you can link it to receive payouts from Violet directly into the same account you use for your other business transactions. However, there are some limitations: * Your linked Stripe Standard account will provide **platform visibility** into all transactions, even those unrelated to Violet. * Once connected, it **cannot be linked** to another platform account. * **Standard accounts have additional restrictions** for cross-border transactions. The banking country must match the country of Violet’s Stripe platform account. * If you are an international merchant connecting to a US-based platform, a **Stripe Express account is required**. Reach out to your channel to learn more about the country they operate in. For more details, visit the [Stripe documentation](https://docs.stripe.com/connect/accounts). ## Setting Up Your Payouts ### Connecting a Stripe Standard Account If you choose to link an existing **Stripe Standard account**: {% hint style="info" %} Be aware that connecting a Stripe Standard account gives the Channel visibility into all transactions on that account, including non-Violet transactions. If you want to prevent this, you can create a new Stripe Standard account specifically for Violet during the Stripe onboarding flow. {% endhint %} 1. You’ll be redirected to Stripe to select the account you want to connect. 2. Ensure you're logged into the correct Stripe account before selecting it. 3. After linking, you’ll be returned to Violet, and your account will be ready to receive payouts. ### Creating a New Stripe Express Account If you don’t already have a Stripe account, you can create a new **Stripe Express account**: 1. Choose **"I don’t have a Stripe account."** 2. Select the **country** where your bank account is located (this may differ from your business location). 3. Complete the **Stripe KYC process**. 4. Once finished, you’ll be **redirected back to Violet**. 5. You can **monitor your account status and payouts** in Violet to ensure everything is set up correctly. If your country is **not listed**, Stripe does not currently support payouts to that location. Check the [Stripe Global Support](https://stripe.com/global) page for more details. ![Connected Stripe Express Account in Violet Connect](https://res.cloudinary.com/violet/image/upload/v1749584759/docs/violet_connect/VC-Stripe-Express-Account-2.png) ## Merchants in Unsupported Countries If your country is not supported by Stripe for the channel's payment configuration, you may receive an **EXTERNAL payout account** instead of a Stripe-connected account. This means: * Your payout account will **not** be linked to Stripe * You will **not** have access to a Stripe dashboard for viewing transfers or payout schedules * Payouts will be processed by the Channel outside of Violet's payment infrastructure * You can still view pending distributions in the Merchant Dashboard * Contact your Channel to understand how and when you'll receive payouts {% hint style="info" %} If you believe your country should be supported, contact the Channel you connected with for more information about their payment capabilities and supported regions. {% endhint %} # Managing Payout Accounts in the Merchant Dashboard Once you've successfully connected your store to various apps, you can view and manage your payout accounts in the Merchant Dashboard. Each app connection requires its own dedicated payout account. This ensures clear separation of payments and proper routing of funds for each integration. ## App-Specific Payout Management The Merchant Dashboard lets you manage payouts for each connected app individually at <https://merchant.violet.io/settings/payouts>. Here you'll find a list of all connected apps with their payout accounts, including prompts to set up accounts for new connections. You can also access payout accounts for previously connected apps, even if they're currently disconnected. ![Payout accounts in the Merchant Dashboard](https://res.cloudinary.com/violet/image/upload/v1749584053/docs/merchant_dashboard/grouped-payout-accounts.png) ## Platform Payment Providers Many apps use their own Stripe payment platforms, requiring a direct payout account setup through their system. When setting up these accounts, you'll first need to select your banking country. After this initial step, you'll be redirected to Stripe to complete the onboarding process. For more information on setup options, see our guide on [choosing your Stripe account type](/interacting-with-violet/getting-paid/setting-up-a-payout-account#choosing-your-stripe-account-type). Once complete, you will have a working Stripe payout account connected to the app's payment platform that can receive payouts. ![Specifying your banking country when setting up a new Stripe Express account](https://res.cloudinary.com/ddhjp8mca/image/upload/v1742331657/mintlify/merchant-dashboard/m-dash-stripe-express-setup.png) ![Specifying your banking country when setting up a new Stripe Standard account](https://res.cloudinary.com/ddhjp8mca/image/upload/v1742331657/mintlify/merchant-dashboard/m-dash-stripe-standard-setup.png) ![Active payout account](https://res.cloudinary.com/violet/image/upload/v1749584053/docs/merchant_dashboard/active-payout-account.png) ## Account Migration Options If you need to migrate between different types of Stripe accounts, you can do so in the merchant dashboard. For more information, see our guide on [Connecting a new Stripe Account for Payouts](/interacting-with-violet/getting-paid/connecting-new-stripe-accounts). # Understanding Payouts and Distributions The Merchant Dashboard allows you to view all Payout and Distribution details for orders placed through Violet on your connected Sales Channels. A "Distribution" represents the funds transferred to your bank account for each order, along with a breakdown of any associated fees. Additionally, Violet generates a Distribution for the Sales Channel related to your order, so you can see the final breakdown of how funds were split and where they were transferred for each specific order. A Payout to your bank account is an aggregate of all Distributions across a given time period, usually each business day, that is triggered automatically by Stripe. ## How Funds Flow to Your Bank Understanding the payment timeline helps you know when to expect funds: ### 1. Transfer (Immediate) When a shopper completes checkout, Violet processes the payment and creates a Stripe Transfer to your connected Stripe account. This happens programmatically within seconds of order submission. ### 2. Settlement / Clearing (2-3 Business Days) Although the transfer posts immediately, Stripe holds funds as "pending" until the original card payment clears. This is standard for card transactions and reflects Stripe's risk and settlement window—not a delay in transferring your money. {% hint style="warning" %} **Why do funds show as "pending"?** This is normal. Stripe marks funds as "pending" until the card payment settles (typically 2-3 business days). During this time, the money is in your Stripe account but not yet available for payout. {% endhint %} ### 3. Bank Payout (Per Your Schedule) Once funds become "available," Stripe automatically initiates a payout to your bank based on your payout schedule: * **New accounts:** 7-day rolling basis after your first sale * **Established accounts:** 2-day rolling basis * **Bank processing:** Additional 1-2 business days for the bank to post the deposit ### Example Timeline | Event | Timing | | ------------------------ | -------------------------------- | | Order placed | Monday 2pm | | Transfer to your Stripe | Monday 2pm (\~30 sec later) | | Funds become "available" | Wednesday-Thursday | | Stripe initiates payout | Thursday evening (2-day rolling) | | Funds hit your bank | Friday-Saturday | **Total time:** \~5-7 business days for a new order to reach your bank (not counting weekends/holidays) ## Viewing Your Payouts You can view a list of all your payouts by navigating to the [Payouts dashboard](https://merchant.violet.io/payouts). On the default payouts page, you'll see a "Ext Payout" field which will map to the ID of your payout in your payment provider. You can use this along with the Violet Payout ID ("Payout ID") to map all related distributions to your payout amount. ![Payout Dashboard](https://res.cloudinary.com/ddhjp8mca/image/upload/v1721928065/mintlify/merchant-distributions/Payouts_bbgyw8.png) You can click into a payout and see a summary of order volume, payments, refunds, and distributions relevant to your payout. You'll also be able to see related distributions and export the payout with its related distributions in this view. ![Payout Detail View](https://res.cloudinary.com/ddhjp8mca/image/upload/v1721928058/mintlify/merchant-distributions/Payout_summary_xqr6ig.png) The [Distributions dashboard](https://merchant.violet.io/payouts?tab=distributions) is available in the tab next to Payouts. By default, you'll be able to see the following: ![](https://res.cloudinary.com/ddhjp8mca/image/upload/v1718720026/mintlify/merchant-distributions/Screenshot_2024-06-17_at_7.04.52_PM_bzvd3v.png) The “Ext Order” is the ID of the Order in your e-commerce store. You can use this ID to easily map between the Distribution in Violet to the Order placed in your system. The “Amount” column is the total amount you receive for this specific Order. Flipping on the “Channel” toggle, will let you see see the related Distributions made to Sales Channels for the same Order. This is usually their commission amount for the Order, minus any payment provider fees that the Channel pays. If the commission you give to a Channel does not cover the payment processor fees, you will see them on your Distribution record. ![](https://res.cloudinary.com/ddhjp8mca/image/upload/v1718720026/mintlify/merchant-distributions/Screenshot_2024-06-17_at_7.25.19_PM_f1n6s6.png) You can also download Distribution reports as CSV files that let you view more information and do reconciliation in a spreadsheet manager. To download a Distributions report, click on “Export” and follow the prompts. ![](https://res.cloudinary.com/ddhjp8mca/image/upload/v1718720025/mintlify/merchant-distributions/Screenshot_2024-06-17_at_7.27.56_PM_qy3vy2.png) ![](https://res.cloudinary.com/ddhjp8mca/image/upload/v1718720025/mintlify/merchant-distributions/Screenshot_2024-06-17_at_7.28.22_PM_v4lucy.png) To learn more about each column, you can click [here](https://docs.violet.io/prism/reporting/distributions/columns). Each Distribution that is associated to a Payout to your bank contains a Payout ID. From the example below, you can see all Distributions related to Payout ID 10280 , which correspond to a payout of $79.09 to your bank account, settled on 18th June 2024. As seen below, Refunds are also included when calculating the breakdown of a Payout. ![](https://res.cloudinary.com/ddhjp8mca/image/upload/v1718720026/mintlify/merchant-distributions/Screenshot_2024-06-18_at_10.06.00_AM_whtuvv.png) # Connecting a new Stripe Account for Payouts This guide walks through how to set up and manage your Stripe payout accounts in Violet. You can create multiple payout accounts and switch between them—one per app at any time. Payment history and Distribution records for past transactions will continue to point to the old account. New transactions will be tied to the active account. All payout records, past and present, remain visible in your Violet dashboard. {% hint style="info" %} This functionality replaces what was previously known as "Payout Account Migration". The new flow is simpler and lets you easily add, view, and switch between accounts without losing access to past payout data. {% endhint %} ## Understanding Payout Accounts Each **app** (or sales channel) you’re connected to in Violet has its **own dedicated payout account**. This account determines where earnings from that app are sent. You can have multiple payout accounts per app, but **only one can be marked as `Active`** at a time. ### What does “Active” mean? The **active** payout account is the one that will receive all new earnings from sales through that specific app. If you have multiple payout accounts connected, only the one marked as “Active” will be used for payouts. ## Why Switch to a New Payout Account? There are a few common reasons you may want to switch your active payout account: * You want to switch from a personal Stripe account to a business Stripe account * You need to change banking details and prefer creating a new account * Your sales channel requires a specific Stripe account type (Express or Standard) * You've had issues with your current Stripe account and want to start fresh Inactive accounts remain linked to your merchant profile and can be reactivated later if they still meet Stripe’s verification requirements. ## Getting Started To connect a new Stripe payout account, ensure you are connected to at least one app. Then, follow these steps: 1. Go to the [**Merchant Dashboard**](https://merchant.violet.io). 2. Navigate to [**Payout Account Settings**](https://merchant.violet.io/settings/payouts). 3. Navigate to the app you'd like to configure a payout account for. If no account exists, you’ll see a prompt to create one. If an account already exists, you’ll see an option to **Create Account** beneath your existing payout accounts. {% stepper %} {% step %} **Add a New Payout Account** 1. Click **Create New Payout Account** in the relevant app section. 2. Choose between **Stripe Express** or **Stripe Standard**. {% hint style="warning" %} Selecting "Already have a Stripe Account?" will let you connect an existing Stripe Standard account, while selecting "Don't have a Stripe Account?" will let you create a new Stripe Connect Express account. **Note:** Some apps may not support Stripe Standard. If unavailable, you will only have the option to create a Stripe Express account. {% endhint %} ![Choosing your Stripe Account Type](https://res.cloudinary.com/violet/image/upload/v1756157619/docs/merchant_dashboard/stripe-account-type-select.png) 3. Complete the Stripe onboarding flow (you’ll be redirected). 4. Once you return, the payout account will be created and visible in your dashboard. 5. If this is your **first** account for the app, it will be marked **Active** 6. Otherwise, it will be added as **Inactive** until you activate it manually ![Payout accounts in the Merchant Dashboard](https://res.cloudinary.com/violet/image/upload/v1749584053/docs/merchant_dashboard/grouped-payout-accounts.png) {% endstep %} {% step %} **Complete KYC in Stripe** All new payout accounts must meet Stripe’s Know-Your-Customer (KYC) requirements before they can be activated. 1. Click **Go to Stripe** next to the new account 2. Provide all required information in Stripe’s onboarding flow 3. Click **Submit** to complete verification. You’ll be redirected back to Violet Once KYC is complete, the account becomes eligible for activation {% endstep %} {% step %} **Switch to a Different Payout Account** Once your new account has completed KYC, you can activate it to replace your current payout account: 1. Click into the **Inactive** account 2. Review the account’s details and confirm KYC is marked **Complete** 3. Click on the "Inactive" pill and select the option **Make Active** * *Note: This option will be disabled if the account is not eligible for activation (i.e. KYC is not complete)* 4. A modal will appear to confirm the switch 5. On confirmation, this action will immediately deactivate the currently active account 6. All future earnings from the app will be routed to the new account ![An inactive payout account](https://res.cloudinary.com/violet/image/upload/v1749584054/docs/merchant_dashboard/inactive-payout-account.png) \\ ![Confirm activation of a payout account](https://res.cloudinary.com/violet/image/upload/v1749584054/docs/merchant_dashboard/payout-account-activate-modal.png) {% hint style="info" %} You must always have one active payout account per app. If no other account is eligible, you won't be able to deactivate the current one. {% endhint %} {% endstep %} {% endstepper %} You can perform the same steps in Violet Connect once on the payments setup step to switch to a new payout account for a specific app connection. ## How Refunds Work After Switching Accounts Refunds are always processed from the account that originally received the payout. * If an order is refunded after you’ve switched accounts, Violet will attempt to reverse the payout from the **original Stripe account** * This applies only during the **remorse period** (default: 30 days after the order date) * If the original account has been closed or disconnected from Stripe, the refund may fail # Connecting a new Payout Account in Violet Connect This guide explains how to connect or switch your payout account during the Violet Connect onboarding flow. Violet Connect is the merchant onboarding experience that allows you to set up your store connection and payment settings with a Channel. {% hint style="info" %} If you've already completed onboarding and want to manage your payout accounts from the Merchant Dashboard, see [Connecting a new Stripe Account for Payouts](/interacting-with-violet/getting-paid/connecting-new-stripe-accounts). {% endhint %} ## When to Use Violet Connect for Payout Setup You'll use Violet Connect to set up or change your payout account in these scenarios: * **Initial onboarding**: When first connecting your store to a Channel through Violet * **Adding a new Channel**: When connecting to an additional sales channel that requires its own payout account * **Switching accounts during setup**: When you need to change the payout account before completing onboarding Each Channel (app) connection has its own dedicated payout account. You can have different payout accounts for different Channels, or use the same account across multiple Channels. ## Setting Up Your Payout Account in Violet Connect When you reach the payments step in Violet Connect, you'll be prompted to connect a Stripe account for receiving payouts. {% stepper %} {% step %} **Choose Your Stripe Account Type** You'll see two options for connecting your payout account: 1. **"Don't have a Stripe Account?"** - Select this to create a new Stripe Express account 2. **"Already have a Stripe Account?"** - Select this to connect an existing Stripe Standard account {% hint style="warning" %} Some Channels may only support Stripe Express accounts. If Stripe Standard is unavailable for your Channel, you'll only see the option to create a Stripe Express account. {% endhint %} {% endstep %} {% step %} **Complete the Stripe Onboarding Flow** After selecting your account type, you'll be redirected to Stripe to complete the setup: **For Stripe Express accounts:** 1. Select the **country** where your bank account is located 2. Complete the **KYC (Know Your Customer)** verification process 3. Provide your banking details for receiving payouts 4. Click **Submit** to finish **For Stripe Standard accounts:** 1. Log in to your existing Stripe account 2. Authorize the connection to the Channel 3. Review and confirm the permissions Once complete, you'll be redirected back to Violet Connect. {% endstep %} {% step %} **Verify Your Payout Account Status** After returning from Stripe, your payout account status will be displayed in Violet Connect: * **Active**: Your account is fully set up and ready to receive payouts * **Pending**: KYC verification is in progress; you may need to provide additional information * **Action Required**: Additional steps are needed in Stripe to complete verification ![Connected Stripe Express Account in Violet Connect](https://res.cloudinary.com/violet/image/upload/v1749584759/docs/violet_connect/VC-Stripe-Express-Account-2.png) {% hint style="info" %} If your account shows "Pending" or "Action Required", click **Go to Stripe** to complete any remaining verification steps. {% endhint %} {% endstep %} {% endstepper %} ## Switching to a Different Payout Account in Violet Connect If you've already connected a payout account during onboarding but need to switch to a different one, you can do so directly from Violet Connect: 1. Navigate to the **Payments** step in Violet Connect 2. Click **Create New Payout Account** below your existing account 3. Follow the same steps above to connect a new Stripe account 4. Once the new account is verified, click the status indicator and select **Make Active** 5. Confirm the switch in the modal that appears {% hint style="info" %} The previous account will become inactive but remains linked to your merchant profile. You can reactivate it later from the [Merchant Dashboard](https://merchant.violet.io/settings/payouts) if needed. {% endhint %} ## Understanding Payout Account Ownership * Each Channel connection has exactly one **active** payout account at any time * You can have multiple payout accounts per Channel, but only one receives payouts * Switching accounts does not affect historical payment records—past distributions remain tied to the original account * Refunds for orders placed before switching will be processed through the original account ## Next Steps After completing your payout account setup in Violet Connect: * Continue with the remaining onboarding steps to complete your Channel connection * Review your payout settings in the [Merchant Dashboard](https://merchant.violet.io/settings/payouts) * Learn more about [Understanding Payouts and Distributions](/interacting-with-violet/getting-paid/understanding-payouts) # Quick Reference #### Account Types Comparison | Feature | Stripe Express | Stripe Standard | | -------------------- | ----------------- | --------------------- | | **Setup Complexity** | 🟢 Simple | 🟡 Moderate | | **Dashboard Access** | Express Dashboard | Full Stripe Dashboard | | **Best For** | New merchants | Existing Stripe users | | **Cross-border** | ✅ Supported | ❌ Limited | | **Onboarding** | Violet-hosted | Self-managed | #### Payout Timeline {% code overflow="wrap" %} ``` Order Placed → Transfer to Stripe → Settlement (Pending→Available) → Stripe Payout → Bank Deposit ↓ ↓ ↓ ↓ ↓ Instant ~30 seconds 2-3 business days Per schedule 1-2 days ``` {% endcode %} {% hint style="info" %} **Understanding "Pending" funds:** After the transfer posts to your Stripe account, funds may show as "pending" for 2-3 business days. This is Stripe's standard card settlement window. The money is already in your Stripe account—it just isn't available for bank payout yet. {% endhint %} #### Common Questions <details> <summary>💰 <strong>When do I get paid?</strong></summary> Payouts follow Stripe's standard schedule: * **New accounts:** 7-day rolling basis after first sale * **Established accounts:** 2-day rolling basis * **Custom schedules:** Available for high-volume merchants </details> <details> <summary>🌍 Can I receive payments in different currencies?</summary> Yes! Violet supports: * Multi-currency payouts through Stripe * Automatic currency conversion * Presentment currency pricing (advanced feature) </details> <details> <summary><strong>🔒 How secure are my banking details?</strong></summary> Your banking information is handled entirely by Stripe: * PCI DSS Level 1 compliant * Bank-grade security * Violet never stores your banking details </details> <details> <summary>🕐 <strong>Why do my funds show as "pending" in Stripe?</strong></summary> This is normal Stripe behavior. When funds are transferred to your Stripe account, they initially show as "pending" while the original card payment settles. This typically takes 2-3 business days. **What "pending" means:** * The transfer from the channel has completed successfully * The funds are in your Stripe account * They just aren't available for bank payout yet **What to check:** * Your Stripe Express dashboard shows both "pending" and "available" balances * Pending funds will automatically move to "available" after settlement * No action is required on your part </details> <details> <summary>⏳ <strong>Why did my bank deposit take longer than expected?</strong></summary> Bank payouts involve multiple steps after funds become available: 1. **Stripe payout initiation**: Based on your payout cadence (2-day or 7-day rolling) 2. **Bank processing**: 1-2 business days for the bank to post the deposit 3. **Weekends/holidays**: Neither Stripe nor banks process on non-business days **Example:** If funds become available on Thursday, Stripe may initiate the payout Thursday evening. Your bank might not show the deposit until Monday if Friday/weekend processing delays apply. **To check your payout schedule:** View your Stripe Express dashboard or contact your channel partner. </details> # Need Help? Quick Solutions * **Account Issues:** Check your Stripe Express dashboard for verification status * **Missing Payouts:** Verify your bank account details in payout settings * **Commission Questions:** Review your commission rates in the Merchant Dashboard #### Get Support * **📞 Technical Issues:** Contact your channel partner for account setup problems * **💬 Business Questions:** Reach out to your channel partner for commission discussions * **📧 Stripe Issues:** Use your Stripe Express dashboard for payment-related questions {% hint style="info" %} 🎯 **Pro Tip:** Use your Merchant Dashboard Messages tab to communicate directly with your connected channels about payout questions. {% endhint %} # Merchant Dashboard {% hint style="warning" %} If you are a channel testing the merchant dashboard in sandbox, go to <https://merchant.violet.dev\\> Click [here](https://github.com/violetio/docs/blob/main/channel-docs/resources/merchant-dashboard.md) for more information {% endhint %} The Violet Merchant Dashboard lets your merchants review the state of their connection to Violet Channels, view Orders placed through the system, and configure their payments. ## Sign In Merchants onboard through [Violet Connect](https://github.com/violetio/docs/blob/main/channel-docs/prism/violet-connect/README.md), which is an onboarding process tailored to your Channel. Once the onboarding process is complete, they can sign into the [Merchant Dashboard](https://merchant.violet.io) for an Overview of the orders placed through their integration with Violet; change their commission rates; or update payout accounts. Enter the same email address used during Violet Connect onboarding. {% hint style="info" %} If the merchant signs in and sees a screen saying "No Store Connected", that means they have not used the email that is tied to their merchant account. Please make sure they are using the same email they signed up with originally in Violet Connect. {% endhint %} ![](/files/sMHbPxWtL6cDvmRFM35d) ## Navigating the Merchant Dashboard There are three main sections to the Merchant Dashboard: 1. Overview (Home) 2. Notifications 3. Messages 4. Commission Rates 5. Payouts 6. Orders 7. Products ### Overview The Overview page is where they can see see information about their connected store, all the Channels they are connected to, and control their commission rates. ![Overview](https://res.cloudinary.com/ddhjp8mca/image/upload/v1742336368/mintlify/merchant-dashboard/m-dash-home.png) ### Notifications The Notifications page is where merchants can manage all the notifications that they have received such as from completed report notifications and commission rate updates. ![Notifications Tab](https://res.cloudinary.com/ddhjp8mca/image/upload/v1742336367/mintlify/merchant-dashboard/m-dash-notifications.png) ### Messages The Messages tab enables direct communication with your connected channels. From here, you can initiate and manage conversations with channels in real-time. ![Messages Tab](https://res.cloudinary.com/ddhjp8mca/image/upload/v1742336368/mintlify/merchant-dashboard/m-dash-messages.png) ### Commission Rates The Commission Rates tab displays historical commission rate changes for the merchant's connected apps. You can:\ \- View a chronological log of all rate changes\ \- Filter changes by specific channels ![Commission Rates Tab](https://res.cloudinary.com/ddhjp8mca/image/upload/v1742336367/mintlify/merchant-dashboard/m-dash-commission-rates.png) ### Payouts The Payouts page is merchants can see all the financial transactions related to their orders. Each payout entry includes:\ \- A detailed summary of the transaction\ \- Related distribution records\ \- Transaction status and timeline\ \- They can also access a dedicated Distributions tab for a more comprehensive view of money earned across orders. ![Payouts Tab](https://res.cloudinary.com/ddhjp8mca/image/upload/v1742336369/mintlify/merchant-dashboard/m-dash-payouts.png) #### Distributions Tab The Distributions tab provides a comprehensive view of all distributions across your orders. ![Distributions Tab](/files/jAMnwLkp89IaPJL6gY13) You can click on any distribution to view its details. ![Distribution Detail](/files/fNU2ceciWEq8bhfqvSjH) #### Transfers Tab The Transfers tab shows all transfers associated with your payouts. ![Transfers Tab](/files/gy6EDtfoWIfdjXMWBGNd) You can click on any transfer to view its details. ![Transfer Detail](/files/kuy85zrcbz7P5X9RqlOM) ### Orders The Orders dashboard is where they can see all orders that have been placed through their integrations with Violet, including the state that they are in. ![Orders Tab](/files/j1718VCfpwMEzw7IHm77) #### Adding Fulfillment & Tracking Details When you select an order, the detail view shows your items in two sections: * **Unfulfilled** — items that have not yet been shipped. * **Fulfilled** — items that have been shipped, along with their tracking details. **Adding Tracking** 1. Open an order and click **+ Add Tracking** in the Unfulfilled section. 2. Review the order summary (order number, date, and shipping address). 3. In the **Items** section, confirm the quantity of each item you are shipping. You can adjust quantities to create a partial fulfillment if you are shipping items in multiple shipments. 4. Under **Tracking**, fill in the required fields: * **Carrier** (required) — select from the dropdown: UPS, USPS, FedEx, DHL, OnTrac, Royal Mail, Sendle, PostNord, Yun Express, or Other. * **Tracking Number** (required) — enter the tracking number provided by the carrier. * **Tracking URL** (optional) — enter a direct link to the tracking page. 5. Click **Add Tracking** to submit. The items move to the Fulfilled section, where you and your connected channels can view the carrier, tracking number, and tracking link. **Editing Tracking** To update tracking details for an already-fulfilled shipment, click the **pencil icon** next to the tracking number in the Fulfilled section. In the Edit Tracking modal, you can change the carrier, tracking number, or tracking URL, then click **Save Changes**. **Partial Fulfillment** If you are shipping an order in multiple packages, you can fulfill a subset of items at a time. Each time you add tracking, only the remaining unfulfilled items are shown. Repeat the process for each shipment until all items are fulfilled. ### Products (Publishing) The Products page is where they can see all the products that they have synced into Violet. Here they can `Publish` or `Unpublish` products to sell through your Channel. {% hint style="info" %} Unpublishing a product makes it inaccessible to any connected channel. An product that is 'published' simply means that it is accessible to a Channel. Violet maps statuses from their e-commerce platform and honors configurations that set a product to disabled, not for sale, out of stock, hidden, archived, etc.\ Just because a product is published does not mean that a channel will be able to purchase that product. {% endhint %} ![Products Tab](/files/ERepZdOJEeIfXtsWJQrE) ## Account Settings To access and modify account settings, they can click on “Violet User” in the bottom left corner and click Settings. ![Account settings link](https://res.cloudinary.com/ddhjp8mca/image/upload/v1742336372/mintlify/merchant-dashboard/m-dash-account-settings-link.png) Here, you can navigate to the payouts tab to manage your payout account settings. For more information on how to setup and manage payout accounts, please see [this guide](https://github.com/violetio/docs/blob/main/channel-docs/prism/payments/payouts/prism-payout-accounts/README.md). # Refunding An Order Refunding a Violet Order is the same as any other order When a customer contacts a merchant wishing for a refund on an order that was placed through Violet, the merchant will be able to easily service that request without leaving their ecommerce platform. All that is required is to follow the standard refund process for an order in your ecommerce platform, with the end goal of changing the state of that order to "refunded". Violet will take it from there. {% hint style="info" %} All that is required by the merchant is to mark the order refunded in their e-commerce platform, the merchant does *not* need to initiate any funds transfers, even if they would usually do that for a native order. {% endhint %} As a part of the standard Violet e-commerce integration, Violet subscribes to webhook notifications for refunds, processing each when they are received. So once the merchant has marked the order as refunded, Violet will process that refund, reversing all funds transferred to the merchant and channel and returning the funds to the shopper's payment method. Funds should appear on the shopper's card within 5-10 business days. ## Special Platform Specific Considerations Certain e-commerce platforms have special limitations and considerations that impact and alter the basic Violet returns and refund flow. ### Shopify Beyond the usual process for [refunding an order](/interacting-with-violet/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](#violet-refund-and-return-flow) ![cancel-order.png](/files/TADRAUdSp98hDbryBRPC) *** ### Ecwid The Ecwid platform, as a rule, does not allow for an order placed via the API, as Violet does, to be refunded in the same way that an order placed on the storefront may be refunded.\ This means that for Violet Orders, the Ecwid interface refund button that can typically be used to start a refund is not able to be used. Instead, simply mark any Violet orders as `refunded` or `cancelled` when the order is refunded and Violet will treat it as a full refund. *** ### Sales Force Commerce Cloud As there is no concept of refunds in both the OCAPI and SCAPI, Violet is unable to be notified of refunds or access any refund data. As a temporary workaround, you will need to perform one of the following steps. **Option 1: Mark Order as Cancelled**\ This option requires the least amount of effort. Simply mark any Violet orders as `cancelled` when the order is refunded and Violet will treat it as a refund. **Option 2: Notify Violet of Refunds**\ This option will likely require the involvement of your engineering team. When a refund occurs, you will need to send information about the refund to Violet so that it can process the refund accordingly. If you choose this option, the integration documentation will be shared with you by Violet or the channel that onboarded you. **Whats Next**\ Violet will begin integrating with the order management systems that you connect to your Salesforce Commerce Cloud stores. Once we have an integration with the OMS you use you will be able to remove/skip the above fallback options as Violet will be able to discover refunds automatically. *** ### Wix {% hint style="warning" %} The below ONLY applies to orders placed **before** 2024-04-22. All orders placed afterward can be refunded via the standard process. See our [release notes](https://docs.violet.io/changelog) for more details. {% endhint %} {% hint style="info" %} The Order API on the WIX platform is currently in its early stages and comes with certain limitations concerning order refunds. Consequently, it is essential to carefully follow these specifics steps to ensure a comprehensive and successful refund for your customers. {% endhint %} #### Unfulfilled Order \ In the event that an order is still undergoing processing and has not yet been shipped, initiating a refund can be accomplished by canceling the order. **Step 1**: Go to Actions ![Cancel Action](/files/zBdLB2shchBJLL5reVi7) **Step 2**: Cancel Order ![Cancel Order](/files/6P8ZOlJlcqfXELs3dmQW) **Step 2.5**: Confirm Cancel ![Cancel Order](/files/4KAuPIziiIbLRVS9Ab3S) **Previously Fulfilled Order** Once an order has been dispatched, it is necessary to unfulfill it before you can proceed with initiating a refund by canceling the order. **Step 1**: Go to Actions ![Unfulfill Action](/files/f4o6123hoBny12CaDk8T) **Step 2**: Unfulfill Order\ As soon as you select the option `Mark as fulfilled`, the order status will promptly be updated to `UNFULFILLED`. You can see this below: ![Unfulfilled Status](/files/h0bA7S8FX6oWPf7aNsHm) **Step 3**: Follow Steps from `Unfulfilled Order` above. ## Violet Refund and Return Flow See the below diagram for how Violet handles the refund and return flows {% embed url="<https://www.figma.com/embed?embed_host=astra&url=https://www.figma.com/file/RN5JKLIVwZ8yLZgiBpPX3W/DIAGRAM%3A-Returns-%2B-Refunds>" %} # Canceling an Order From the merchants system, canceling a Violet Order is the same as canceling a traditional order. When a merchant chooses to not accept and fulfill an order they must cancel it from within their existing system (commerce platform). If an order is not canceled and is left unfulfilled it will likely result in a chargeback from the cardholder. If a shopper requests order cancelation from a merchant before the order has been fulfilled the merchant can cancel it from within their system and Violet will be made aware of the cancelation automatically. {% hint style="info" %} All that is required by the merchant is to mark the order as canceled in their e-commerce platform. The merchant does *not* need to initiate any manual transfer of funds, even if they would usually do that for a traditional order. {% endhint %} As a part of the standard Violet e-commerce integration, Violet subscribes to webhook notifications for cancelations, processing each when they are received. Once the merchant has marked the order as canceled, Violet will process that cancelation, reversing all funds transferred to the merchant and channel and returning the funds to the shopper's payment method. Funds should appear on the shopper's card within 5-10 business days. *** ## Special Platform Specific Considerations Certain e-commerce platforms have special limitations and considerations that impact and alter the basic Violet cancelation flow. ### Shopify A Shopify merchant must create a refund in their Shopify admin before canceling the order. Without first performing this step the cardholders transaction may not be reversed. ### Ecwid An Ecwid merchant must set the **Payment Status** to `Cancelled` or `Refunded`. Simply setting the **Fulfillment Status** to `Delivery Canceled` is not suficient. *** ## Channel Initiated Cancelations Channels (Apps) also have the ability to cancel an order that they originated if that order has not yet been fulfilled. When a channel cancels an order it will be marked as canceled in the merchants existing system (commerce platform). Any transactions will be reversed, so the fincancial status of the order will reflect that it has been refunded. Common reasons for a channel to perform this action are shopper fraud or a merchant not fulfilling an order. # Understanding Adjustments Learn how Violet handles post-order corrections to shipping, tax, and discounts Sometimes after an order is placed, corrections need to be made to shipping costs, tax amounts, or discounts. Violet handles these corrections through **Order Adjustments** - immutable audit records that track changes without modifying the original order. ## What Are Adjustments? Adjustments are financial corrections applied to an order after it has been submitted. They create a transparent audit trail of any changes made to: * **Shipping costs**: When the estimated shipping at checkout differs from actual carrier rates * **Tax amounts**: When tax calculations need correction due to jurisdiction issues * **Discounts**: When promotional credits are applied post-order {% hint style="info" %} Adjustments are different from refunds. A refund returns money for returned or cancelled products. An adjustment corrects a billing error without affecting the products in the order. {% endhint %} ## When Do Adjustments Happen? ### Automatic Shipping Reconciliation Violet can automatically monitor for shipping cost discrepancies before transferring funds to your payout account. If the shipping amount charged at checkout differs significantly from the actual rate (by more than $3.00), Violet creates an adjustment to correct the difference. **Example**: A customer was charged $12.00 for shipping at checkout, but the actual carrier rate was $8.50. Violet detects this $3.50 discrepancy and creates an adjustment so the correct amount flows to your payout. {% hint style="info" %} Your app must be configured for automatic shipping reconciliation for this feature to be enabled. Please contact the Violet Support team to learn more. {% endhint %} ### Manual Corrections In some cases, Violet support may create adjustments to correct billing discrepancies identified after an order was placed. You'll see these reflected in your distributions. ## How Adjustments Affect Your Payouts When an adjustment is created, it generates a new **ADJUSTMENT distribution** that appears alongside your regular payment distributions. This adjustment amount is included in your next payout transfer. ### Key Points About Adjustment Distributions | Aspect | How It Works | | ------------------ | -------------------------------------------------------------------------------------------------------- | | **Commission** | Adjustments do NOT recalculate commission. Your commission rate was applied to the original transaction. | | **Payout timing** | Adjustment distributions are batched with your regular payouts on the standard 2-day rolling schedule. | | **Visibility** | You can see adjustment distributions in your Merchant Dashboard under the Distributions view. | | **Reconciliation** | Adjustment distributions have the same Order ID as the original payment, making them easy to match. | ### Example Adjustment Flow 1. **Original Order**: Customer places a $100 order with $10 shipping 2. **Payment Distribution**: You receive a PAYMENT distribution for your portion (e.g., $95 after commission) 3. **Shipping Correction**: Actual shipping was $7, not $10 4. **Adjustment Created**: A $3 SHIPPING\_TOTAL adjustment is created 5. **Adjustment Distribution**: A new ADJUSTMENT distribution for $3 is added to your next payout ## Viewing Adjustments in the Dashboard To see adjustments affecting your orders: 1. Navigate to the **Merchant Dashboard** 2. Go to the **Distributions** section 3. Look for distributions with type **ADJUSTMENT** 4. Click on a distribution to see details including the `adjustment_id` You can also view adjustments in the **Transfer Details** page, which shows a breakdown of all distributions (PAYMENT, REFUND, and ADJUSTMENT) included in each transfer to your bank. ## Adjustments vs. Refunds | Scenario | Use Adjustment | Use Refund | | ------------------------------------ | -------------- | ---------- | | Shipping was overcharged at checkout | Yes | No | | Tax was calculated incorrectly | Yes | No | | Customer wants to return a product | No | Yes | | Order needs to be cancelled | No | Yes | | Post-order promotional credit | Yes | No | If a customer contacts you about returning products or cancelling an order, follow the standard [refund process](/interacting-with-violet/refunding-an-order) in your ecommerce platform. Adjustments are handled automatically by Violet for billing corrections. ## Common Questions ### Will I be notified when an adjustment is created? Adjustment distributions appear in your Merchant Dashboard and are included in your regular payout transfers. Currently, there is no separate notification for adjustments - they flow through with your normal distributions. ### Can I dispute an adjustment? If you believe an adjustment was created in error, contact Violet support with the order ID and adjustment details. Our team will review the adjustment and work with you to resolve any discrepancies. ### Do adjustments affect my commission rate? No. Commission is calculated on the original transaction at the time of payment. Adjustments correct billing errors but do not trigger commission recalculation. ### How do I reconcile adjustments with my records? Adjustment distributions include the same `order_id` and `external_order_id` as the original payment. In your Stripe Dashboard, you'll see the adjustment as a separate transfer line item associated with the same order.