Developers

Connect your own systems. With a key, a library and webhooks.

Every store has an API for products, orders, customers, discounts and stock. Two ready-made libraries, for JavaScript and Python, take care of keys, paging, errors and webhook signatures, so the first call takes minutes.

01Start

Three steps to the first call.

  1. Make a key

    In the admin, open Developers and make an API key with only the permissions it needs. Copy it then: it is shown once. API access is part of the Business plan.

  2. Download a library

    JavaScript or Python, below. Each is one download with no dependencies.

  3. Call the API

    Give the library the key and the store id (both on the Developers page) and read your first products. Keep the key on a server, never in a browser page.

02Libraries

Two languages, the same API.

Both libraries cover the same ground: products, orders, customers, discounts and stock, every list page after page, errors you can act on, and webhook signature checks. Anything they do not cover yet is one call away with request().

JavaScript and TypeScript

For Node 18 and later, Deno, Bun and Cloudflare Workers. One ES module with its type definitions.

Example
import { Kreaza, KreazaError } from "./kreaza.js";

const kreaza = new Kreaza({
  apiKey: process.env.KREAZA_API_KEY,
  storeId: process.env.KREAZA_STORE_ID,
});

// One page of active products
const { products, next_cursor } = await kreaza.products.list({ status: "active" });

// Every paid order, page after page
for await (const order of kreaza.orders.all({ payment_status: "paid" })) {
  console.log(order.number, order.total);
}

try {
  await kreaza.products.create({ title: "", variants: [{ price: 12900 }] });
} catch (e) {
  if (e instanceof KreazaError) console.log(e.status, e.code, e.fields);
}

Python

For Python 3.9 and later, typed. A wheel you install with pip; only the standard library inside.

Install
pip install ./kreaza-1.0.0-py3-none-any.whl
Example
import os
from kreaza import Kreaza, ValidationError

kreaza = Kreaza(api_key=os.environ["KREAZA_API_KEY"],
                store_id=os.environ["KREAZA_STORE_ID"])

# One page of active products
page = kreaza.products.list(status="active")
print(len(page), page.next_cursor)

# Every paid order, page after page
for order in kreaza.orders.all(payment_status="paid"):
    print(order["number"], order["total"])

try:
    kreaza.products.create({"title": "", "variants": [{"price": 12900}]})
except ValidationError as e:
    print(e.status, e.code, e.fields)

The libraries are downloads from this site for now, not npm or PyPI packages.

03Lists

Page by page, or all at once.

A list answers one page and a next_cursor; the last page has none. list() reads one page. all() follows the cursor for you and hands over items one at a time, fetching the next page only when it is needed.

04Errors

Errors that say what to do.

A refused request raises an error with the HTTP status, a stable code for programs, the fields at fault and a request id to quote to support. In JavaScript it is KreazaError; in Python each status has its own class.

StatusWhat it meansPython class
400, 422The input was refused. fields names each field and its problem.ValidationError
401The key is missing, wrong, revoked or belongs to another store.AuthenticationError
403The key works but lacks the permission this needs.PermissionDeniedError
404There is no such thing in this store.NotFoundError
409It clashes with the current state, for example an address already in use.ConflictError
429Too many requests. Wait and try again.RateLimitError
5xxThe API failed. A read is safe to retry; check before repeating a write.ServerError
0No answer: the network failed (network) or it took too long (timeout).APIConnectionError, APITimeoutError

05Webhooks

Hear about an order the moment it changes.

A webhook posts a signed JSON message to your https address when something happens in the store: an order placed, paid, sent, cancelled or refunded, a new or changed customer or product, low stock, a confirmed booking, a review, a message or a return request. A delivery that fails is retried with growing gaps, up to 8 times, and every attempt is in the log on the Developers page.

Events

  • order.created
  • order.paid
  • order.fulfilled
  • order.cancelled
  • order.refunded
  • customer.created
  • customer.updated
  • product.created
  • product.updated
  • product.deleted
  • inventory.low
  • booking.confirmed
  • review.created
  • form.submitted
  • return.requested

Each message carries X-Creatify-Signature: sha256= and the HMAC-SHA256 of the exact body with the webhook's secret. Check it on the raw body, before parsing: JSON written out again will not match.

JavaScript and TypeScript
import { verifyWebhook } from "./kreaza.js";

// Read the body as text, before parsing it
const raw = await request.text();
const ok = await verifyWebhook(process.env.KREAZA_WEBHOOK_SECRET, raw,
  request.headers.get("x-creatify-signature"));
if (!ok) return new Response("bad signature", { status: 401 });
const event = JSON.parse(raw);
Python
from kreaza import verify_webhook

# The raw bytes, before parsing them
raw = request.get_data()
if not verify_webhook(os.environ["KREAZA_WEBHOOK_SECRET"], raw,
                      request.headers.get("X-Creatify-Signature")):
    abort(401)
event = json.loads(raw)

06Permissions

A key can do only what you allow.

Choose the permissions when you make the key. The account, payments, team and the keys themselves are never open to a key: they stay with people signed in to the admin.

Permissions a key can hold

  • products.read
  • products.write
  • inventory.read
  • inventory.write
  • orders.read
  • orders.manage
  • customers.read
  • customers.write
  • discounts.read
  • discounts.write
  • analytics.read
  • hosting.read
  • hosting.manage
  • hosting.settings
  • themes.read
  • themes.write

Build on your store.

Open a store, move to Business when you are ready, and make your first key on the Developers page.