API Keys
Merchants create, scope, revoke, and operationally rotate integration credentials from the merchant portal.
Keys are merchant-managed and shown once.
When a merchant creates a key, Rarely displays the secret once and stores only a hash. Merchants can label keys for systems like warehouses or analytics tools, optionally restrict them to specific fulfillment locations, and revoke them at any time.
Scopes are capability-based, not role-based.
Instead of broad access roles, keys are granted explicit capabilities like orders.read, inventory.adjust, or fulfillments.create. That keeps integrations narrowly scoped to the actions they actually need.
Merchant context
Read merchant profile, handle, brand-safe context, vendors, tags, and approval policy.
merchant.read
Brand
Access and manage merchant brand identity and brand media.
brand.read
brand.write
Vendors
Access and manage merchant vendors and their brand overrides.
vendors.read
vendors.write
Tags
Access and manage merchant tags used across catalog, orders, and customers.
tags.read
tags.write
Orders
Access merchant orders, line items, and fulfillment-ready shipping details.
orders.read
orders.tags.write
orders.cancel
Products
Access and manage native products, variants, SKUs, media, and catalog data.
products.read
products.write
products.submit
products.visibility.write
products.delete
Variants
Access and manage product variant rows, SKU options, prices, and sellability settings.
variants.read
variants.write
Bundles
Access and manage bundle definitions, slots, options, perks, and bundle presentation.
bundles.read
bundles.write
bundles.submit
Collections
Access and manage native collections, product assignments, rules, and tags.
collections.read
collections.write
collections.submit
collections.visibility.write
collections.delete
Media
Access and manage merchant media assets for catalog and landing pages.
media.read
media.write
media.delete
Landing pages
Access and manage merchant landing page drafts and submissions.
landing_pages.read
landing_pages.write
landing_pages.submit
landing_pages.delete
Landing page templates
Access and manage reusable merchant landing page templates.
landing_page_templates.read
landing_page_templates.write
Social videos
Access and manage native social videos and their product or collection links.
social_videos.read
social_videos.write
social_videos.submit
social_videos.visibility.write
social_videos.delete
Fulfillment locations
Access and manage merchant fulfillment locations and location assignment rules.
fulfillment_locations.read
fulfillment_locations.write
Inventory
Read stock by fulfillment location and apply merchant-scoped inventory adjustments.
inventory.read
inventory.write
inventory.adjust
inventory.set
Fulfillments
Read fulfillment state and create or update merchant-native fulfillments.
fulfillments.read
fulfillments.write
fulfillments.create
fulfillments.update
fulfillments.tracking.write
fulfillments.cancel
Shipping
Access and manage shipping profiles, zones, rates, carrier rates, and checkout rules.
shipping.read
shipping.write
shipping_labels.quote
shipping_labels.purchase
Return policies
Access and manage merchant return policies and product or collection assignments.
return_policies.read
return_policies.write
Returns
Access and manage return requests, return shipments, and return lifecycle events.
returns.read
returns.write
Refunds
Access refund state and create merchant-initiated refunds.
refunds.read
refunds.create
Customers
Access and manage merchant-visible customer profiles and tags.
customers.read
customers.write
Audience
Read customer follows and wishlists for merchant relationship workflows.
followers.read
wishlists.read
Customer groups
Access and manage customer segments, segment memberships, and group pricing.
customer_segments.read
customer_segments.write
customer_prices.read
customer_prices.write
Pricing rules
Access and manage merchant pricing rules and quantity tier behavior.
pricing_rules.read
pricing_rules.write
Discounts
Access and manage coupons, discount qualification rules, and gift cards.
discounts.read
discounts.write
gift_cards.read
gift_cards.write
Analytics and finance
Read merchant analytics, ledger entries, payout batches, and finance summaries.
analytics.read
finance.read
payouts.read
ledger.read
Integrations
Access and manage connected integration records and operational sync settings.
integrations.read
integrations.write
Webhooks
Access and manage outbound webhook endpoints, test deliveries, and replays.
webhooks.read
webhooks.write
webhooks.test
webhooks.replay
API keys
Access and manage merchant integration API keys.
api_keys.read
api_keys.write
AI agents
Access and manage merchant AI agent setup and agent API keys.
ai_agents.read
ai_agents.write
Team
Access and manage merchant team members and roles.
team.read
team.write
Settings
Access and manage merchant account settings.
settings.read
settings.write
Rotate operationally: create a new key, update the external system, revoke the old key.
V1 does not expose a dedicated rotate endpoint. The safe rotation workflow is to create a replacement key with the same scopes, update the downstream system, validate traffic, then revoke the old key.