Admin API (1.0)
Kreezalid provides an API, which makes it extremely easy for any developer to integrate external systems with our platform - adding their own layer of awesomeness on the top of Kreezalid.
The Admin API lets you build apps and integrations that extend and enhance the Kreezalid admin. You can create your own useful plugins (created exactly to fit your needs), synchronize data with other platforms or even code a customized backup solution - anything you want!
Kreezalid Admin API is organized around REST.
You can view code examples in the dark area to the right; switch the programming language of the examples with the tabs in the top right.
If anything is missing or seems incorrect, please contact our support team.
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:
- Go to your admin panel. For example: https://subdomain.mykreezalid.com/admin
- Click on the
Settings
link in the sidebar, then on the Account button - In the API access section, click on the button
Enable API access
to generate a new secret key - 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.
Retrieve add-on
Authorizations:
path Parameters
id required | integer Add-on's unique identifier |
Responses
Response samples
- 200
{- "add_on": {
- "id": 0,
- "object": "AddOn",
- "listing_id": 324353,
- "title": "Extended Warranty",
- "description": "Protect your purchases beyond the standard warranty period",
- "price": 12.5
}
}
Create a new add-on
Authorizations:
path Parameters
id required | integer Listing's unique identifier |
Request Body schema: application/jsonrequired
AddOn data
title required | string |
price required | number |
description | string |
Responses
Request samples
- Payload
{- "title": "string",
- "price": 0,
- "description": "string"
}
Response samples
- 201
{- "add_on": {
- "id": 432432,
- "object": "Variant",
- "external_id": "INTERNAL_REF_234324",
- "listing_id": 324353,
- "price": 123.5,
- "price_unit": null,
- "quantity": 10,
- "sort_priority": 10,
- "sku": "BASKT-XYZ-BLN-41",
- "title": "Blue Shoes Size 41",
- "weight": 0.8
}
}
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)
Get all collections
Retrieve all collections and its child collections
Authorizations:
Responses
Response samples
- 200
[- {
- "id": 432432,
- "handle": "soldes",
- "title": "Promotions de Printemps",
- "metadata": {
- "last_updated_at": "2025-07-01T10:00:00Z",
- "theme": "blue"
}, - "parent_handle": "promos",
- "created_at": "2025-07-20T10:30:00Z",
- "updated_at": "2025-07-20T14:45:00Z"
}
]
Create collection
Creates a top-level collection (if no parent_handle is provided) or a sub-collection under an existing collection (if parent_handle is set).
Authorizations:
Request Body schema: application/jsonrequired
handle required | string URL-friendly identifier for the collection (slug) |
title required | string Human-readable title of the collection |
metadata | object or null Flexible metadata container for the collection |
parent_handle | string or null Handle of the parent collection, if this is a sub-collection |
Responses
Request samples
- Payload
{- "handle": "soldes",
- "title": "Promotions de Printemps",
- "metadata": {
- "last_updated_at": "2025-07-01T10:00:00Z",
- "theme": "blue"
}, - "parent_handle": "promos"
}
Response samples
- 201
{- "id": 432432,
- "handle": "soldes",
- "title": "Promotions de Printemps",
- "metadata": {
- "last_updated_at": "2025-07-01T10:00:00Z",
- "theme": "blue"
}, - "parent_handle": "promos",
- "created_at": "2025-07-20T10:30:00Z",
- "updated_at": "2025-07-20T14:45:00Z"
}
Update collection
Update an existing collection partially using its handle
Authorizations:
path Parameters
handle required | string The handle (slug) of the collection to update |
Request Body schema: application/jsonrequired
metadata | object |
Responses
Request samples
- Payload
{- "metadata": {
- "last_update_at": "2025-09-30T10:00:00Z"
}
}
Response samples
- 200
{- "id": 432432,
- "handle": "soldes",
- "title": "Promotions de Printemps",
- "metadata": {
- "last_updated_at": "2025-07-01T10:00:00Z",
- "theme": "blue"
}, - "parent_handle": "promos",
- "created_at": "2025-07-20T10:30:00Z",
- "updated_at": "2025-07-20T14:45:00Z"
}
Get associated listings
Get all listings associated with a specific collection or sub-collection
Authorizations:
path Parameters
handle required | string The handle (code) of the collection or sub-collection |
Responses
Response samples
- 200
[- {
- "id": 645646,
- "object": "Listing",
- "admin_status": "approved",
- "attributes": "[]",
- "category": {
- "id": 432432,
- "object": "Category",
- "title": "string",
- "url": "string"
}, - "category_id": 432432,
- "city": "New York City",
- "country": "US",
- "cover": "string",
- "currency": "USD",
- "date_online": "2019-08-24T14:15:22Z",
- "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla dignissim laoreet sem, quis mollis elit rutrum a. Donec nunc urna, rhoncus in sagittis ut, elementum scelerisque libero. Quisque interdum nibh nisl, non gravida nibh molestie quis. Phasellus nunc nunc, luctus a luctus ac, iaculis sit amet turpis.</p><p>Phasellus tortor orci, posuere in mi at, blandit ullamcorper tellus. Proin vel sem aliquam, faucibus dolor quis, dictum leo. Aliquam consectetur massa at ipsum auctor, at mattis nunc porttitor. Suspendisse potenti. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>",
- "external_id": "INTERNAL_REF_234324",
- "lat": 40.7572114,
- "lng": -73.9913385,
- "location": "253 W 42nd St, New York, NY 10036, United States",
- "min_qty": 1,
- "medias": "string",
- "order_type_id": 986545,
- "price": 123.5,
- "price_unit": null,
- "price_with_currency": "$123.50",
- "quantity": 43,
- "quantity_selector": null,
- "requires_shipping": true,
- "shipping_methods": [
- {
- "id": 1,
- "carrier_alias": "fed_ex",
- "price": 4.95,
- "sort_priority": 4,
- "step_price": 0.95,
- "title": "FedEx"
}
], - "slug": "listing-s-slug",
- "state": "NY",
- "status": "published",
- "supplier": {
- "id": 545353,
- "object": "User",
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group": [
- {
- "object": "Group",
- "id": 784568,
- "name": "VIP Customers",
- "alias": "vip-customers"
}
], - "group_alias": "string",
- "group_id": 784568,
- "group_name": "string",
- "lang": "string",
- "last_name": "Doe",
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "profile_url": "string",
- "public_name": "John Doe",
- "status": "enabled",
- "store_id": "123456",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}, - "supplier_id": 655785,
- "title": "Listing's title",
- "url": "string",
- "variants": {
- "id": 432432,
- "object": "Variant",
- "external_id": "INTERNAL_REF_234324",
- "listing_id": 324353,
- "price": 123.5,
- "price_unit": null,
- "quantity": 10,
- "sort_priority": 10,
- "sku": "BASKT-XYZ-BLN-41",
- "title": "Blue Shoes Size 41",
- "weight": 0.8
}, - "visibility": "both",
- "weight": 0.8
}
]
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.
Retrieve a list of events
Returns a list of your events. The events are returned sorted by creation date, with the most recent events appearing first.
Authorizations:
Responses
Response samples
- 200
[- {
- "id": 0,
- "type": "string",
- "status": "string",
- "object": "string",
- "object_id": 0,
- "created": "2019-08-24T14:15:22Z"
}
]
Retrieve an event
Retrieves the details of an existing event. You need only supply the unique event identifier that was returned upon event creation.
Authorizations:
path Parameters
id required | integer ID of your event. |
Responses
Response samples
- 200
[- {
- "id": 0,
- "type": "string",
- "status": "string",
- "object": "string",
- "object_id": 0,
- "created": "2019-08-24T14:15:22Z"
}
]
Get listings
Retrieves a list of listings with optional filters and customizable response fields.
This endpoint returns a paginated list of listings. You can filter the results using various
query parameters such as user ID, status, admin review status, category ID, and more.
Additionally, you can reduce the payload size by selecting only the fields you need via the fields
parameter.
Examples:
/listings?user_id=123&status=published
/listings?user_id=123&admin_status[]=waiting&admin_status[]=rejected
/listings?category_id=5,9&fields=id,title,price
If the fields
parameter is omitted, all default fields will be included.
If the fields
parameter is specified, only those fields will be returned.
Authorizations:
query Parameters
admin_status | string Example: admin_status=approved,rejected,waiting or blocked Filter by admin status. Can be a single value or a comma-separated list (e.g. approved,rejected,waiting or blocked). |
category_id | string Example: category_id=12,34 Filter by category ID(s). Can be a single ID or a comma-separated list. |
fields | string Example: fields=title,price,attributes Comma-separated list of fields to include in the response (e.g. title,price,attributes). |
on_homepage | boolean Example: on_homepage=false Filter listings that are marked to appear on the homepage (1 = yes, 0 = no). |
order_type_id | integer Example: order_type_id=2 Filter by order type ID. |
status | string Example: status=published,draft,archived Filter by listing status. Can be a single value or a comma-separated list (e.g. published,draft or archived). |
user_id | string Example: user_id=123,456 Filter by user ID(s). Can be a single ID or comma-separated list. |
Responses
Response samples
- 200
[- {
- "id": 645646,
- "object": "Listing",
- "admin_status": "approved",
- "attributes": "[]",
- "category": {
- "id": 432432,
- "object": "Category",
- "title": "string",
- "url": "string"
}, - "category_id": 432432,
- "city": "New York City",
- "country": "US",
- "cover": "string",
- "currency": "USD",
- "date_online": "2019-08-24T14:15:22Z",
- "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla dignissim laoreet sem, quis mollis elit rutrum a. Donec nunc urna, rhoncus in sagittis ut, elementum scelerisque libero. Quisque interdum nibh nisl, non gravida nibh molestie quis. Phasellus nunc nunc, luctus a luctus ac, iaculis sit amet turpis.</p><p>Phasellus tortor orci, posuere in mi at, blandit ullamcorper tellus. Proin vel sem aliquam, faucibus dolor quis, dictum leo. Aliquam consectetur massa at ipsum auctor, at mattis nunc porttitor. Suspendisse potenti. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>",
- "external_id": "INTERNAL_REF_234324",
- "lat": 40.7572114,
- "lng": -73.9913385,
- "location": "253 W 42nd St, New York, NY 10036, United States",
- "min_qty": 1,
- "medias": "string",
- "order_type_id": 986545,
- "price": 123.5,
- "price_unit": null,
- "price_with_currency": "$123.50",
- "quantity": 43,
- "quantity_selector": null,
- "requires_shipping": true,
- "shipping_methods": [
- {
- "id": 1,
- "carrier_alias": "fed_ex",
- "price": 4.95,
- "sort_priority": 4,
- "step_price": 0.95,
- "title": "FedEx"
}
], - "slug": "listing-s-slug",
- "state": "NY",
- "status": "published",
- "supplier": {
- "id": 545353,
- "object": "User",
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group": [
- {
- "object": "Group",
- "id": 784568,
- "name": "VIP Customers",
- "alias": "vip-customers"
}
], - "group_alias": "string",
- "group_id": 784568,
- "group_name": "string",
- "lang": "string",
- "last_name": "Doe",
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "profile_url": "string",
- "public_name": "John Doe",
- "status": "enabled",
- "store_id": "123456",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}, - "supplier_id": 655785,
- "title": "Listing's title",
- "url": "string",
- "variants": {
- "id": 432432,
- "object": "Variant",
- "external_id": "INTERNAL_REF_234324",
- "listing_id": 324353,
- "price": 123.5,
- "price_unit": null,
- "quantity": 10,
- "sort_priority": 10,
- "sku": "BASKT-XYZ-BLN-41",
- "title": "Blue Shoes Size 41",
- "weight": 0.8
}, - "visibility": "both",
- "weight": 0.8
}
]
Create listing
Authorizations:
Request Body schema: application/jsonrequired
admin_status | string Enum: "waiting" "approved" "rejected" "blocked" Admin validation status of the listing. Possible values: waiting (awaiting approval), approved (visible if status also published), rejected (hidden from the marketplace). |
attributes | Array of any |
object (Category) | |
category_id required | integer Category's unique identifier |
city | string or null |
country | string or null |
currency | string |
date_online | string <date-time> |
description | string or null |
external_id | string or null |
lat | number or null |
lng | number or null |
location | string or null |
min_qty | number or null |
medias | string |
order_type_id required | integer Order type's unique identifier |
price | number or null |
price_unit | integer or null |
quantity | integer or null |
quantity_selector | string or null |
requires_shipping | boolean |
Array of objects | |
slug | string or null |
state | string or null |
status | string Enum: "draft" "published" "archived" Public status of the listing. Possible values: draft, published (visible), archived (hidden). |
object (User resource) | |
supplier_id required | integer Supplier's unique identifier |
title required | string |
object (Variant) | |
visibility | string Enum: "both" "catalog" "search" "none" Defines where the listing is displayed. Possible values: both (visible in catalog and search), catalog (only catalog), search (only search results), none (not visible). |
weight | number |
Responses
Request samples
- Payload
{- "admin_status": "approved",
- "attributes": "[]",
- "category": {
- "title": "string"
}, - "category_id": 432432,
- "city": "New York City",
- "country": "US",
- "currency": "USD",
- "date_online": "2019-08-24T14:15:22Z",
- "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla dignissim laoreet sem, quis mollis elit rutrum a. Donec nunc urna, rhoncus in sagittis ut, elementum scelerisque libero. Quisque interdum nibh nisl, non gravida nibh molestie quis. Phasellus nunc nunc, luctus a luctus ac, iaculis sit amet turpis.</p><p>Phasellus tortor orci, posuere in mi at, blandit ullamcorper tellus. Proin vel sem aliquam, faucibus dolor quis, dictum leo. Aliquam consectetur massa at ipsum auctor, at mattis nunc porttitor. Suspendisse potenti. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>",
- "external_id": "INTERNAL_REF_234324",
- "lat": 40.7572114,
- "lng": -73.9913385,
- "location": "253 W 42nd St, New York, NY 10036, United States",
- "min_qty": 1,
- "medias": "string",
- "order_type_id": 986545,
- "price": 123.5,
- "price_unit": null,
- "quantity": 43,
- "quantity_selector": null,
- "requires_shipping": true,
- "shipping_methods": [
- {
- "id": 1,
- "carrier_alias": "fed_ex",
- "price": 4.95,
- "sort_priority": 4,
- "step_price": 0.95,
- "title": "FedEx"
}
], - "slug": "listing-s-slug",
- "state": "NY",
- "status": "published",
- "supplier": {
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group_id": 784568,
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "status": "enabled",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}, - "supplier_id": 655785,
- "title": "Listing's title",
- "variants": {
- "external_id": "INTERNAL_REF_234324",
- "listing_id": 324353,
- "price": 123.5,
- "price_unit": null,
- "quantity": 10,
- "sort_priority": 10,
- "sku": "BASKT-XYZ-BLN-41",
- "title": "Blue Shoes Size 41",
- "weight": 0.8
}, - "visibility": "both",
- "weight": 0.8
}
Response samples
- 200
[- {
- "id": 645646,
- "object": "Listing",
- "admin_status": "approved",
- "attributes": "[]",
- "category": {
- "id": 432432,
- "object": "Category",
- "title": "string",
- "url": "string"
}, - "category_id": 432432,
- "city": "New York City",
- "country": "US",
- "cover": "string",
- "currency": "USD",
- "date_online": "2019-08-24T14:15:22Z",
- "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla dignissim laoreet sem, quis mollis elit rutrum a. Donec nunc urna, rhoncus in sagittis ut, elementum scelerisque libero. Quisque interdum nibh nisl, non gravida nibh molestie quis. Phasellus nunc nunc, luctus a luctus ac, iaculis sit amet turpis.</p><p>Phasellus tortor orci, posuere in mi at, blandit ullamcorper tellus. Proin vel sem aliquam, faucibus dolor quis, dictum leo. Aliquam consectetur massa at ipsum auctor, at mattis nunc porttitor. Suspendisse potenti. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>",
- "external_id": "INTERNAL_REF_234324",
- "lat": 40.7572114,
- "lng": -73.9913385,
- "location": "253 W 42nd St, New York, NY 10036, United States",
- "min_qty": 1,
- "medias": "string",
- "order_type_id": 986545,
- "price": 123.5,
- "price_unit": null,
- "price_with_currency": "$123.50",
- "quantity": 43,
- "quantity_selector": null,
- "requires_shipping": true,
- "shipping_methods": [
- {
- "id": 1,
- "carrier_alias": "fed_ex",
- "price": 4.95,
- "sort_priority": 4,
- "step_price": 0.95,
- "title": "FedEx"
}
], - "slug": "listing-s-slug",
- "state": "NY",
- "status": "published",
- "supplier": {
- "id": 545353,
- "object": "User",
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group": [
- {
- "object": "Group",
- "id": 784568,
- "name": "VIP Customers",
- "alias": "vip-customers"
}
], - "group_alias": "string",
- "group_id": 784568,
- "group_name": "string",
- "lang": "string",
- "last_name": "Doe",
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "profile_url": "string",
- "public_name": "John Doe",
- "status": "enabled",
- "store_id": "123456",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}, - "supplier_id": 655785,
- "title": "Listing's title",
- "url": "string",
- "variants": {
- "id": 432432,
- "object": "Variant",
- "external_id": "INTERNAL_REF_234324",
- "listing_id": 324353,
- "price": 123.5,
- "price_unit": null,
- "quantity": 10,
- "sort_priority": 10,
- "sku": "BASKT-XYZ-BLN-41",
- "title": "Blue Shoes Size 41",
- "weight": 0.8
}, - "visibility": "both",
- "weight": 0.8
}
]
Retrieve listing
Authorizations:
path Parameters
id required | integer Listing's unique identifier |
Responses
Response samples
- 200
{- "id": 645646,
- "object": "Listing",
- "admin_status": "approved",
- "attributes": "[]",
- "category": {
- "id": 432432,
- "object": "Category",
- "title": "string",
- "url": "string"
}, - "category_id": 432432,
- "city": "New York City",
- "country": "US",
- "cover": "string",
- "currency": "USD",
- "date_online": "2019-08-24T14:15:22Z",
- "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla dignissim laoreet sem, quis mollis elit rutrum a. Donec nunc urna, rhoncus in sagittis ut, elementum scelerisque libero. Quisque interdum nibh nisl, non gravida nibh molestie quis. Phasellus nunc nunc, luctus a luctus ac, iaculis sit amet turpis.</p><p>Phasellus tortor orci, posuere in mi at, blandit ullamcorper tellus. Proin vel sem aliquam, faucibus dolor quis, dictum leo. Aliquam consectetur massa at ipsum auctor, at mattis nunc porttitor. Suspendisse potenti. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>",
- "external_id": "INTERNAL_REF_234324",
- "lat": 40.7572114,
- "lng": -73.9913385,
- "location": "253 W 42nd St, New York, NY 10036, United States",
- "min_qty": 1,
- "medias": "string",
- "order_type_id": 986545,
- "price": 123.5,
- "price_unit": null,
- "price_with_currency": "$123.50",
- "quantity": 43,
- "quantity_selector": null,
- "requires_shipping": true,
- "shipping_methods": [
- {
- "id": 1,
- "carrier_alias": "fed_ex",
- "price": 4.95,
- "sort_priority": 4,
- "step_price": 0.95,
- "title": "FedEx"
}
], - "slug": "listing-s-slug",
- "state": "NY",
- "status": "published",
- "supplier": {
- "id": 545353,
- "object": "User",
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group": [
- {
- "object": "Group",
- "id": 784568,
- "name": "VIP Customers",
- "alias": "vip-customers"
}
], - "group_alias": "string",
- "group_id": 784568,
- "group_name": "string",
- "lang": "string",
- "last_name": "Doe",
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "profile_url": "string",
- "public_name": "John Doe",
- "status": "enabled",
- "store_id": "123456",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}, - "supplier_id": 655785,
- "title": "Listing's title",
- "url": "string",
- "variants": {
- "id": 432432,
- "object": "Variant",
- "external_id": "INTERNAL_REF_234324",
- "listing_id": 324353,
- "price": 123.5,
- "price_unit": null,
- "quantity": 10,
- "sort_priority": 10,
- "sku": "BASKT-XYZ-BLN-41",
- "title": "Blue Shoes Size 41",
- "weight": 0.8
}, - "visibility": "both",
- "weight": 0.8
}
Update listing
Authorizations:
path Parameters
id required | integer Listing's unique identifier |
Request Body schema: application/jsonrequired
admin_status | string Enum: "waiting" "approved" "rejected" "blocked" Admin validation status of the listing. Possible values: waiting (awaiting approval), approved (visible if status also published), rejected (hidden from the marketplace). |
attributes | Array of any |
object (Category) | |
category_id required | integer Category's unique identifier |
city | string or null |
country | string or null |
currency | string |
date_online | string <date-time> |
description | string or null |
external_id | string or null |
lat | number or null |
lng | number or null |
location | string or null |
min_qty | number or null |
medias | string |
order_type_id required | integer Order type's unique identifier |
price | number or null |
price_unit | integer or null |
quantity | integer or null |
quantity_selector | string or null |
requires_shipping | boolean |
Array of objects | |
slug | string or null |
state | string or null |
status | string Enum: "draft" "published" "archived" Public status of the listing. Possible values: draft, published (visible), archived (hidden). |
object (User resource) | |
supplier_id required | integer Supplier's unique identifier |
title required | string |
object (Variant) | |
visibility | string Enum: "both" "catalog" "search" "none" Defines where the listing is displayed. Possible values: both (visible in catalog and search), catalog (only catalog), search (only search results), none (not visible). |
weight | number |
Responses
Request samples
- Payload
{- "admin_status": "approved",
- "attributes": "[]",
- "category": {
- "title": "string"
}, - "category_id": 432432,
- "city": "New York City",
- "country": "US",
- "currency": "USD",
- "date_online": "2019-08-24T14:15:22Z",
- "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla dignissim laoreet sem, quis mollis elit rutrum a. Donec nunc urna, rhoncus in sagittis ut, elementum scelerisque libero. Quisque interdum nibh nisl, non gravida nibh molestie quis. Phasellus nunc nunc, luctus a luctus ac, iaculis sit amet turpis.</p><p>Phasellus tortor orci, posuere in mi at, blandit ullamcorper tellus. Proin vel sem aliquam, faucibus dolor quis, dictum leo. Aliquam consectetur massa at ipsum auctor, at mattis nunc porttitor. Suspendisse potenti. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>",
- "external_id": "INTERNAL_REF_234324",
- "lat": 40.7572114,
- "lng": -73.9913385,
- "location": "253 W 42nd St, New York, NY 10036, United States",
- "min_qty": 1,
- "medias": "string",
- "order_type_id": 986545,
- "price": 123.5,
- "price_unit": null,
- "quantity": 43,
- "quantity_selector": null,
- "requires_shipping": true,
- "shipping_methods": [
- {
- "id": 1,
- "carrier_alias": "fed_ex",
- "price": 4.95,
- "sort_priority": 4,
- "step_price": 0.95,
- "title": "FedEx"
}
], - "slug": "listing-s-slug",
- "state": "NY",
- "status": "published",
- "supplier": {
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group_id": 784568,
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "status": "enabled",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}, - "supplier_id": 655785,
- "title": "Listing's title",
- "variants": {
- "external_id": "INTERNAL_REF_234324",
- "listing_id": 324353,
- "price": 123.5,
- "price_unit": null,
- "quantity": 10,
- "sort_priority": 10,
- "sku": "BASKT-XYZ-BLN-41",
- "title": "Blue Shoes Size 41",
- "weight": 0.8
}, - "visibility": "both",
- "weight": 0.8
}
Response samples
- 200
{- "success": true,
- "message": "Listing has been updated"
}
Response samples
- 200
[- {
- "id": 645646,
- "object": "Listing",
- "admin_status": "approved",
- "attributes": "[]",
- "category": {
- "id": 432432,
- "object": "Category",
- "title": "string",
- "url": "string"
}, - "category_id": 432432,
- "city": "New York City",
- "country": "US",
- "cover": "string",
- "currency": "USD",
- "date_online": "2019-08-24T14:15:22Z",
- "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla dignissim laoreet sem, quis mollis elit rutrum a. Donec nunc urna, rhoncus in sagittis ut, elementum scelerisque libero. Quisque interdum nibh nisl, non gravida nibh molestie quis. Phasellus nunc nunc, luctus a luctus ac, iaculis sit amet turpis.</p><p>Phasellus tortor orci, posuere in mi at, blandit ullamcorper tellus. Proin vel sem aliquam, faucibus dolor quis, dictum leo. Aliquam consectetur massa at ipsum auctor, at mattis nunc porttitor. Suspendisse potenti. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>",
- "external_id": "INTERNAL_REF_234324",
- "lat": 40.7572114,
- "lng": -73.9913385,
- "location": "253 W 42nd St, New York, NY 10036, United States",
- "min_qty": 1,
- "medias": "string",
- "order_type_id": 986545,
- "price": 123.5,
- "price_unit": null,
- "price_with_currency": "$123.50",
- "quantity": 43,
- "quantity_selector": null,
- "requires_shipping": true,
- "shipping_methods": [
- {
- "id": 1,
- "carrier_alias": "fed_ex",
- "price": 4.95,
- "sort_priority": 4,
- "step_price": 0.95,
- "title": "FedEx"
}
], - "slug": "listing-s-slug",
- "state": "NY",
- "status": "published",
- "supplier": {
- "id": 545353,
- "object": "User",
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group": [
- {
- "object": "Group",
- "id": 784568,
- "name": "VIP Customers",
- "alias": "vip-customers"
}
], - "group_alias": "string",
- "group_id": 784568,
- "group_name": "string",
- "lang": "string",
- "last_name": "Doe",
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "profile_url": "string",
- "public_name": "John Doe",
- "status": "enabled",
- "store_id": "123456",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}, - "supplier_id": 655785,
- "title": "Listing's title",
- "url": "string",
- "variants": {
- "id": 432432,
- "object": "Variant",
- "external_id": "INTERNAL_REF_234324",
- "listing_id": 324353,
- "price": 123.5,
- "price_unit": null,
- "quantity": 10,
- "sort_priority": 10,
- "sku": "BASKT-XYZ-BLN-41",
- "title": "Blue Shoes Size 41",
- "weight": 0.8
}, - "visibility": "both",
- "weight": 0.8
}
]
Rebuild Elasticsearch index
We use an Elasticsearch server to enable full-text search, filter, and sort on your store.
To display listings in search results, listings need to be indexed first. After each listing creation or update. We automatically remove the listings from the user account that have been blocked or deleted. But when you create your listings from the API, those listings are not automatically indexed.
By using this endpoint, you can choose to reindex all your listings, or only those that are not indexed yet.
For performance reason, you should limit the number of listings indexed at once. The Default value is 999.
Authorizations:
query Parameters
scope | string Possible values: 'all' to reindex all your listings, or 'not_indexed' to reindex only listings that have been modified after the last indexation. Default value is 'not_indexed'. |
limit | integer Number of listings to reindex at once. Default value is 999. |
Responses
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.
Send a notification
Authorizations:
Request Body schema: application/json
TEST desc
type required | string Enum: "new_order_customer" "new_order_supplier" desc type |
object_id required | integer |
Responses
Request samples
- Payload
{- "type": "new_order_customer",
- "object_id": 185423
}
Response samples
- 200
{- "success": true,
- "data": {
- "id": 234432,
- "object_id": 185423,
- "content": {
- "subject": "You have a new order ...",
- "body": " .... "
}, - "created": "2023-01-18T23:42:27Z",
- "recipient": "toto@test.mail",
- "transport": "email",
- "type": "new_order_customer"
}
}
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.
Get orders
Authorizations:
query Parameters
id | Array of strings ID(s) to filter by |
status | Array of strings Example: status=?status=new ?status=new,closed Status to retrieve. To filter on multiple status, separate them by comma |
cart_id | integer Example: cart_id=432644 Cart's unique identifier |
supplier_id | integer Example: supplier_id=432244 Vendor's unique identifier |
customer_id | integer Example: customer_id=432245 Customer's unique identifier |
order_number | string Example: order_number=2301FDSKFSDKL Order number |
start_on_date[value] | string <date-time> Example: start_on_date[value]=2023-01-24 Filtering value |
start_on_date[condition_type] | string Enum: "gt" "gte" "lt" "lte" "eq" "notEq" "like" "notLike" "in" "notIn" Example: start_on_date[condition_type]=gte Filtering type |
Responses
Response samples
- 200
[- {
- "id": 0,
- "object": "string",
- "number": "string",
- "order_number": "string",
- "amount": 0,
- "currency": "string",
- "amount_with_currency": 0,
- "status": "string",
- "refusal_reason": "string",
- "supplier": {
- "id": 545353,
- "object": "User",
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group": [
- {
- "object": "Group",
- "id": 784568,
- "name": "VIP Customers",
- "alias": "vip-customers"
}
], - "group_alias": "string",
- "group_id": 784568,
- "group_name": "string",
- "lang": "string",
- "last_name": "Doe",
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "profile_url": "string",
- "public_name": "John Doe",
- "status": "enabled",
- "store_id": "123456",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}, - "customer": {
- "id": 545353,
- "object": "User",
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group": [
- {
- "object": "Group",
- "id": 784568,
- "name": "VIP Customers",
- "alias": "vip-customers"
}
], - "group_alias": "string",
- "group_id": 784568,
- "group_name": "string",
- "lang": "string",
- "last_name": "Doe",
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "profile_url": "string",
- "public_name": "John Doe",
- "status": "enabled",
- "store_id": "123456",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}, - "checkout_message": "string",
- "customer_url": "string",
- "supplier_url": "string",
- "checkout_at": "2019-08-24T14:15:22Z",
- "fulfillment_status": "started",
- "shippings": {
- "id": 0,
- "amount": 0,
- "carrier": "string",
- "title": "string",
- "tracking_number": "string",
- "tracking_url": "string",
- "address": {
- "id": 0,
- "object": "string",
- "city": "string",
- "country": "string",
- "mobile": "string",
- "name": "string",
- "phone": "string",
- "postcode": "string",
- "state": "string",
- "street": "string",
- "street_option": "string"
}
}, - "shipping_fees_destination": "platform",
- "payout": {
- "status": "string",
- "amount": 0,
- "currency_code": "string",
- "requested_at": "2019-08-24T14:15:22Z",
- "completed_at": "2019-08-24T14:15:22Z",
- "arrival_date": "2019-08-24T14:15:22Z"
}, - "smart_fees": [
- {
- "fee_target": "string",
- "rule_title": "string",
- "fee_amount": "string"
}
], - "order_items": [
- {
- "object": "string",
- "id": 0,
- "add_ons": [
- null
], - "amount": 0,
- "configurable_options": [
- null
], - "currency": "string",
- "downloadable_assets": [
- null
], - "listing": {
- "id": 645646,
- "object": "Listing",
- "admin_status": "approved",
- "attributes": "[]",
- "category": {
- "id": 432432,
- "object": "Category",
- "title": "string",
- "url": "string"
}, - "category_id": 432432,
- "city": "New York City",
- "country": "US",
- "cover": "string",
- "currency": "USD",
- "date_online": "2019-08-24T14:15:22Z",
- "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla dignissim laoreet sem, quis mollis elit rutrum a. Donec nunc urna, rhoncus in sagittis ut, elementum scelerisque libero. Quisque interdum nibh nisl, non gravida nibh molestie quis. Phasellus nunc nunc, luctus a luctus ac, iaculis sit amet turpis.</p><p>Phasellus tortor orci, posuere in mi at, blandit ullamcorper tellus. Proin vel sem aliquam, faucibus dolor quis, dictum leo. Aliquam consectetur massa at ipsum auctor, at mattis nunc porttitor. Suspendisse potenti. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>",
- "external_id": "INTERNAL_REF_234324",
- "lat": 40.7572114,
- "lng": -73.9913385,
- "location": "253 W 42nd St, New York, NY 10036, United States",
- "min_qty": 1,
- "medias": "string",
- "order_type_id": 986545,
- "price": 123.5,
- "price_unit": null,
- "price_with_currency": "$123.50",
- "quantity": 43,
- "quantity_selector": null,
- "requires_shipping": true,
- "shipping_methods": [
- {
- "id": 1,
- "carrier_alias": "fed_ex",
- "price": 4.95,
- "sort_priority": 4,
- "step_price": 0.95,
- "title": "FedEx"
}
], - "slug": "listing-s-slug",
- "state": "NY",
- "status": "published",
- "supplier": {
- "id": 545353,
- "object": "User",
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group": [
- {
- "object": "Group",
- "id": 784568,
- "name": "VIP Customers",
- "alias": "vip-customers"
}
], - "group_alias": "string",
- "group_id": 784568,
- "group_name": "string",
- "lang": "string",
- "last_name": "Doe",
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "profile_url": "string",
- "public_name": "John Doe",
- "status": "enabled",
- "store_id": "123456",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}, - "supplier_id": 655785,
- "title": "Listing's title",
- "url": "string",
- "variants": {
- "id": 432432,
- "object": "Variant",
- "external_id": "INTERNAL_REF_234324",
- "listing_id": 324353,
- "price": 123.5,
- "price_unit": null,
- "quantity": 10,
- "sort_priority": 10,
- "sku": "BASKT-XYZ-BLN-41",
- "title": "Blue Shoes Size 41",
- "weight": 0.8
}, - "visibility": "both",
- "weight": 0.8
}, - "listing_id": 0,
- "listing_image": "string",
- "listing_sku": "string",
- "listing_title": "string",
- "listing_unit_price": 0,
- "custom_unit_price": 0,
- "listing_weight": 0,
- "qty": 0,
- "token": "string",
- "properties": [
- null
]
}
]
}
]
Retrieve order
View method
Authorizations:
path Parameters
id required | integer ID of your order |
Responses
Response samples
- 200
[- {
- "id": 0,
- "object": "string",
- "number": "string",
- "order_number": "string",
- "amount": 0,
- "currency": "string",
- "amount_with_currency": 0,
- "status": "string",
- "refusal_reason": "string",
- "supplier": {
- "id": 545353,
- "object": "User",
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group": [
- {
- "object": "Group",
- "id": 784568,
- "name": "VIP Customers",
- "alias": "vip-customers"
}
], - "group_alias": "string",
- "group_id": 784568,
- "group_name": "string",
- "lang": "string",
- "last_name": "Doe",
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "profile_url": "string",
- "public_name": "John Doe",
- "status": "enabled",
- "store_id": "123456",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}, - "customer": {
- "id": 545353,
- "object": "User",
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group": [
- {
- "object": "Group",
- "id": 784568,
- "name": "VIP Customers",
- "alias": "vip-customers"
}
], - "group_alias": "string",
- "group_id": 784568,
- "group_name": "string",
- "lang": "string",
- "last_name": "Doe",
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "profile_url": "string",
- "public_name": "John Doe",
- "status": "enabled",
- "store_id": "123456",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}, - "checkout_message": "string",
- "customer_url": "string",
- "supplier_url": "string",
- "checkout_at": "2019-08-24T14:15:22Z",
- "fulfillment_status": "started",
- "shippings": {
- "id": 0,
- "amount": 0,
- "carrier": "string",
- "title": "string",
- "tracking_number": "string",
- "tracking_url": "string",
- "address": {
- "id": 0,
- "object": "string",
- "city": "string",
- "country": "string",
- "mobile": "string",
- "name": "string",
- "phone": "string",
- "postcode": "string",
- "state": "string",
- "street": "string",
- "street_option": "string"
}
}, - "shipping_fees_destination": "platform",
- "payout": {
- "status": "string",
- "amount": 0,
- "currency_code": "string",
- "requested_at": "2019-08-24T14:15:22Z",
- "completed_at": "2019-08-24T14:15:22Z",
- "arrival_date": "2019-08-24T14:15:22Z"
}, - "smart_fees": [
- {
- "fee_target": "string",
- "rule_title": "string",
- "fee_amount": "string"
}
], - "order_items": [
- {
- "object": "string",
- "id": 0,
- "add_ons": [
- null
], - "amount": 0,
- "configurable_options": [
- null
], - "currency": "string",
- "downloadable_assets": [
- null
], - "listing": {
- "id": 645646,
- "object": "Listing",
- "admin_status": "approved",
- "attributes": "[]",
- "category": {
- "id": 432432,
- "object": "Category",
- "title": "string",
- "url": "string"
}, - "category_id": 432432,
- "city": "New York City",
- "country": "US",
- "cover": "string",
- "currency": "USD",
- "date_online": "2019-08-24T14:15:22Z",
- "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla dignissim laoreet sem, quis mollis elit rutrum a. Donec nunc urna, rhoncus in sagittis ut, elementum scelerisque libero. Quisque interdum nibh nisl, non gravida nibh molestie quis. Phasellus nunc nunc, luctus a luctus ac, iaculis sit amet turpis.</p><p>Phasellus tortor orci, posuere in mi at, blandit ullamcorper tellus. Proin vel sem aliquam, faucibus dolor quis, dictum leo. Aliquam consectetur massa at ipsum auctor, at mattis nunc porttitor. Suspendisse potenti. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>",
- "external_id": "INTERNAL_REF_234324",
- "lat": 40.7572114,
- "lng": -73.9913385,
- "location": "253 W 42nd St, New York, NY 10036, United States",
- "min_qty": 1,
- "medias": "string",
- "order_type_id": 986545,
- "price": 123.5,
- "price_unit": null,
- "price_with_currency": "$123.50",
- "quantity": 43,
- "quantity_selector": null,
- "requires_shipping": true,
- "shipping_methods": [
- {
- "id": 1,
- "carrier_alias": "fed_ex",
- "price": 4.95,
- "sort_priority": 4,
- "step_price": 0.95,
- "title": "FedEx"
}
], - "slug": "listing-s-slug",
- "state": "NY",
- "status": "published",
- "supplier": {
- "id": 545353,
- "object": "User",
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group": [
- {
- "object": "Group",
- "id": 784568,
- "name": "VIP Customers",
- "alias": "vip-customers"
}
], - "group_alias": "string",
- "group_id": 784568,
- "group_name": "string",
- "lang": "string",
- "last_name": "Doe",
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "profile_url": "string",
- "public_name": "John Doe",
- "status": "enabled",
- "store_id": "123456",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}, - "supplier_id": 655785,
- "title": "Listing's title",
- "url": "string",
- "variants": {
- "id": 432432,
- "object": "Variant",
- "external_id": "INTERNAL_REF_234324",
- "listing_id": 324353,
- "price": 123.5,
- "price_unit": null,
- "quantity": 10,
- "sort_priority": 10,
- "sku": "BASKT-XYZ-BLN-41",
- "title": "Blue Shoes Size 41",
- "weight": 0.8
}, - "visibility": "both",
- "weight": 0.8
}, - "listing_id": 0,
- "listing_image": "string",
- "listing_sku": "string",
- "listing_title": "string",
- "listing_unit_price": 0,
- "custom_unit_price": 0,
- "listing_weight": 0,
- "qty": 0,
- "token": "string",
- "properties": [
- null
]
}
]
}
]
A Payment Gateway API is a set of protocols and procedures that allow e-commerce websites, online stores, and other businesses to securely process payments over the internet. It provides a connection between a customer's bank or credit card issuer and the online store, and handles the secure transfer of payment data.
Update payment gateway
Authorizations:
path Parameters
id required | integer ID of the payment gateway |
Request Body schema: application/jsonrequired
Responses
Request samples
- Payload
{- "title": "Your Title",
- "sandbox": false,
- "status": "active",
- "currency": "EUR",
- "min_transaction_size": 10,
- "max_transaction_size": 5000,
- "settings": [ ]
}
Create a new PSP user
Authorizations:
path Parameters
user_id required | integer ID of the user |
Request Body schema: application/jsonrequired
Responses
Request samples
- Payload
{- "external_account_id": 5,
- "gateway_id": 12,
- "properties": {
- "preference": "static"
}, - "tos_acceptance": {
- "date": null,
- "user_agent": "merchant",
- "ip": "16.16.16.16"
}
}
Update specific PSP user
Authorizations:
path Parameters
user_id required | integer ID of the user |
account_id required | integer ID of the PSP user |
Request Body schema: application/jsonrequired
Responses
Request samples
- Payload
{- "external_account_id": 6,
- "gateway_id": 17,
- "properties": {
- "preference": "dynamic"
}, - "tos_acceptance": {
- "date": null,
- "user_agent": "merchant",
- "ip": "20.20.22.2"
}
}
Shipping rates are what you charge your customer in addition to the cost of the listings that they order. The cost of any shipping rates are added to a customer's order at checkout.
Retrieve a shipping rate
Authorizations:
path Parameters
id required | integer ID of your shipping rate. |
Responses
Response samples
- 200
{- "id": "432424",
- "price": "6.95",
- "step_price": "1.45",
- "always_selected": true,
- "title": "Standard",
- "tracking_number": null,
- "tracking_url": null
}
List all users
Returns a list of your users. The users are returned sorted by creation date, with the most recent users appearing first.
Authorizations:
Responses
Response samples
- 200
[- {
- "id": 545353,
- "object": "User",
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group": [
- {
- "object": "Group",
- "id": 784568,
- "name": "VIP Customers",
- "alias": "vip-customers"
}
], - "group_alias": "string",
- "group_id": 784568,
- "group_name": "string",
- "lang": "string",
- "last_name": "Doe",
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "profile_url": "string",
- "public_name": "John Doe",
- "status": "enabled",
- "store_id": "123456",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}
]
Add user
Authorizations:
Request Body schema: application/jsonrequired
account_type | string Enum: "individual" "company" "non-profit" |
external_id | string or null |
address_city | string |
address_country | string |
address_line1 | string or null |
address_line2 | string or null |
address_state | string or null |
address_zipcode | string or null |
attributes | Array of any or null |
avatar | string or null Absolute URL of the profile image |
business_name | string or null Company or organization name |
can_post_listing | boolean |
created | string <date-time> |
email required | string |
first_name | string or null |
group_id required | integer Deprecated |
locale | string or null |
note | integer Average note based on reviews |
phone_country_number | string or null |
phone_number | string or null |
status | string Enum: "enabled" "disabled" Account status. Possible values are "enabled2" or "disabled" |
review_count | integer |
timezone | string Default: "UTC" |
username | string or null |
Responses
Request samples
- Payload
{- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group_id": 784568,
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "status": "enabled",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}
Response samples
- 201
- 400
- 401
- 404
{- "id": 545353,
- "object": "User",
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group": [
- {
- "object": "Group",
- "id": 784568,
- "name": "VIP Customers",
- "alias": "vip-customers"
}
], - "group_alias": "string",
- "group_id": 784568,
- "group_name": "string",
- "lang": "string",
- "last_name": "Doe",
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "profile_url": "string",
- "public_name": "John Doe",
- "status": "enabled",
- "store_id": "123456",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}
Retrieve user
Authorizations:
path Parameters
id required | integer Unique identifier of the user |
Responses
Response samples
- 200
{- "id": 545353,
- "object": "User",
- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group": [
- {
- "object": "Group",
- "id": 784568,
- "name": "VIP Customers",
- "alias": "vip-customers"
}
], - "group_alias": "string",
- "group_id": 784568,
- "group_name": "string",
- "lang": "string",
- "last_name": "Doe",
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "profile_url": "string",
- "public_name": "John Doe",
- "status": "enabled",
- "store_id": "123456",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}
Update user
Authorizations:
path Parameters
id required | integer User's unique identifier |
Request Body schema: application/jsonrequired
account_type | string Enum: "individual" "company" "non-profit" |
external_id | string or null |
address_city | string |
address_country | string |
address_line1 | string or null |
address_line2 | string or null |
address_state | string or null |
address_zipcode | string or null |
attributes | Array of any or null |
avatar | string or null Absolute URL of the profile image |
business_name | string or null Company or organization name |
can_post_listing | boolean |
created | string <date-time> |
email required | string |
first_name | string or null |
group_id required | integer Deprecated |
locale | string or null |
note | integer Average note based on reviews |
phone_country_number | string or null |
phone_number | string or null |
status | string Enum: "enabled" "disabled" Account status. Possible values are "enabled2" or "disabled" |
review_count | integer |
timezone | string Default: "UTC" |
username | string or null |
Responses
Request samples
- Payload
{- "account_type": "individual",
- "external_id": "ABCdef123456",
- "address_city": "New-York City",
- "address_country": "US",
- "address_line1": "253 W 42nd St",
- "address_line2": null,
- "address_state": "NY",
- "address_zipcode": "NY 10036",
- "attributes": {
- "profession": "Web developer"
}, - "avatar": "string",
- "business_name": "ACME",
- "can_post_listing": true,
- "created": "2019-08-24T14:15:22Z",
- "email": "admin@acme.com",
- "first_name": "John",
- "group_id": 784568,
- "locale": "en",
- "note": "4.5",
- "phone_country_number": "+1",
- "phone_number": "212-398-2600",
- "status": "enabled",
- "review_count": "3",
- "timezone": "America/New_York",
- "username": "BestJohnDoe"
}
Response samples
- 201
{- "success": true,
- "message": "User has been updated"
}
{
"title": "Blue shoes size 6",
"external_id": "INTERNAL_REF_234324",
"sku": "SKU_123",
"price": 123.5,
"quantity": 10
}
A variant refers to a specific version or option of a product that has distinct characteristics such as size, color, material, or any other attribute that differentiates it from the other versions of the same product.
For example, a T-shirt may have multiple variants such as different sizes (small, medium, large), colors (red, blue, green), or styles (short-sleeved, long-sleeved). Each variant may have a different price, SKU (stock-keeping unit), and availability.
By offering multiple variants of a product, e-commerce businesses can cater to the diverse preferences of their customers and enhance the customer shopping experience. Additionally, variants allow for better inventory management and tracking of sales performance for each specific version of a product.
You can add variants to your listing by adding a variants
index to the Listing object. You can then POST or PATCH the Listing object.
Create a new variant
Authorizations:
path Parameters
id required | integer Listing's unique identifier |
Request Body schema: application/jsonrequired
Variant data
title required | string |
price | number |
quantity | number |
sku | string |
weight | number |
Responses
Request samples
- Payload
{- "title": "string",
- "price": 0,
- "quantity": 0,
- "sku": "string",
- "weight": 0
}
Response samples
- 201
{- "variant": {
- "id": 432432,
- "object": "Variant",
- "external_id": "INTERNAL_REF_234324",
- "listing_id": 324353,
- "price": 123.5,
- "price_unit": null,
- "quantity": 10,
- "sort_priority": 10,
- "sku": "BASKT-XYZ-BLN-41",
- "title": "Blue Shoes Size 41",
- "weight": 0.8
}
}
Retrieve variant
Authorizations:
path Parameters
id required | integer Variant's unique identifier |
Responses
Response samples
- 200
{- "variant": {
- "id": 432432,
- "object": "Variant",
- "external_id": "INTERNAL_REF_234324",
- "listing_id": 324353,
- "price": 123.5,
- "price_unit": null,
- "quantity": 10,
- "sort_priority": 10,
- "sku": "BASKT-XYZ-BLN-41",
- "title": "Blue Shoes Size 41",
- "weight": 0.8
}
}