Stores

A store is the tenancy root of Feeef — products, orders, shipping prices, integrations and finance all hang off a store id. This page covers the store resource itself: CRUD and lookup, the member/RBAC model, invites, custom domains, the draft template preview, and the small analytics surfaces (summary, chart, leaderboard). Conventions (pagination, filterator, errors) are documented in API conventions; webhook management lives in Webhooks.

At a glance

Store resource

Analytics & settings surfaces

Store settings (name, logo, configs, shipping defaults, decoration) are plain fields on the store document — edit them with PUT /v1/stores/{id}. Integration configs are a separate surface under /v1/stores/{id}/integrations/{key} gated by the store.integrations scope.

Members

Invites

Custom domains

Template preview (draft themes)

Used by the CLI feeef dev flow — see Templates for the data model.

Roles & member scopes

Every store has one owner (store.userId) with full access. Additional members carry a role and an optional scopes array:

Scopes narrow what a member (or an OAuth token — the vocabulary is shared, see Scopes) can touch. Canonical values: store, store.read, store.settings, store.integrations, store.members, orders, orders.read, products, products.read, categories, categories.read, pages, pages.read, product_landing_pages, product_landing_pages.read, shipping_prices, shipping_prices.read, template_components, template_components.read, store_templates, store_templates.read, finance, finance.read, inventory, inventory.read.

Hierarchy rules:

• * and store grant everything.
• A parent scope implies its .read child (orders ⇒ orders.read).
• store.integrations additionally implies the integration-gated modules (inventory*, finance*).
• Empty/missing scopes on a member = legacy full access (backward compatible). An empty scope list on an access token denies everything.

Look up a store by slug or domain

The show endpoint resolves {id} against id, slug, and custom domain in one query. Pass by=slug or by=domain.name to force a column:

curl "https://api.feeef.org/v1/stores/my-shop?by=slug" \
  -H "Accept: application/json"

Responses are the store's public JSON: integration secrets are stripped for non-members, and subscription/members are only present for members (and platform admins). Optional includes: with=lor (lite orders report) and with=template (resolved theme document).

Add a member with scopes

curl -X POST "https://api.feeef.org/v1/stores/{storeId}/members" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "teammate@example.com",
    "role": "confermer",
    "scopes": ["orders", "products.read"]
  }'

The user must already have a Feeef account (lookup is by email) — otherwise use an invite, which works for people without an account yet.

Invite flow

# Create (owner)
curl -X POST "https://api.feeef.org/v1/stores/{storeId}/invites" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "new-hire@example.com", "role": "editor" }'

# Accept (invitee, token from the email link or GET /v1/me/store-invites)
curl -X POST "https://api.feeef.org/v1/stores/{storeId}/invites/{inviteId}/accept" \
  -H "Authorization: Bearer $INVITEE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "token": "..." }'

Attach a custom domain

curl -X POST "https://api.feeef.org/v1/stores/{storeId}/domain" \
  -H "Authorization: Bearer $FEEEF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "shop.example.com" }'

# Then poll until verified
curl "https://api.feeef.org/v1/stores/{storeId}/domain/status" \
  -H "Authorization: Bearer $FEEEF_TOKEN"

The add call registers the domain with the hosting layer and returns the DNS records to create. check-dns performs real public-DNS lookups and automatically runs verification once every record resolves; status is the cheap polling endpoint. Domain names are unique across Feeef — attaching a domain already used by another store fails with 400.

Notes

• Creation trial: POST /v1/stores activates a Pro trial (7 days, unlimited orders, subscription.metadata.trial = true).
• Caching: list and show responses are cached server-side per user. Mutations bust the cache; role/scope edits invalidate the member-access cache immediately.
• Security block: POST /v1/stores/{id}/integrations/security/block (Bearer) sets the same rate-limit keys used by public checkout for a given order's customer — a moderation tool for blocking abusive phone numbers/IPs.
• Webhooks and integrations under /v1/stores/{storeId}/integrations/... require the store.integrations scope and are documented in Webhooks.