Front API

The Front API is the API of the people who use the marketplace. It acts on behalf of one signed-in member with their own email and password, so it is safe to call from code your users run: a mobile app, a single-page app, or the JavaScript of your theme.

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

Typical integrations

• Mobile apps for customers or vendors. See Build a mobile app.
• Headless storefronts with your own front end. See Build a headless storefront.
• Interactive theme features: a wishlist button, a vendor favourites page, a quantity badge on the cart icon, written in your theme’s JavaScript. See Use vendors as wishlist items.

Authentication

The member logs in with POST /auth/login and receives a token valid for one year, sent as Authorization: Bearer <token>. Inside a theme on the marketplace’s domain, the storefront session works as well. Visitors who are not signed in can use a few endpoints: sign-up, password reset, categories, public vendor profiles, reviews and the guest cart. Details in Authentication.

Cross-origin requests are allowed from any origin, so a front end on another domain can call the API directly with a Bearer token.

Resources

Resource	Endpoints	Who
Session	POST /auth/login · GET /auth/me · DELETE /auth/logout	Member
Account	POST /account/create · PATCH /account/update · POST /account/forgot-password · POST /account/reset-password · POST /account/change-password · POST /account/email-exist	Visitor or member
Checkout addresses	GET and POST /account/checkout-addresses · GET, PUT and DELETE /account/checkout-addresses/{id}	Member
Categories	GET /categories · GET /categories/{category_id}	Anyone
Cart	POST /carts · GET /carts/{url_key} · POST /carts/{url_key} (add an item) · PUT and DELETE /carts/{url_key}/order_items/{order_item_id} · GET /carts/{url_key}/listings/{listing_id}/quantity	Visitor or member
Cart delivery	GET /carts/{url_key}/orders/{order_id}/available-shipping-methods · PATCH /carts/{url_key}/orders/{order_id}/shipping-method · PUT /carts/{url_key}/checkout-addresses/{checkout_address_id}	Visitor or member; the address step needs a member
Orders	GET /orders · GET /orders/{id} · messages, attachments and invoice number of an order	Member, as customer or vendor of the order
Wishlist	GET /wishlists · POST /wishlists · GET /wishlists/{item_id}/check · DELETE /wishlists/{item_id}	Member
Vendor’s own listings	GET /listings · GET /listings/{id} · POST /listings/add · PATCH /listings/{id}/edit · attachments and related listings	Member who is a vendor
Listing attributes	GET /listings/attributes	Anyone
Public profiles	GET /directories/{user_id} · GET /reviews/user/{user_id}	Anyone

See the Front API reference for request and response fields.

The Front API does not browse the catalog

GET /listings returns the signed-in vendor’s own listings, not the marketplace catalog. To show a catalog in an app or a headless front end, read listings from your server with the Admin API and serve them to your front end, or keep the catalog pages on the theme. See Build a headless storefront.

How the cart works

1. POST /front_api/v1/carts with an empty body creates a cart and returns its url_key. Keep it: every cart call is addressed by it.
2. POST /front_api/v1/carts/{url_key} with listing_id and quantity, plus optional variants, options, addons and properties, adds a listing.
3. The cart holds one order per vendor. GET /front_api/v1/carts/{url_key} returns the cart with its orders, so you can choose a shipping method per order.
4. When a guest who owns a cart signs in, the cart is attached to their account on the next cart call.

A cart created by a guest can be read and changed by anyone who knows its url_key, until a member owns it. Treat the url_key as a secret of the visitor’s session.

Things to know

• Responses are not uniform. Endpoints return {"success": …}, {"status": …} or {"code": …, "status": …} bodies depending on their family, and a few errors come back as HTML pages. See Errors.
• Sign-up needs a group. POST /account/create requires email, password and the group_id the member joins. Add ?no-confirmation-email to the URL to skip the welcome or confirmation email.
• Logging out does not revoke the token. Delete it from the device.
• Payment is not part of the Front API. A cart is paid on the marketplace’s checkout pages, or with your own payment provider followed by an Admin API call from your server. See Record orders paid outside Kreezalid.

Front API referenceEvery endpoint and field.

AuthenticationLogin, tokens, public endpoints.