Browse documentation

Reference

Storefront API reference

Webtools Storefront API 0.1.0. 79 endpoints across 18 resource groups, generated from the production OpenAPI contract.

Resource groups

Resolve a project by slug or custom domain and read its public configuration — name, default currency, enabled features and branding. Call this first to discover which other resource groups are available.

3 endpoints

Catalogue

Read the published product catalogue: products and their variants, product categories and collections. Supports search, category and collection filters, price range, brand, product type and featured filters.

4 endpoints · requires the commerce feature

Carts

Create an anonymous cart, add and update line items, and read the current cart with computed totals. Carts are identified by the X-Cart-Token returned when the cart is created.

4 endpoints · requires the commerce feature

Shipping

List the shipping methods a project offers so a shopper can choose one before checkout.

1 endpoint · requires the commerce feature

Checkout

Validate the current cart and create the order and payment records in one call. The response contains the order reference and the resolved line items and totals.

1 endpoint · requires the commerce feature

Customers

Register and log in project-scoped storefront customers, manage their addresses, and read their order history. Customer accounts are per project and are never the same as Webtools dashboard accounts.

4 endpoints · requires the commerce feature

Blog & content

Read published editorial content: posts with pagination and full-text search, categories, tags, authors, featured posts, and the blog landing configuration.

11 endpoints · requires the blog feature

Subscribers

Let a storefront capture newsletter subscribers and process unsubscribe requests. Submissions are attributed to the project.

2 endpoints · requires the newsletter feature

Services

Read a business's published service catalogue — pricing type, deliverables, media and calls to action — and record view or enquiry events against a service.

3 endpoints · requires the services feature

Past works

Read a published portfolio of past works or case studies, with galleries and metadata, and record view or click events against an item.

3 endpoints · requires the past_works feature

Landing pages

Read published landing page layouts and the entries that fill them. Each entry is one URL, with SEO, theme colors, and values for that layout's blocks.

4 endpoints · requires the landing_pages feature

Enquiries

Submit a typed enquiry from a storefront — contact, product enquiry, quote request, service request, support or wholesale. Submissions land in the project's enquiry inbox and can flow into CRM.

1 endpoint · requires the custom_queries feature

Forms

Read public form metadata and submit freeform JSON payloads to a named form slug. Field keys are owned by your storefront and can change over time; the dashboard renders a dynamic submissions table.

2 endpoints · requires the forms feature

Storefront events

Record lightweight storefront analytics events — page and resource views, searches and clicks — for the project's insights dashboards.

1 endpoint · requires the analytics feature

Files

Serve a media file by its opaque file key. Used for images and documents referenced by other resources.

1 endpoint

Platform

Service metadata endpoints that are not project-scoped.

1 endpoint

Storefront Agent

2 endpoints

Storefront Writes

31 endpoints

Pagination

List endpoints accept page and page_size query parameters (1-based) and return an envelope with items and pagination metadata.

Parameter	Type	Notes
`page`	integer	1-based page number. Default 1.
`page_size`	integer	Items per page. Endpoint-defined maximum.

List response envelope

{
  "items": [ /* … */ ],
  "meta": {
    "page": 1,
    "page_size": 20,
    "total": 137,
    "total_pages": 7
  }
}

Errors

Errors use standard HTTP status codes with a JSON body. FastAPI validation errors return a detail array; application errors return a message and a short code.

Error body

{
  "message": "Human readable summary.",
  "code": "rate_limited"
}

Status	Meaning
`400`	Malformed request.
`401`	Missing or invalid key or customer token.
`403`	Valid key without the required scope, or a secret key sent from a browser origin.
`404`	Unknown project or resource, or the project feature is disabled.
`409`	Conflict — most often a slug that already exists, or a replayed Idempotency-Key with a different body.
`422`	Request body or query parameters failed validation.
`429`	Rate limit exceeded. Retry after the Retry-After header.

Rate limits

Public storefront routes are rate limited per client IP and per key fingerprint. Agent write and seed routes allow 30 requests per minute. A 429 response includes Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.

Machine-readable spec

For code generation and tooling, the OpenAPI 3.1 document is published at https://api.webtools.ng/openapi.storefront.json. These pages are the readable contract; do not infer fields from marketing copy.