Getting Started

This page walks you through your first authenticated request to the Customer API. It takes about five minutes if you already have your credentials.

What you need

• Your Customer Code (e.g. ACME01).
• Your API Key (a long random string).
• The base URL for your deployment, supplied by your Kiss account manager — for example https://api.kiss.example.com.
• Any HTTP client. The examples below use curl, but httpie, Postman, Insomnia, or your application's HTTP library all work.

Step 1 — Exchange your API key for an access token

Send a POST request to /auth/token with your credentials. The body is form-encoded:

curl -X POST "https://api.kiss.example.com/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=ACME01" \
  -d "client_secret=YOUR_API_KEY"

A successful response looks like:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

The access_token is valid for 3600 seconds (one hour). Cache it and reuse it — there is no need to fetch a new token on every request. A few minutes before it expires, request a new one.

For full details, see Authentication.

Step 2 — Make your first request

With your access token in hand, call any customer endpoint with an Authorization: Bearer <token> header:

curl "https://api.kiss.example.com/api/version" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

You should get back the current API profile:

{ "apiVersion": "2026-04" }

If you see 200 OK with this payload, you're up and running.

Step 3 — Fetch your data

The three main customer endpoints all use the same pattern. Send a GET with your bearer token, get back JSON.

curl "https://api.kiss.example.com/products" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

You'll receive a JSON array, where each element is one product:

[
  {
    "SKU": "DRAC001",
    "Name": "Dracula Adult Costume",
    "ProductCategoryCode": "HALLOWEEN-ADULT",
    "Status": "ACTIVE",
    "ProductPrices": [
      {
        "PriceListCode": "EUR-WHOLESALE",
        "CurrencyCode": "EUR",
        "PriceExclVAT": 19.95,
        "MOQ": 12,
        "OrderMultiple": 12
      }
    ]
  }
]

The same pattern works for stock and prices:

curl "https://api.kiss.example.com/stock"  -H "Authorization: Bearer ..."
curl "https://api.kiss.example.com/prices" -H "Authorization: Bearer ..."

:::note Field names use PascalCase JSON property keys in data responses are PascalCase: SKU, MOQ, PriceExclVAT, NextAvailableETA, and so on. Reference them verbatim in your client code. See Data models for the full reference. :::

What's next?

Now you have a working request. The recommended next steps are:

1. Read Authentication to understand how to manage tokens in your client and handle expiry cleanly.
2. Read Rate limits to make sure your polling strategy stays inside your quota.
3. Pick the endpoint reference for the data you need: Products, Stock, or Prices.
4. Read Errors so your client handles failures correctly.

A note on data shape

Because the API is fully customer-scoped, there are no customer_id parameters and no need to filter by price list, warehouse, or discount. The bearer token does all that work for you. Just call the endpoint and your data comes back.

Tips for production integrations

• Cache the access token in memory and refresh it just before it expires (a few minutes early is good practice).
• Poll sensibly — see Rate limits. Most integrations refresh products daily and stock every 15–30 minutes.
• Use the schema endpoints (/products/schema and /stock/schema) if you want your client to adapt automatically to new fields without code changes. Be aware that the schema reports names in camelCase while the data response uses PascalCase — see the schemas page.
• Watch the API profile by polling /api/version. When the profile changes, review the release notes to see what's new.