Admin API (1.0)

Obtaining your secret key

To interact with the API, you need to have a unique, personal secret key, which is used to authenticate yourself within the API.

Token is an equivalent of the user name & password pair - once generated, it uniquely identifies your own account, so you should be careful with it and not disclosure it to any untrusted party (application).

To generate your secret key, you should:

1. Go to your admin panel. For example: https://subdomain.mykreezalid.com/admin
2. Click on the Settings link in the sidebar, then on the Account button
3. In the API access section, click on the button Enable API access to generate a new secret key
4. Note down your newly generated secret key - you are going to need it soon

If you don't use a custom domain, you can use your custom subdomain, generated on your store creation. Be careful, the main domain name is *.mykreezalid.com. To avoid errors, you can just copy/paste the URL of your homepage:

https://subdomain.mykreezalid.com/api/v1

If you already connect a custom domain, you must use it in your API calls. As we don't follow redirects, you need to precise your primary domain (with www or without www or any other subdomain):

https://your_custom_domain.tld/api/v1

Admin API supports a limit of 40 requests per minute.

Past the limit, the API will return a 429 Too Many Requests error.

All API queries return HTTP status codes that can tell you more about the response.

401 Unauthorized

The client doesn’t have correct authentication credentials. Check your Base URL is correct (w/o www.).

403 Forbidden

The server is refusing to respond.

404 Not Found

The requested resource was not found. This is typically caused by incorrect endpoint calls.

429 Too Many Requests

The client has exceeded the rate limit.

5xx Errors

An internal error occurred in Kreezalid. Our technical team has been notified.

{
"title": "Extended Warranty",
"listing_id": 234324,
"price": 12.5,
"description": "Protect your purchases beyond the standard warranty period"
}

An add-on is a supplementary product, feature, or service that can be purchased or acquired in addition to the primary item or service being offered. Add-ons typically enhance or expand the functionality, customization, or overall experience of the main product or service, providing added value to the customer.

Here are some examples of typical add-ons: Extended warranties: Many retailers offer extended warranty plans as add-ons to protect customers' purchases beyond the standard warranty period. Product customization: Some businesses allow customers to personalize their products with custom colors, engraving, or other unique features, often for an additional fee. Premium support: E-commerce platforms may offer priority customer support, dedicated account managers, or other enhanced support services as add-ons. Gift wrapping and packaging: Retailers may offer gift wrapping, gift messages, or special packaging options as add-ons, providing customers with a convenient way to send gifts directly to recipients. Installation or assembly services: Some retailers offer professional installation or assembly services for products that require expert setup, often for an additional fee.

To add Add-on to your listing, you need to create an index add_ons in the listing. You can then POST or PATCH the add-on data to the listing's add_ons index.

Categories endpoint is related to Listings. Those categories are created by the admin, from the admin panel or through the API.

Categories can have children categories (or sub-categories), and those children can have themselves children indefinitely.

Manage collections and sub-collections used to group listings by business logic (e.g., construction sites)

Events are generated by some Kreezalid resources when certain actions are completed, such as the creation of a listing, the acceptance of an order, or the sign up of a user.

By requesting events, you can know when certain actions have occurred and trigger relevant actions like updating a third-party service, sending an email to a user or to the admin, etc.

Related to listings tag

When you do actions through the API, like creating a user, a listing or updating an order, no notification is sent. You need to call the notifications endpoint and choose which one to send and to whom.

An order is a customer's request to purchase one or more listings from a supplier. You can retrieve, update, add metafields and delete orders using the Orders endpoint.

Order Status

Orders are automatically created when a product is added to cart (when cart is enabled) or when the customer starts a Direct checkout. The status of the order is then draft.

You can retrieve all you abandonned carts by getting all orders created more than two hours ago and still with draft status.

After checkout, the status should be pending or new, depending on how the payment is handled. Pending status is used with non-automatic payment methods, such as bank wires, cash on delivery or checks. If the payment is made online (with cards), the status should be new if the payment succeeded, or failed if the payment fails. You can also keep the status draft if you want to let the user to retry the payment.

Contrary to e-commerce stores, on a multi-vendor marketplace you cannot be sure the Catalog is always up to date. That's why all orders should be moderated and validated on the vendor's side. Payment Service Provider (PSP) won't refund their fees if a transaction is cancelled. By capturing the funds only on vendor's acceptation, you can avoid losing money on order that are declined by vendors. When the order is reviewed and validated by the vendor, the status becomes accepted. If the order is not accepted, the status becomes declined.

Status service_provided, shipped and customer_confirmed depends on your order workflow, but you can use them in any order you like.

If the vendor cannot fulfill the order, or if the customer want to cancel the order, the status becomes canceled. If money has been captured (probably the case if the status is at least accepted), you need to handle the refund of the funds. The endpoint is not publicly available, but you can ask our support team to send you all relevant documentation to handle it.

Finally, when the order's workflow has come to an end, you can use the status completed. You can now consider the order like closed.

Notifications

No notifications sent when you update the order status through the API. You need to manually manage the sending of notifications. Please check the Notifications endpoint to learn how to send a notification.