Quickstart

This page takes you from an empty terminal to a listing created through the Admin API. You need a marketplace you administer. If you do not have one yet, start a free trial first: it takes a minute.

The examples use the fictional marketplace acme.mykreezalid.com. Replace it with your own address everywhere.

1. Get your API credentials

1. Sign in to the back office of your marketplace, https://acme.mykreezalid.com/admin.

2. Open Settings → Account (/admin/settings/account) and find the API access section.

3. Click Generate secret key. The page now shows an API key (it starts with pk_) and an API secret (it starts with sk_).

4. Store both values in your secret manager or in environment variables. The examples below read them from KREEZALID_API_KEY and KREEZALID_API_SECRET.

export KREEZALID_BASE_URL="https://acme.mykreezalid.com/api/v1"
export KREEZALID_API_KEY="pk_…"
export KREEZALID_API_SECRET="sk_…"

Caution

The key and secret act on your marketplace with the rights of an administrator. Keep them on a server. See Authentication for rotation.

2. Make your first call

The Admin API uses HTTP Basic authentication: the API key is the user name, the API secret is the password. List the categories of your marketplace; you need a category id to create a listing anyway.

curl

curl "$KREEZALID_BASE_URL/listings/categories" \
  -u "$KREEZALID_API_KEY:$KREEZALID_API_SECRET"

Node.js

first-call.mjs

const base = process.env.KREEZALID_BASE_URL;
const auth = Buffer.from(
  `${process.env.KREEZALID_API_KEY}:${process.env.KREEZALID_API_SECRET}`
).toString('base64');

const res = await fetch(`${base}/listings/categories`, {
  headers: { Authorization: `Basic ${auth}`, Accept: 'application/json' },
});
console.log(res.status, await res.json());

PHP

first-call.php

<?php
$base = getenv('KREEZALID_BASE_URL');
$ch = curl_init("$base/listings/categories");
curl_setopt_array($ch, [
    CURLOPT_USERPWD        => getenv('KREEZALID_API_KEY') . ':' . getenv('KREEZALID_API_SECRET'),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Accept: application/json'],
]);
$body = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), PHP_EOL, $body, PHP_EOL;

Python

first_call.py

import os, requests

base = os.environ["KREEZALID_BASE_URL"]
auth = (os.environ["KREEZALID_API_KEY"], os.environ["KREEZALID_API_SECRET"])

res = requests.get(f"{base}/listings/categories", auth=auth)
print(res.status_code, res.json())

A successful call answers 200 with the categories and a pagination block:

{
  "categories": [
    {
      "id": 812,
      "title": "Road bikes",
      "page_title": "Second-hand road bikes",
      "description": "Carbon and steel road bikes, checked by our partners.",
      "slug": "road-bikes",
      "listing_count": 37,
      "url": "https://acme.mykreezalid.com/…",
      "admin_url": "https://acme.mykreezalid.com/admin/…"
    }
  ],
  "pagination": {
    "totalResultsCount": 1,
    "currentPage": 1,
    "nextPage": false,
    "prevPage": false,
    "resultOnPageCount": 1,
    "pageCount": 1
  }
}

If you get a 403 instead, read the message: Access denied. Please use your API credentials to use the API means no credentials were sent, Permission denied, wrong credentials means the pair is wrong or belongs to another marketplace. See Errors.

3. Find the vendor who will own the listing

Every listing belongs to a user, its vendor. List your users and pick one whose group allows posting listings (can_post_listing: true):

curl "$KREEZALID_BASE_URL/users?fields=id,email,public_name,group,can_post_listing&limit=5" \
  -u "$KREEZALID_API_KEY:$KREEZALID_API_SECRET"

{
  "users": [
    {
      "id": 4242,
      "email": "jane@example.com",
      "public_name": "Jane's Cycles",
      "group": { "object": "Group", "id": 3, "name": "Vendors", "alias": "vendors" },
      "can_post_listing": true
    }
  ],
  "pagination": { "totalResultsCount": 18, "currentPage": 1, "nextPage": true, "prevPage": false, "resultOnPageCount": 5, "pageCount": 4 }
}

4. Create a listing

Send POST /api/v1/listings with a JSON body. user_id, title, description, price and category_id are required.

curl

curl -X POST "$KREEZALID_BASE_URL/listings" \
  -u "$KREEZALID_API_KEY:$KREEZALID_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 4242,
    "category_id": 812,
    "title": "Steel road bike, 56 cm",
    "description": "Reynolds 531 frame, serviced in September. Ready to ride.",
    "price": 480,
    "quantity": 1,
    "external_id": "JC-BIKE-0193",
    "images": ["https://images.example.com/bikes/0193-side.jpg"]
  }'

Node.js

create-listing.mjs

const base = process.env.KREEZALID_BASE_URL;
const auth = Buffer.from(
  `${process.env.KREEZALID_API_KEY}:${process.env.KREEZALID_API_SECRET}`
).toString('base64');

const res = await fetch(`${base}/listings`, {
  method: 'POST',
  headers: {
    Authorization: `Basic ${auth}`,
    'Content-Type': 'application/json',
    Accept: 'application/json',
  },
  body: JSON.stringify({
    user_id: 4242,
    category_id: 812,
    title: 'Steel road bike, 56 cm',
    description: 'Reynolds 531 frame, serviced in September. Ready to ride.',
    price: 480,
    quantity: 1,
    external_id: 'JC-BIKE-0193',
    images: ['https://images.example.com/bikes/0193-side.jpg'],
  }),
});

const body = await res.json();
if (!body.success) throw new Error(body.message);
console.log('Created listing', body.id);

PHP

create-listing.php

<?php
$base = getenv('KREEZALID_BASE_URL');
$payload = [
    'user_id'     => 4242,
    'category_id' => 812,
    'title'       => 'Steel road bike, 56 cm',
    'description' => 'Reynolds 531 frame, serviced in September. Ready to ride.',
    'price'       => 480,
    'quantity'    => 1,
    'external_id' => 'JC-BIKE-0193',
    'images'      => ['https://images.example.com/bikes/0193-side.jpg'],
];

$ch = curl_init("$base/listings");
curl_setopt_array($ch, [
    CURLOPT_USERPWD        => getenv('KREEZALID_API_KEY') . ':' . getenv('KREEZALID_API_SECRET'),
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json', 'Accept: application/json'],
    CURLOPT_RETURNTRANSFER => true,
]);
$body = json_decode(curl_exec($ch), true);
if (empty($body['success'])) {
    throw new RuntimeException($body['message'] ?? 'Unknown error');
}
echo 'Created listing ', $body['id'], PHP_EOL;

Python

create_listing.py

import os, requests

base = os.environ["KREEZALID_BASE_URL"]
auth = (os.environ["KREEZALID_API_KEY"], os.environ["KREEZALID_API_SECRET"])

res = requests.post(f"{base}/listings", auth=auth, json={
    "user_id": 4242,
    "category_id": 812,
    "title": "Steel road bike, 56 cm",
    "description": "Reynolds 531 frame, serviced in September. Ready to ride.",
    "price": 480,
    "quantity": 1,
    "external_id": "JC-BIKE-0193",
    "images": ["https://images.example.com/bikes/0193-side.jpg"],
})
body = res.json()
if not body.get("success"):
    raise RuntimeError(body.get("message"))
print("Created listing", body["id"])

The response gives the id of the new listing:

{
  "id": 645646,
  "message": "Listing created",
  "success": true
}

Read `success`, not only the status code

When a listing is refused (a missing field, an unknown category), the API still answers 200, with "success": false, "id": null and the reason in message, for instance Field price is required or Category with ID 9999 does not exist. Always check success.

A few behaviours worth knowing before you go further:

• The listing is published and approved right away. To create it offline, send "is_online": 0: it is saved as a draft and blocked, and you publish it later.
• description is stored as plain text. HTML you send is converted to text.
• Each URL in images is downloaded during the request, so it only needs to be reachable for that long. The array order is the display order.
• A price of 0 is refused as missing.

5. Read it back

curl "$KREEZALID_BASE_URL/listings/645646" \
  -u "$KREEZALID_API_KEY:$KREEZALID_API_SECRET"

A single listing comes back under the product key:

{
  "product": {
    "object": "Listing",
    "id": 645646,
    "title": "Steel road bike, 56 cm",
    "status": "published",
    "admin_status": "approved",
    "visibility": "both",
    "price": "480.00",
    "price_with_currency": "€480.00",
    "currency": "EUR",
    "quantity": 1,
    "external_id": "JC-BIKE-0193",
    "category": { "object": "Category", "id": 812, "title": "Road bikes", "slug": "road-bikes" },
    "owner": { "object": "User", "id": 4242, "public_name": "Jane's Cycles" },
    "medias": [
      { "object": "Media", "id": 99120, "alt": null, "position": 0, "media_type": "image", "src": "https://…/0193-side.jpg" }
    ],
    "url": "https://acme.mykreezalid.com/…"
  }
}

This response is abridged: the full listing also carries its attributes, variants, add-ons, shipping methods, order type and metafields. Amounts such as price are returned as strings with two decimals. See Retrieve listing for every field.

Next steps

• Core concepts: how users, listings and orders fit together.
• Pagination and filtering: read large lists efficiently.
• Import a catalog: create hundreds of listings at once.
• Sync orders to an ERP: webhooks plus the API as a safety net.