Skip to content
Developers

Create several listings

POST
/listings/bulk
curl --request POST \
  --url https://acme.mykreezalid.com/api/v1/listings/bulk \
  --header 'Authorization: Basic <credentials>' \
  --header 'Content-Type: application/json' \
  --data '[ { "admin_status": "waiting", "attributes": { "color": "Blue", "material": "Leather" }, "category_id": 432432, "city": "New York City", "country": "US", "currency": "USD", "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", "is_online": true, "lat": 40.7572114, "lng": -73.9913385, "location": "253 W 42nd St, New York, NY 10036, United States", "min_qty": 1, "medias": [ { "object": "Media", "id": 4242, "alt": "example", "position": 0, "media_type": "image", "src": "https://example.com" } ], "images": [ "https://example.com/photo-front.jpg", "https://example.com/photo-back.jpg" ], "order_type_id": 986545, "order_type_url_token": "example", "original_price": 150, "on_homepage": false, "price": 123.5, "quantity": 43, "quantity_selector": null, "requires_shipping": true, "sku": "SKU_123", "slug": "listing-s-slug", "state": "NY", "status": "draft", "owner": { "external_id": "ABCdef123456", "account_type": "individual", "address_city": "New-York City", "address_country": "US", "address_line1": "253 W 42nd St", "address_line2": null, "address_state": "NY", "address_zipcode": "10036", "attributes": { "profession": "Web developer" }, "avatar": "example", "birthday": "1990-05-17", "business_name": "ACME", "email": "jane@example.com", "first_name": "Jane", "group": { "name": "VIP Customers" }, "group_id": 784568, "lang": "en", "last_name": "Doe", "nationality": "US", "phone_country_code": "+1", "phone_number": "212-398-2600", "identity_status": "not_completed", "timezone": "America/New_York", "username": "janedoe" }, "user_id": 655785, "title": "Blue leather shoes", "variants": [ { "external_id": "INTERNAL_REF_234324", "price": 123.5, "price_unit": null, "quantity": 10, "sort_priority": 10, "sku": "BASKT-XYZ-BLN-41", "title": "Blue Shoes Size 41", "weight": 0.8, "cover_id": 4242 } ], "visibility": "both", "weight": 0.8, "weight_unit": "kg" } ]'

Creates several listings in one call. Send a JSON array of listings; each one follows the rules of Create listing. Required fields: user_id (the vendor), title, description, price (not zero) and the category (category_id, or category with an id or the title of an existing category). Unless you send them, status is published and admin_status approved, or draft and blocked when is_online is 0; visibility defaults to both. When you send status, the listing is still created as published. Nested fields can be sent with dotted keys, for example attributes.color. Each listing is created on its own: one failure does not stop the others. responses holds one result per listing, in the order you sent them. The HTTP status is 200 even when some listings failed.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
Array<object>

A listing (product or service) of your marketplace. Read-only fields are returned in responses; write-only fields are only accepted when you create or update a listing.

object
id

Listing’s unique identifier

integer

Example 

645646
object
string
default: Listing

Example 

Listing
admin_status

Admin validation status of the listing: waiting (awaiting approval), approved (visible if the status is also published), rejected or blocked (hidden from the marketplace). On creation it defaults to approved, or to blocked when is_online is 0.

string
Allowed values: waiting approved rejected blocked

Example 

approved
attributes

Values of the listing attributes, keyed by attribute alias (see List listing attributes). When writing, a select or checkbox attribute accepts option identifiers or option titles (several values as an array or separated by ##); a title that matches no existing option creates that option. Unknown aliases are ignored.

object
key
additional properties
any

Example 

{
  "color": "Blue",
  "material": "Leather"
}
add_ons

Add-ons of the listing, null when there are none

Array<object>
nullable

An extra product or service a buyer can add to a listing, such as gift wrapping or an extended warranty.

object
id

Add-on’s unique identifier

integer

Example 

4242
object
string
default: Addon

Example 

Addon
listing_id

Unique identifier of the listing the add-on belongs to

integer

Example 

324353
title
string

Example 

Extended Warranty
description
string

Example 

Protect your purchases beyond the standard warranty period
price

Price of the add-on, with up to two decimal places

number format: double
nullable

Example 

12.5
address

Address of the listing, grouped

object
location
string
nullable
city
string
nullable
state
string
nullable
country
string
nullable
category

Category of the listing. On write you can also send category with an id, or with a title matching an existing category, instead of category_id.

object
object
string

Example 

Category
id
integer

Example 

4242
parent_id
integer
nullable
title
string

Example 

Shoes
slug
string

Example 

shoes
url
string

Example 

/c/shoes
category_id

Unique identifier of the listing’s category. Required on creation.

integer

Example 

432432
city
string
nullable

Example 

New York City
country
string
nullable

Example 

US
cover

URL of the cover image

string
nullable
currency
string

Example 

USD
date_online

Date the listing went online

string
nullable

Example 

2026-10-01 09:30:00
description

Description of the listing. Required on creation. HTML you send is converted to plain text.

string
nullable

Example 

<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

Your own reference for the listing

string
nullable

Example 

INTERNAL_REF_234324
formatted_price

Price formatted for display, with its currency and price unit; may contain HTML

string
nullable

Example 

$123.50
is_online

Set to 0 on creation to create the listing as a draft, blocked by an admin, unless you send status or admin_status yourself.

boolean

Example 

true
lat
number
nullable

Example 

40.7572114
lng
number
nullable

Example 

-73.9913385
location
string
nullable

Example 

253 W 42nd St, New York, NY 10036, United States
min_qty

Minimum quantity a buyer must order

number
nullable

Example 

1
logistic_category

Logistic category of the listing

object
object
string

Example 

LogisticCategory
id
integer

Example 

4242
title
string
medias

Images attached to the listing, as returned in responses, null when there are none. On create and update this name is also accepted as an alias of images and takes the same value, a list of image URLs; if both are sent, images wins. Prefer images when writing — the alias exists so that posting back the field name you read does not fail silently.

Array<object>
nullable
object
object
string

Example 

Media
id
integer

Example 

4242
alt
string
nullable
position
integer

Example 

0
media_type
string

Example 

image
src
string format: uri
images

Images to attach to the listing, as a JSON array of publicly reachable image URLs; a single URL on its own is accepted too. Each URL is downloaded server-side and re-uploaded to our own storage, so the source only needs to stay reachable for the duration of the request; the stored copy is returned in medias. The order of the array is the display order. On update, sending images replaces the whole set, so any existing image you want to keep must be sent again. Omit the field to leave the current images untouched. medias is accepted as an alias of this field.

Array<string>

Example 

[
  "https://example.com/photo-front.jpg",
  "https://example.com/photo-back.jpg"
]
order_type_id

Unique identifier of the listing’s order type (see List order types). On creation, when it is missing or unknown, the first available order type is used.

integer

Example 

986545
order_type_url_token

URL token of an order type (see List order types), as an alternative to order_type_id

string
order_type

Order type of the listing

object
object
string

Example 

OrderType
id
integer

Example 

4242
title
string

Example 

Sale
transaction_type
string

Example 

selling
enable_cart
boolean
original_price

Price before discount

number
nullable

Example 

150
on_homepage

Whether the listing is shown on the homepage

boolean

Example 

false
price

Price of the listing. Required (and not zero) on creation.

number
nullable

Example 

123.5
price_unit

Title of the price unit, for example per night

string
nullable

Example 

null
price_with_currency
string

Example 

$123.50
quantity

Quantity available for sale

number
nullable

Example 

43
quantity_selector
string
nullable

Example 

null
requires_shipping
boolean

Example 

true
sku
string
nullable

Example 

SKU_123
shipping_methods

Shipping methods selected for the listing

Array<object>
nullable
object
id
integer

Example 

1
carrier_alias
string

Example 

fed_ex
price
number

Example 

4.95
sort_priority
number

Example 

4
step_price
number

Example 

0.95
title
string

Example 

FedEx
slug
string
nullable

Example 

listing-s-slug
state
string
nullable

Example 

NY
status

Public status of the listing: draft, published (visible) or archived (hidden). On creation, a listing is created as published, or as a draft when is_online is 0 and no status is sent.

string
Allowed values: draft published archived

Example 

published
supplier
One of:
User resource

A member of your marketplace, customer or vendor, as the Admin API returns it.

object
id

User’s unique identifier

integer

Example 

545353
object
string

Example 

User
external_id

Your own identifier for this user

string
nullable

Example 

ABCdef123456
account_type
string
nullable
Allowed values: individual company non_profit soletrader

Example 

individual
address_city
string
nullable

Example 

New-York City
address_country

Two-letter country code

string
nullable

Example 

US
address_line1
string
nullable

Example 

253 W 42nd St
address_line2
string
nullable

Example 

null
address_state
string
nullable

Example 

NY
address_zipcode
string
nullable

Example 

10036
attributes

Values of the user’s custom profile fields

object

Example 

{
  "profession": "Web developer"
}
avatar

Absolute URL of the profile image

string
nullable
birthday
string format: date
nullable

Example 

1990-05-17
business_name

Company or organization name

string
nullable

Example 

ACME
can_post_listing

Whether the user’s group may publish listings

boolean
is_onboarding

Whether the user’s group goes through onboarding

boolean
company

Company details. Absent when account_type is individual.

object
object
string

Example 

Company
address_line1
string
nullable
address_line2
string
nullable
address_city
string
nullable
address_country
string
nullable
address_state
string
nullable
address_zipcode
string
nullable
name
string
nullable

Example 

ACME
number

Company registration number

string
nullable
website_url
string
nullable
created_at

Sign-up date, YYYY-MM-DD HH:MM:SS

string

Example 

2024-03-18 09:41:05
email
string

Example 

jane@example.com
first_name
string
nullable

Example 

Jane
group
object
object
string
default: Group
id

Group’s unique identifier

integer

Example 

784568
name
string

Example 

VIP Customers
alias
string

Example 

vip-customers
group_id

Identifier of the user’s group. Deprecated in responses: read group.id.

integer

Example 

784568
group_name

Read group.name.

string
group_alias

Read group.alias.

string
lang

Language code

string
nullable

Example 

en
last_name
string
nullable

Example 

Doe
listing_count

Number of the user’s listings

integer
nullable

Example 

12
listing_count_any_status

Number of the user’s listings, whatever their status

integer

Example 

14
locale

Same value as lang

string
nullable

Example 

en
metafields

The user’s metafields, when they are loaded; null otherwise

Array<object>
nullable

A custom value you attach to a resource, identified by its namespace and title.

object
namespace
required

Group the metafield belongs to

string

Example 

erp
title
required

Name of the metafield, unique within its namespace

string

Example 

warehouse_code
value
required

Value of the metafield. Usually a string; it can be returned as a number or a JSON value depending on how the metafield was defined.

string

Example 

WH-42
nationality

Two-letter country code

string
nullable

Example 

US
average_rating

Average rating from the reviews the user received

number
nullable

Example 

4.5
phone_country_code
string
nullable

Example 

+1
phone_number
string
nullable

Example 

212-398-2600
profile_url

Absolute URL of the user’s public profile

string
nullable

Example 

https://acme.mykreezalid.com/shop/a1b2c3d/jane-doe
public_name

Name shown publicly, following your display settings

string

Example 

Jane Doe
status

Account status

string
Allowed values: enabled disabled unknown
identity_status

Whether the user completed their identity details

string
nullable
Allowed values: not_completed completed
review_count

Number of reviews the user received

integer
nullable

Example 

3
timezone
string
nullable

Example 

America/New_York
username
string
nullable

Example 

janedoe
owner
User resource

A member of your marketplace, customer or vendor, as the Admin API returns it.

object
id

User’s unique identifier

integer

Example 

545353
object
string

Example 

User
external_id

Your own identifier for this user

string
nullable

Example 

ABCdef123456
account_type
string
nullable
Allowed values: individual company non_profit soletrader

Example 

individual
address_city
string
nullable

Example 

New-York City
address_country

Two-letter country code

string
nullable

Example 

US
address_line1
string
nullable

Example 

253 W 42nd St
address_line2
string
nullable

Example 

null
address_state
string
nullable

Example 

NY
address_zipcode
string
nullable

Example 

10036
attributes

Values of the user’s custom profile fields

object

Example 

{
  "profession": "Web developer"
}
avatar

Absolute URL of the profile image

string
nullable
birthday
string format: date
nullable

Example 

1990-05-17
business_name

Company or organization name

string
nullable

Example 

ACME
can_post_listing

Whether the user’s group may publish listings

boolean
is_onboarding

Whether the user’s group goes through onboarding

boolean
company

Company details. Absent when account_type is individual.

object
object
string

Example 

Company
address_line1
string
nullable
address_line2
string
nullable
address_city
string
nullable
address_country
string
nullable
address_state
string
nullable
address_zipcode
string
nullable
name
string
nullable

Example 

ACME
number

Company registration number

string
nullable
website_url
string
nullable
created_at

Sign-up date, YYYY-MM-DD HH:MM:SS

string

Example 

2024-03-18 09:41:05
email
string

Example 

jane@example.com
first_name
string
nullable

Example 

Jane
group
object
object
string
default: Group
id

Group’s unique identifier

integer

Example 

784568
name
string

Example 

VIP Customers
alias
string

Example 

vip-customers
group_id

Identifier of the user’s group. Deprecated in responses: read group.id.

integer

Example 

784568
group_name

Read group.name.

string
group_alias

Read group.alias.

string
lang

Language code

string
nullable

Example 

en
last_name
string
nullable

Example 

Doe
listing_count

Number of the user’s listings

integer
nullable

Example 

12
listing_count_any_status

Number of the user’s listings, whatever their status

integer

Example 

14
locale

Same value as lang

string
nullable

Example 

en
metafields

The user’s metafields, when they are loaded; null otherwise

Array<object>
nullable

A custom value you attach to a resource, identified by its namespace and title.

object
namespace
required

Group the metafield belongs to

string

Example 

erp
title
required

Name of the metafield, unique within its namespace

string

Example 

warehouse_code
value
required

Value of the metafield. Usually a string; it can be returned as a number or a JSON value depending on how the metafield was defined.

string

Example 

WH-42
nationality

Two-letter country code

string
nullable

Example 

US
average_rating

Average rating from the reviews the user received

number
nullable

Example 

4.5
phone_country_code
string
nullable

Example 

+1
phone_number
string
nullable

Example 

212-398-2600
profile_url

Absolute URL of the user’s public profile

string
nullable

Example 

https://acme.mykreezalid.com/shop/a1b2c3d/jane-doe
public_name

Name shown publicly, following your display settings

string

Example 

Jane Doe
status

Account status

string
Allowed values: enabled disabled unknown
identity_status

Whether the user completed their identity details

string
nullable
Allowed values: not_completed completed
review_count

Number of reviews the user received

integer
nullable

Example 

3
timezone
string
nullable

Example 

America/New_York
username
string
nullable

Example 

janedoe
user
One of:
User resource

A member of your marketplace, customer or vendor, as the Admin API returns it.

object
id

User’s unique identifier

integer

Example 

545353
object
string

Example 

User
external_id

Your own identifier for this user

string
nullable

Example 

ABCdef123456
account_type
string
nullable
Allowed values: individual company non_profit soletrader

Example 

individual
address_city
string
nullable

Example 

New-York City
address_country

Two-letter country code

string
nullable

Example 

US
address_line1
string
nullable

Example 

253 W 42nd St
address_line2
string
nullable

Example 

null
address_state
string
nullable

Example 

NY
address_zipcode
string
nullable

Example 

10036
attributes

Values of the user’s custom profile fields

object

Example 

{
  "profession": "Web developer"
}
avatar

Absolute URL of the profile image

string
nullable
birthday
string format: date
nullable

Example 

1990-05-17
business_name

Company or organization name

string
nullable

Example 

ACME
can_post_listing

Whether the user’s group may publish listings

boolean
is_onboarding

Whether the user’s group goes through onboarding

boolean
company

Company details. Absent when account_type is individual.

object
object
string

Example 

Company
address_line1
string
nullable
address_line2
string
nullable
address_city
string
nullable
address_country
string
nullable
address_state
string
nullable
address_zipcode
string
nullable
name
string
nullable

Example 

ACME
number

Company registration number

string
nullable
website_url
string
nullable
created_at

Sign-up date, YYYY-MM-DD HH:MM:SS

string

Example 

2024-03-18 09:41:05
email
string

Example 

jane@example.com
first_name
string
nullable

Example 

Jane
group
object
object
string
default: Group
id

Group’s unique identifier

integer

Example 

784568
name
string

Example 

VIP Customers
alias
string

Example 

vip-customers
group_id

Identifier of the user’s group. Deprecated in responses: read group.id.

integer

Example 

784568
group_name

Read group.name.

string
group_alias

Read group.alias.

string
lang

Language code

string
nullable

Example 

en
last_name
string
nullable

Example 

Doe
listing_count

Number of the user’s listings

integer
nullable

Example 

12
listing_count_any_status

Number of the user’s listings, whatever their status

integer

Example 

14
locale

Same value as lang

string
nullable

Example 

en
metafields

The user’s metafields, when they are loaded; null otherwise

Array<object>
nullable

A custom value you attach to a resource, identified by its namespace and title.

object
namespace
required

Group the metafield belongs to

string

Example 

erp
title
required

Name of the metafield, unique within its namespace

string

Example 

warehouse_code
value
required

Value of the metafield. Usually a string; it can be returned as a number or a JSON value depending on how the metafield was defined.

string

Example 

WH-42
nationality

Two-letter country code

string
nullable

Example 

US
average_rating

Average rating from the reviews the user received

number
nullable

Example 

4.5
phone_country_code
string
nullable

Example 

+1
phone_number
string
nullable

Example 

212-398-2600
profile_url

Absolute URL of the user’s public profile

string
nullable

Example 

https://acme.mykreezalid.com/shop/a1b2c3d/jane-doe
public_name

Name shown publicly, following your display settings

string

Example 

Jane Doe
status

Account status

string
Allowed values: enabled disabled unknown
identity_status

Whether the user completed their identity details

string
nullable
Allowed values: not_completed completed
review_count

Number of reviews the user received

integer
nullable

Example 

3
timezone
string
nullable

Example 

America/New_York
username
string
nullable

Example 

janedoe
user_id

Unique identifier of the vendor (user) who owns the listing. Required on creation.

integer

Example 

655785
title

Title of the listing. Required on creation.

string

Example 

Blue leather shoes
url

Full URL of the listing page on your marketplace

string
variants

Variants of the listing, null when there are none. On update, send the full list: each variant is matched to an existing one by external_id, then by sku; a variant with no match is created, and every existing variant missing from the list is deleted.

Array<object>
nullable

A version of a listing that differs by size, color or any other characteristic, with its own price, SKU and stock.

object
id

Variant’s unique identifier

integer

Example 

432432
object
string
default: Variant

Example 

Variant
external_id

Your own reference for the variant

string
nullable

Example 

INTERNAL_REF_234324
listing_id

Unique identifier of the listing the variant belongs to

integer

Example 

324353
price
number
nullable

Example 

123.5
price_unit
integer
nullable

Example 

null
quantity

The quantity of the variant that is available for sale

number
nullable

Example 

10
sort_priority

Sorts the variants with the lowest number first. Negative numbers are allowed.

number
nullable

Example 

10
sku
string
nullable

Example 

BASKT-XYZ-BLN-41
title
required
string

Example 

Blue Shoes Size 41
weight
number

Example 

0.8
cover_id

Unique identifier of the listing image used for this variant

integer
nullable

Example 

4242
visibility

Where the listing is displayed: both (catalog and search), catalog (only the catalog), search (only search results) or none (not visible). Defaults to both on creation.

string
Allowed values: both catalog search none

Example 

both
weight
number
nullable

Example 

0.8
weight_unit
string
nullable

Example 

kg
metafields

Metafields of the listing, grouped by namespace then by title

object
key
additional properties
any

Example 

{
  "erp": {
    "warehouse_code": "WH-42"
  }
}
next_date

Date of the next availability, for listings that have one

string
nullable
settings

Settings the listing inherits from its order type, such as whether payment, shipping or stock are enabled

object
key
additional properties
any

Responses

Section titled “Responses”

200

Section titled “200”

One result per listing sent

Media typeapplication/json
object
responses
Array<object>
object
id

Identifier of the new listing, null on failure

integer
nullable
success
boolean
message

Listing created, or the reason of the failure

string

Example 

{
  "responses": [
    {
      "id": 4242,
      "success": true,
      "message": "Listing created"
    }
  ]
}

403

Section titled “403”

Missing or wrong API credentials