Core concepts

A Kreezalid marketplace connects vendors, who publish listings, with customers, who place orders. This page describes those objects as the APIs return them, so you can map them to your own system. Field names are those of the Admin API; webhooks carry the same objects.

The marketplace

Each marketplace is a separate world with its own address (acme.mykreezalid.com, or its own domain), its own back office, users, catalog and orders. Every API call, webhook and credential belongs to exactly one marketplace. There is no cross-marketplace call: an integration that serves several marketplaces holds one set of credentials per marketplace.

Every object carries an object field naming its kind ("User", "Listing", "Order", "OrderItem", "Category"…) and an id, unique within the marketplace.

Users and groups

There is one kind of account, the user. What a user may do depends on the group it belongs to, and the groups are defined by the marketplace owner in Settings → Users → Groups (/admin/settings/users/groups): for instance Customers, Vendors, Partner shops.

Field	Meaning
group	{ "object": "Group", "id", "name", "alias" }: the user’s group.
can_post_listing	true when the group may publish listings. These users are the vendors.
account_type	individual, company, non_profit or soletrader. Company accounts also carry a company object (name, number, address, website).
external_id	Free text for your own reference, for instance your CRM id. Kreezalid never interprets it.
status	The account’s state as shown in the back office.
email, first_name, last_name, public_name, username	Identity. public_name is the name shown on the storefront.
address_*, phone_country_code, phone_number, lang, timezone	Contact and locale.
attributes	Values of the custom profile fields the marketplace defined, keyed by field alias.
average_rating, review_count, listing_count	Counters maintained by Kreezalid.
metafields	Your own data attached to the user. See Metafields.

A vendor is a customer like any other when they buy: the same user id can appear as customer on one order and as supplier on another.

Listings

A listing is what a vendor offers: a product, a service, a rental, a booking, a job.

Field	Meaning
owner	The vendor, as a user object. user and supplier carry the same value for older integrations. When you write a listing, the vendor is user_id.
title, description	Description is plain text.
price, original_price, currency, price_with_currency	price is the selling price, original_price an optional crossed-out price. Amounts are strings with two decimals.
quantity, min_qty, sku	Stock and order constraints, when the listing’s order type enables them.
category	{ "object": "Category", "id", "title", "slug", "url" }. A listing has one category; when you write, send category_id. Categories can be nested (parent_id).
attributes	Values of the listing fields the marketplace defined (size, brand, surface…), keyed by attribute alias. Read their definitions with GET /api/v1/listings/attributes.
variants	Purchasable variations of the listing, each with its own price, quantity, sku, title, external_id.
add_ons	Optional extras the customer can add to the listing, each with a title and a price.
order_type	How the listing is sold: { "id", "title", "transaction_type", "enable_cart" }, with the matching rules in settings (cart, stock, shipping, calendar, approval…). Order types are configured by the marketplace owner.
shipping_methods	The delivery methods available for the listing, with their price and step_price (the amount added per additional item).
medias	Images, in display order, each with src, alt and position.
address, location, city, state, country, lat, lng	Where the listing is, when the marketplace uses locations.
external_id	Your reference for the listing, such as your SKU or product id.
metafields	Your own data. See Metafields.

Three fields decide whether a listing is visible:

Field	Values	Set by
status	draft, published, archived	The vendor: whether the listing is offered at all.
admin_status	waiting, approved, rejected, blocked	The marketplace’s moderation. waiting means awaiting approval.
visibility	both, catalog, search, none	Where it appears: catalog pages, search results, both, or neither (reachable by its URL only).

A listing is on sale when it is published and approved.

Collections group listings for the storefront, such as Summer picks or New in. A collection is identified by its handle and can be filled by hand or generated by a collection model from a criterion. Both are managed with the /api/v1/collections and /api/v1/collection-models endpoints.

Carts, orders and order items

A customer puts listings in a cart. Because each vendor fulfils their own part, a cart holds one order per vendor: buying from two vendors produces two orders, each with its own number, status, shipping and payout. A listing bought directly, without a cart, produces a single order.

An order is the agreement between one customer and one vendor.

Field	Meaning
number	The order number shown to users (order_number carries the same value).
status	Where the order is in its life cycle. See below.
fulfillment_status	Optional delivery tracking, independent of status: started, scheduled, prepared, shipped, in_transit, available, delivered, executed, canceled, error.
customer, supplier	The buyer and the vendor, as user objects.
amount, currency, amount_with_currency	What the customer pays for this order.
net_supplier_amount	What the vendor is due once the marketplace’s commission is deducted.
smart_fees	The commission and fee rules applied to the order: fee_target, rule_title, fee_amount.
order_items	The lines of the order. See below.
requires_shipping, shippings	Whether the order is delivered, and the chosen method, amount, carrier, tracking number and URL, pickup point and delivery address.
billing_address	The customer’s billing address.
checkout_at	When the customer checked out, as a Unix timestamp. null until then.
checkout_message	The note the customer left at checkout.
refusal_reason	Why the vendor declined, when they did.
has_declined_items	true when the vendor refused some items of the order.
psp_capture_funds_at_checkout	true when the payment was captured at checkout, false when it was only authorized and is captured later, typically when the vendor accepts.
payout	The vendor’s payout for this order. See Payments and payouts.
metafields	Your own data.

Each order item is one listing in the order:

Field	Meaning
listing_id, listing_title, listing_sku, listing_image	The listing as it was when ordered.
qty	Quantity, a decimal number when the listing is sold by measure.
listing_unit_price, base_amount, amount	Unit price, the line before options, and the line total.
variants, options, add_ons, properties	What the customer chose.
start_datetime	For bookings, when the booked slot starts.
status, refusal_reason	Each item can be accepted or refused on its own when the vendor accepts part of an order.

Order statuses

Orders move through these statuses. Which ones a given marketplace uses depends on its payment set-up and on whether vendors confirm orders, ship goods or provide services.

1. draft: created as soon as a listing is added to a cart or a direct checkout starts. The customer has not paid. Drafts are left out of GET /api/v1/orders unless you ask for them with ?status=draft.
2. pending: the customer checked out with a payment that is not instant, such as a bank transfer or cash on delivery. The order waits for the money.
3. new: the order is paid or validated. This is the new order a vendor must act on. failed: the payment failed.
4. accepted: the vendor confirms they will fulfil it. declined: the vendor refuses it, with a refusal_reason.
5. shipped, service_provided, customer_confirmed, supplier_confirmed: fulfilment steps, used in whatever order the marketplace’s workflow needs.
6. completed: the workflow is over; consider the order closed.

At any point before completion, an order can become canceled by the customer, the vendor or an administrator. Read the current list with GET /api/v1/orders/statuses.

Tip

Status changes made on the marketplace (checkout, a vendor accepting, a customer confirming) emit a webhook named after the status the order enters, such as order.status.new or order.status.accepted. See Event types. A status you set yourself through the API emits no order.status.* event and sends no email: your integration already knows about it.

Payments and payouts

Customers pay through the payment service provider the marketplace connected. The money then follows the marketplace’s model:

• Capture. The payment is either captured at checkout, or authorized at checkout and captured later, usually when the vendor accepts the order. The order’s psp_capture_funds_at_checkout tells you which.
• Commission. The marketplace keeps its fees, described by smart_fees. What remains for the vendor is net_supplier_amount.
• Payout. The vendor receives their share. The order’s payout object gives its status (not_available until money has been paid out, then success), the amount, and the requested_at, completed_at and arrival_date Unix timestamps.

A vendor’s account with the payment provider is visible with GET /api/v1/users/{id}/psp_account. A marketplace that runs its payments outside Kreezalid records each successful authorization with POST /api/v1/checkout/preauth-success: see Record orders paid outside Kreezalid.

Metafields

A metafield is a piece of your own data attached to a user, a listing or an order: a namespace, a title (its key) and a value. Use them to store what Kreezalid has no field for, such as an ERP id, a loyalty tier or a warehouse code. They appear in the object’s metafields field as { "namespace": { "title": "value" } }.

MetafieldsWrite and read metafields on users, listings and orders.

Events

Kreezalid records what happens on the marketplace (listing.creation, user.update, order.status.accepted…) as events. Webhooks push them to your URL; the Admin API lists them with GET /api/v1/events. See Webhooks.