Skip to main content

Customer API

The Kiss Customer API is a secure HTTP/JSON service for retrieving your customer-scoped products, stock, and prices data. It is designed for development teams who want to integrate Kiss data into their own systems — ERP, e‑commerce, PIM, analytics, or anywhere else.

Key facts​

  • Protocol: HTTPS, JSON request/response bodies.
  • Authentication: OAuth 2.0 client credentials grant, returning a short-lived JSON Web Token (JWT).
  • Bearer header: Authorization: Bearer <access_token>.
  • Style: Server-to-server. CORS is not configured — the API is not designed to be called from a browser.
  • Data scope: Every response is automatically filtered to the authenticated customer's price list, warehouse, and discount terms.
  • Versioning: Calendar-based API profiles (e.g. 2026-04) exposed via a /api/version endpoint and inside every schema response.
  • Push notifications: None. The API is pull-only — your client polls on a schedule of your choosing.

When to use it​

Use the Customer API instead of the Datafeed App when:

  • You have a development team and want full control over polling, caching, error handling, and data flow.
  • You need to integrate the data into a live system (website, ERP, order management platform) rather than load it from a file.
  • You want to combine product, stock, and price data with your own business logic before exposing it to end users.

If you just need CSVs on disk, the Datafeed App is the simpler choice.

What the API exposes​

EndpointPurpose
POST /auth/tokenExchange your API key for a short-lived JWT.
GET /productsYour full product catalogue with nested images, accessories, substitutions, composition, and prices.
GET /products/schemaMachine-readable description of the /products payload.
GET /stockLive stock levels at your assigned warehouse.
GET /stock/schemaMachine-readable description of the /stock payload.
GET /pricesYour price-list entries with discounts pre-applied.
GET /api/versionThe deployed API profile, e.g. {"apiVersion":"2026-04"}.
GET /healthLiveness probe. Returns 200 Healthy.

How the data is scoped​

Everything the API returns is automatically scoped to your customer record. You do not need to send any customer identifier in queries — your bearer token already identifies you, and the API:

  • Excludes products whose status is OBSOLETE.
  • Excludes products that are not in your assigned price list.
  • Returns stock only for your assigned warehouse, and only for SKUs in your price list.
  • Applies your discount percentage to any price that is marked as discount-eligible.

How to read the API docs​

The sidebar lists topics in the order a developer typically works through them when building an integration:

  1. Getting started — your first request.
  2. Authentication — credentials, tokens, and token lifetime.
  3. Versioning — how API profiles work.
  4. Rate limits — per-customer quotas and how to handle 429 Too Many Requests.
  5. Errors — the standard error format.
  6. Endpoints — full reference for every endpoint.
  7. Data models — the response schemas in detail.

Conventions used throughout these docs​

  • HTTP method badges like GET /example indicate the verb and path.
  • All request and response bodies are JSON unless explicitly noted.
  • All timestamps are UTC and use ISO 8601 (e.g. 2026-05-14T10:30:00Z).
  • Field names in JSON response bodies use PascalCase — for example, SKU, Name, PriceExclVAT, NextAvailableETA. Reference them verbatim. See Data models.
  • The schema endpoints report field names in camelCase (sKU, mOQ, etc.). This differs from the data endpoints' PascalCase — see the schemas page for the full note.

Need credentials?​

To use the API you need a Customer Code and an API Key. These are issued by Kiss when you sign up for the datafeed service. If you don't have credentials yet, contact your account manager or email support@kissmecostumes.com.

Continue to Getting started to make your first authenticated request.