Endpoints are organised by domain:

• Authentication - /auth/login, /auth/logout, /auth/token
• Products - product detail, variants, media
• Categories - navigation, merchandising, collections
• Cart - cart lifecycle, line items, promotions
• Orders - order detail and history
• Customers - profiles, addresses, preferences
• Content - CMS-driven marketing content
• Search - search suggestions and queries
• Health - readiness and liveness endpoints

Check out our development quickstart guide.

All API requests should be made to this base URL. See Environments for staging and development URLs.

Public endpoints require no authentication. These include:

• Product and category browse
• Search suggestions
• CMS content and static pages

These endpoints do not expose PII and can be cached at the edge.

Customer flows (cart, checkout, orders, profile) require a BFF session token obtained via login.

Login flow

1. Call POST /auth/login with credentials and reCAPTCHA response
2. Receive accessToken, tokenType, expiresIn, and customer object
3. Include the token in X-BFF-Token header on subsequent requests

The login response contains:

accessTokenstringrequired

JWT token to include in subsequent requests.

tokenTypestringrequired

Token type, always "Bearer".

expiresInintegerrequired

Token validity in seconds.

customerobjectrequired

Customer profile object with id, emailAddress, firstName, lastName.

Include the token in the X-BFF-Token header for all authenticated requests.

• expiresIn indicates token validity in seconds
• 401 Unauthorized indicates an expired or invalid token
• 403 Forbidden indicates insufficient permissions

Tokens are short-lived. Handle expiry by re-authenticating or using the refresh flow at POST /auth/token.

Internal services use Google Cloud identity tokens.

These endpoints must not be exposed to the public internet.

codeintegerrequired

HTTP status code (e.g., 400, 401, 404, 422, 429, 500).

messagestringrequired

A human-readable message providing more details about the error. These messages can be shown to your users or logged for debugging.

codestring

For some errors that could be handled programmatically, a short string indicating the error code reported.

errorsarray

For validation errors, a list of detailed field-level errors. Each error contains field, code, and message properties.

Within the errors array, each detailed error contains:

fieldstring

If the error is field-specific, the field path related to the error. For example, you can use this to display a message near the correct form field (e.g., email, shippingAddress.postcode).

codestring

Machine-readable error code for this specific field error (e.g., REQUIRED, INVALID_FORMAT, OUT_OF_RANGE).

messagestring

Human-readable explanation for this field error.

The type field in the error response indicates the category of error.

Any request with a body must set Content-Type: application/json.

Resources have stable, unique identifiers. Treat IDs as opaque strings.

Monetary values use minor units (cents).

Do not send floating-point dollar values. Always use the structured Money object.

typestringrequired

Precision type, always "centPrecision".

currencyCodestringrequired

ISO 4217 currency code (e.g., AUD, NZD).

centAmountintegerrequired

Amount in minor units (cents).

fractionDigitsintegerrequired

Number of decimal places for the currency.

Text that varies by locale uses LocalizedString.

Keys are IETF language tags (e.g., en-AU).

All timestamps use RFC 3339 / ISO 8601 format in UTC.

Always include the trailing Z for UTC. Do not send local time zone offsets.

Collection endpoints return a paged envelope.

See Pagination for details.

limitintegerrequired

Maximum number of results requested.

offsetintegerrequired

Number of results to skip.

countintegerrequired

Number of results in this response.

totalintegerrequired

Total number of results available.

resultsarrayrequired

Array of result objects.

All errors use a standard structure.

See Errors for the full list of status codes and error types.

Live customer traffic with real data. Subject to SLOs, monitoring, and change controls.

Use for:

• Validating behaviour with feature flags after deployment
• Investigating production issues with appropriate access

Never run synthetic load tests or use fake customer data against production.

Mirrors production topology. Used for pre-release verification and regression testing.

Use for:

• End-to-end test scenarios
• QA and UAT flows
• Verifying migrations and contract changes

Data may be synthetic or sanitised production records.

Shared integration environment for feature development.

Use for:

• Testing API changes from feature branches
• Manual testing from local frontend instances
• Early integration testing with other teams

Data and configuration may change frequently.

Runs the BFF on http://localhost:8080.

Typical setup:

• Storefront Next on http://localhost:3000
• Frontend proxies API calls to localhost:8080

See the storefront-bff README for setup details.

limitinteger

This specifies a limit on the number of objects to return, ranging between 1 and 100. Default is 20.

offsetinteger

The number of results to skip before returning results. Use this to page through results. Default is 0.

limitintegerrequired

The limit that was applied to this request.

offsetintegerrequired

The offset that was applied to this request.

countintegerrequired

The number of results in this response (may be less than limit on the last page).

totalintegerrequired

The total number of results available across all pages.

resultsarrayrequired

An array containing the actual response elements.

To paginate through results:

1. Make an initial request with your desired limit
2. Check if offset + count < total to determine if more pages exist
3. Increment offset by limit for the next page
4. Repeat until you've retrieved all results

• Use reasonable page sizes (20-50 items) for optimal performance
• Cache results where appropriate to reduce API calls
• Handle the case where total may change between requests (items added/removed)
• Consider using filtering to reduce result sets before pagination

Many endpoints expose explicit parameters for common filters:

• Boolean flags: inStock, featured, isDefault
• Value ranges: minPrice, maxPrice (in cents)
• Enumerations: status=active|inactive|discontinued
• Identifiers: category, brand, customerId

Endpoints with search use the query parameter.

The query is passed to the search system and may support stemming, synonyms, and fuzzy matching.

For complex conditions, use the filter parameter with operators.

Operators

Combine multiple filter parameters in a single request.

Content endpoints support a locale parameter.

Pattern: ^[a-z]{2}-[A-Z]{2}$ (e.g., en-AU). Default: en-AU.

Invalid filters return 400 Bad Request with details about the invalid parameter.

Required for any request with a body.

If missing or incorrect, returns 415 Unsupported Media Type.

Customer session token from the login flow.

Required for customer endpoints (cart, orders, profile). See Authentication.

Google Cloud identity token for service-to-service calls.

Used by internal services and batch jobs.

Selects the resource schema version.

Pattern: v{major}.{minor}. Required on requests, echoed in responses.

UUID for correlating logs and traces across services.

Optional. If not provided, the BFF generates one. Reuse the same ID for related requests in a single user flow (e.g., checkout).

Direction must be asc (ascending) or desc (descending).

Sort by a single field with ascending or descending direction.

Repeat the sort parameter for multiple fields.

Sort is applied in parameter order:

1. Featured products first
2. Then by popularity
3. Then alphabetically by name

Unsupported sort fields return 400 Bad Request.

Sorting is applied before pagination. Always use the same sort parameters when paginating to maintain stable ordering.

These operations can be retried on network failures or 5xx errors:

• GET, HEAD, OPTIONS - always safe
• PUT, DELETE - idempotent by design
• POST - only where explicitly documented

Prefer state-setting operations over action-style operations.

The client sends the desired state. Retries produce the same outcome.

Action endpoints are harder to make safe. Prefer state-setting alternatives.

When actions are necessary, implement them to be retry-safe:

Server behaviour:

• If confirmable, confirm and return the result
• If already confirmed, return the same result (not an error)
• If in an incompatible state, return 4xx

The API does not currently require explicit idempotency keys. If introduced in future, they will:

• Use an Idempotency-Key header
• Be scoped to method, path, and principal
• Store and replay original responses for matching requests

When you exceed a rate limit, the API returns a 429 status code.

The response may include a Retry-After header indicating how many seconds to wait before retrying.

Rate limits may be applied by:

• IP address - protects against abusive traffic
• Customer session - prevents UI loops
• Service account - for server-to-server integrations
• Endpoint - expensive operations (e.g., search) may have stricter limits

Exact thresholds are environment-specific and may change without notice.

• Debounce search and autocomplete requests
• Cache static data lookups
• On 429, wait per Retry-After and show a friendly message
• Don't retry aggressively

• Implement exponential backoff with jitter: 1s, 2s, 4s, 8s (capped)
• Reuse HTTP clients with connection pooling
• Stagger retries after outages to avoid thundering herd

Implement exponential backoff with jitter for production clients.

Rate limits in development and staging may be less strict but can still apply to expensive endpoints like search.

Design your clients to handle 429 gracefully in all environments.

The base URL is versionless. Versioning is applied at the resource level or via headers.

Individual resources can include a version suffix.

Version format: v{major} or v{major}.{minor}.

Omitting a version returns the latest supported version for that resource.

The X-Api-Version header controls cross-cutting behaviour.

Resource URL versions take precedence over the header for resource-specific behaviour.

These require a new major version:

• Removing fields
• Changing field types or formats
• Changing field semantics
• Changing status code behaviour

These are backwards-compatible and don't require a new version:

• Adding new optional fields
• Adding new endpoints
• Adding new parameters with defaults

1. Introduce v1 - Resource becomes generally available
2. Add v1.x - Optional improvements requiring explicit opt-in
3. Introduce v2 - Breaking changes; v1 enters deprecation window
4. Deprecate v1 - Removed after the agreed period

We limit live major versions to two at a time.

• Default to unversioned URLs unless you need a specific version
• For stable integrations, use explicit versions (e.g., /orders/v1)
• Track deprecation notices and plan upgrades
• Test across environments before production deployment