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.