Admin API

The Admin API is the back office as an API. It reads and writes everything an administrator of the marketplace can see: every user, every vendor’s listings, every order. It is a JSON REST API served at:

https://<primary address>/api/v1

Typical integrations

• ERP, accounting and order management: pull new orders, push statuses, tracking numbers and invoice data back. See Sync orders to an ERP.
• Catalog management: import and update listings for all vendors from a PIM, a supplier feed or a spreadsheet. See Import a catalog.
• CRM and marketing: sync members, their groups and custom data, tag them with metafields.
• Custom payment flows: record payments taken with your own payment provider. See Record orders paid outside Kreezalid.
• Back end of a custom front end: your server reads the catalog for a mobile app or a headless storefront. See Build a headless storefront.

Authentication

HTTP Basic, with the API key as user name and the API secret as password. Generate them in Settings → Account → API access. Details, rotation and errors in Authentication.

Server-side only

Admin API credentials have administrator rights on the whole marketplace. Never ship them in a mobile app, a browser or any code your users can download.

Resources

Resource	Main endpoints
Listings	List · Retrieve · Create · POST /listings/bulk · Update · Delete · Search by field
Listing set-up	GET /listings/categories · GET /listings/attributes · GET /listings/order_types
Variants	List a listing’s variants · Retrieve · Update · Delete
Add-ons	List a listing’s add-ons · Retrieve · Update
Categories	Search · POST /categories/add
Collections	List · Create · Update · Listings of a collection · Collection models
Users	List · Retrieve · POST /users/add · PUT /users/{id}/update · Delete · GET /users/search · Payment account
Orders	List · Retrieve · Update · GET /orders/statuses
Metafields	On users, listings and orders: GET and POST /{resource}/{id}/metafields. See Metafields.
Events	List · Retrieve
Notifications	Send a notification email
Shipping rates	GET /shipping-rates · GET /shipping-rates/{id} · POST /shipping-rates/add
Payments	Payment gateways · vendors’ external payment accounts · POST /checkout/preauth-success · /checkout-redirects

The Admin API reference documents every field.

Where the reference and the live API differ

A few paths in the generated reference are being corrected. Until then, use these:

• create a user with POST /api/v1/users/add, update one with PUT /api/v1/users/{id}/update;
• create a category with POST /api/v1/categories/add;
• shipping rates live under /api/v1/shipping-rates (with a hyphen);
• variants are created by updating their listing (PATCH /api/v1/listings/{id} with a variants array, see below); add-ons cannot be created through the API yet.

Conventions

• JSON in, JSON out. Send Content-Type: application/json. A .json suffix on the path (/api/v1/listings.json) is accepted and changes nothing.
• Wrapped responses. Lists come under a plural key (listings, users, orders, events) with a pagination object. A single object comes under its own key: user, order, and, for a listing, product.
• Writes answer with success. Create, update and delete return {"success": true|false, "message": "…"}, plus the new id on creation. A refused write still answers 200: always read success. See Errors.
• Amounts are strings with two decimals ("480.00") in the marketplace currency.
• Dates: order timestamps (checkout_at, payout dates) are Unix timestamps; listing dates such as date_online are YYYY-MM-DD HH:MM:SS strings.
• Your references: users, listings and variants have an external_id for your own id, and every user, listing and order can carry metafields.

Things to know

• No side effects you did not ask for. Creating a user or a listing, or changing an order’s status through the API, sends no email and emits no order.status.* webhook. Use Send a notification when the customer or the vendor should be told.
• Listings you create are live. They are published and approved immediately unless you send "is_online": 0. The status you send on creation is not applied yet: create with is_online instead.
• Descriptions are plain text. HTML sent in description is converted to text.
• Images are fetched by Kreezalid. Send public image URLs in images; on update, the array replaces every existing image.
• Variants are synced as a set. On PATCH /listings/{id}, each entry of variants updates the existing variant with the same external_id, or else the same sku, and creates a new one otherwise. Existing variants that are not in the array are deleted. Always send the complete list, with external_id or sku on every entry.
• Updating order items. PATCH /orders/{id} accepts an order_items array of { "id", … } objects. Send one item per request when you update items.
• Drafts are hidden from GET /orders unless you filter on status=draft.

QuickstartYour first call and your first listing.

Admin API referenceEvery endpoint and field.