Skip to main content
Get started
REST APIMerchant management
REST API

Merchant management

Automate the merchant back office without opening the dashboard.

Products, customers, customer groups, price lists, webhooks, media, analytics — everything operator-side except orders.

Everything operator-side that isn't orders: products, customers, customer groups, price lists, webhooks, media, analytics. All under/api/storefront/v1/merchant/; all require a bearer with the appropriate scope.

Products

List

bash
curl "https://aly.store/api/storefront/v1/merchant/products?site_slug=acme&limit=25" \  -H "Authorization: Bearer aly_..."

Create

bash
curl -X POST https://aly.store/api/storefront/v1/merchant/products \  -H "Authorization: Bearer aly_..." \  -H "Content-Type: application/json" \  -d '{    "site_slug": "acme",    "name": "Linen Tote",    "slug": "linen-tote",    "price": { "amount": 4200, "currency": "USD" },    "variants": [      { "options": { "color": "natural" }, "stock": 25, "sku": "LT-NAT" }    ],    "tags": ["bags", "linen"]  }'

Update

bash
curl -X PATCH https://aly.store/api/storefront/v1/merchant/products/prod_abc \  -H "Authorization: Bearer aly_..." \  -H "Content-Type: application/json" \  -d '{ "price": { "amount": 3900, "currency": "USD" } }'

Delete

bash
curl -X DELETE https://aly.store/api/storefront/v1/merchant/products/prod_abc \  -H "Authorization: Bearer aly_..."

Customers

  • GET /merchant/customers — paginated list with optional email= + group_id= filters.
  • GET /merchant/customers/{id} — single profile with order summary.
  • PATCH /merchant/customers/{id} — update name, address book.

Customer groups

Segments used by price lists and gated content.

  • GET /merchant/customer-groups
  • POST /merchant/customer-groups — create.
  • POST /merchant/customer-groups/{id}/members — assign a customer.
  • DELETE /merchant/customer-groups/{id}/members/{customerId} — remove.

Price lists

Customer-group-targeted pricing overrides.

bash
curl -X POST https://aly.store/api/storefront/v1/merchant/price-lists \  -H "Authorization: Bearer aly_..." \  -H "Content-Type: application/json" \  -d '{    "site_slug": "acme",    "name": "Wholesale",    "customer_group_id": "grp_whole",    "rules": [      { "type": "percent_off", "value": 30 }    ],    "active": true  }'

Webhooks

Register and inspect endpoints. See Webhooks for the full delivery contract.

  • GET /merchant/webhooks
  • POST /merchant/webhooks — register a URL + event list.
  • DELETE /merchant/webhooks/{id}
  • GET /merchant/webhooks/{id}/deliveries — delivery log.
  • POST /merchant/webhooks/{id}/deliveries/{deliveryId}/replay

Media

R2-backed assets — images, videos, downloadable digital files.

  • GET /merchant/media/assets
  • POST /merchant/media/assets/upload-url — request a signed PUT URL for direct R2 upload.
  • POST /merchant/media/assets — finalize after the upload completes.
  • DELETE /merchant/media/assets/{id}

Analytics

bash
curl "https://aly.store/api/storefront/v1/merchant/analytics/metrics?site_slug=acme&range=30d" \  -H "Authorization: Bearer aly_..."

Two read endpoints:

  • GET /merchant/analytics/metrics — visits, conversions, revenue, by date range.
  • GET /merchant/analytics/activity — recent events (orders, customer signups, fulfillments).
One workspace at a time
Every merchant endpoint operates within the bearer's workspace. To run analytics across two workspaces, mint two keys — the API intentionally doesn't allow cross-workspace queries.

Coupons + memberships

Coupons and memberships are accessible via MCP (coupons.*, memberships.*) and the editor UI. REST endpoints for them are part of the OpenAPI surface — see openapi.json for current shapes.

Updated

Was this page helpful?