REST API overview

The REST API is the conventional HTTP surface — the same operations the dashboard editor uses, exposed under /api/storefront/v1/. It splits into two halves:public storefront endpoints for buyers and merchant endpoints behind scoped bearer auth for operators.

At a glance

Storefront half

Public endpoints for reading the catalog and running checkout. No bearer required.

• Catalog — stores, products, collections, search.
• Cart + checkout — create cart, manage items, apply coupons, initiate Stripe checkout.

Merchant half

Scoped endpoints for managing products, orders, customers, webhooks, media, analytics.

• Orders + fulfillment — list orders, fulfill, refund, return, exchange.
• Merchant management — products, customers, customer groups, price lists, webhooks, analytics.

Status codes

Pagination

List endpoints accept ?limit=&cursor= and return next_cursorwhen more pages are available. Cursors are opaque; don't try to parse them.

1curl "https://aly.store/api/storefront/v1/stores/acme/products?limit=20"

Errors

1{2  "error": {3    "code": "validation_failed",4    "message": "Body did not pass validation.",5    "details": [6      { "path": "line_items.0.quantity", "code": "too_small", "min": 1 }7    ]8  }9}

Next steps

• Authentication — bearer details for merchant endpoints.
• Catalog endpoints — read products and collections.
• Cart + checkout — buyer-side state.
• Orders + fulfillment — merchant-side state machine.
• Merchant management — everything else.