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