Storefront

The Storefront API powers Cloove’s public, hosted storefronts: browsing products, viewing promotions, placing an order, and paying for it. These endpoints are public - no API key is required - and are identified by the store’s URL slug.

All endpoints share the prefix /api/storefronts/:slug.

Storefront endpoints are unauthenticated and rate-limited per IP (100 req/min). Don’t expose anything here you wouldn’t put on a public web page.

Browse

Endpoint	Description
`GET /api/storefronts/:slug`	Storefront profile (name, branding, contact)
`GET /api/storefronts/:slug/products`	Product catalog
`GET /api/storefronts/:slug/featured`	Featured products
`GET /api/storefronts/:slug/on-sale`	Products currently discounted
`GET /api/storefronts/:slug/promotions`	Active promotions

Get a storefront


GET /api/storefronts/:slug


{
  "id": "s1a2b3c4-...",
  "name": "Acme Foods",
  "slug": "acme-foods",
  "description": "Fresh meals, delivered.",
  "logo": "https://...",
  "banner": "https://...",
  "contact": {
    "phone": "+2348012345678",
    "email": "store@acmefoods.com",
    "address": "123 Marina, Lagos"
  }
}

Place an order


POST /api/storefronts/:slug/orders

Creates an order from the public storefront.

Body


{
  "customer": {
    "name": "Ada Lovelace",
    "phone": "+2348012345678",
    "email": "ada@example.com"
  },
  "items": [
    { "productId": "p1a2b3c4-...", "variantId": "v1a2b3c4-...", "quantity": 2 }
  ],
  "notes": "Leave at the gate"
}

Pay for an order

After placing an order, drive payment with these endpoints:

Endpoint	Description
`POST /api/storefronts/:slug/orders/:orderId/bank-transfer`	Start a bank-transfer payment
`GET /api/storefronts/:slug/orders/:orderId/check-payment`	Check payment status
`POST /api/storefronts/:slug/orders/:orderId/refresh-payment`	Refresh expired payment details
`POST /api/storefronts/:slug/orders/:orderId/cancel-payment`	Cancel an unpaid order
`GET /api/storefronts/:slug/orders/:orderId/events`	Payment timeline events

Prefer reacting to webhooks over polling check-payment. The Checkout API covers payment links created outside a storefront.