Permissions & Scopes

Mercentia uses granular, scope-based permissions. Apps must declare the permissions they need upfront, and merchants approve them during installation. Follow the principle of least privilege — only request what your app actually uses.

How Permissions Work

You declare required permissions in your app submission
Merchants see exactly what your app can access before installing
The OAuth token is scoped to only the approved permissions
API calls to resources outside your granted scope return 403 Forbidden
Merchants can revoke access at any time by uninstalling

Scope Reference

Products & Catalog

Scope	Access	What It Grants
`read_products`	Read	View products, variants, images, pricing, tags, collections, categories
`write_products`	Read + Write	Create, update, and delete products. Manage variants, images, and collections

Orders & Fulfillment

Scope	Access	What It Grants
`read_orders`	Read	View orders, line items, payments, refunds, fulfillment status
`write_orders`	Read + Write	Update orders, add notes and tags, create draft orders
`manage_fulfillments`	Write	Create fulfillments, add tracking numbers, update shipment status
`manage_checkouts`	Write	Modify checkout flow, add custom fields, apply discounts at checkout

Customers

Scope	Access	What It Grants
`read_customers`	Read	View customer profiles, addresses, order history, tags. Subject to GDPR/CCPA
`write_customers`	Read + Write	Create and update customers, manage tags. Requires DPA and privacy compliance

Inventory & Shipping

Scope	Access	What It Grants
`read_inventory`	Read	View stock levels, locations, reorder points
`write_inventory`	Read + Write	Adjust stock levels, set reorder points
`read_shipping`	Read	View shipping zones, rates, carriers, tracking info
`write_shipping`	Read + Write	Generate labels, update tracking, configure carriers

Marketing & Discounts

Scope	Access	What It Grants
`read_discounts`	Read	View discount codes, promotions, gift cards
`write_discounts`	Read + Write	Create and manage discount codes, promotions

Content & Store

Scope	Access	What It Grants
`read_content`	Read	View pages, blog posts, navigation menus
`write_content`	Read + Write	Create and edit pages, blog posts, navigation
`read_analytics`	Read	View sales data, traffic, conversion rates, top products
`read_store_settings`	Read	View store name, domain, currencies, languages, tax config

Data Protection Notes

Customer data is sensitive. Apps requesting read_customers or write_customers must:

Have a signed Data Processing Agreement (DPA)
Comply with GDPR Article 28 (processor obligations)
Implement right to erasure — when a customer requests deletion, your app must delete their data within 30 days
Never sell, share, or use customer data for purposes other than app functionality
Disclose all data processing in your privacy policy

Common Rejection Reasons (Permissions)

Over-requesting: App requests write_customers but only displays customer data (should use read_customers)
Unnecessary scopes: A shipping label app requests read_analytics — not relevant to its function
Missing justification: App requests sensitive scopes without explaining why in the submission form
Missing DPA: App requests customer data scopes without a signed Data Processing Agreement