Create a listing

POST

/listings

curl --request POST \
  --url https://acme.mykreezalid.com/front_api/v1/listings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "Blue city bike", "description": "<p>A light city bike.</p>", "category_id": 31, "order_type_id": 20, "order_type_url_token": "example", "price": 120, "sku": "SKU-4242", "quantity": 12, "external_id": "REF-4242", "location": "10 Main Street, Springfield", "city": "Springfield", "state": "IL", "country": "US", "lat": 39.7817, "lng": -89.6501, "weight": 12.5, "visibility": "both", "status": "draft", "attributes": { "color": "Blue", "size": [ "S", "M" ] }, "images": [ "https://example.com/bike-front.jpg" ] }'

• Your marketplace's address. A marketplace with a custom domain must be called on that domain instead (https://developers.kreezalid.com/getting-started/base-urls/).

Creates a listing owned by the signed-in member. Any user_id you send is ignored. The listing gets the order type you name with order_type_id or order_type_url_token, or else the marketplace’s first available one. Its currency and whether it requires shipping come from that order type. Unless you send status, it is published; its moderation status is waiting when the order type requires approval and approved otherwise. The response always has status 200: check success. Validation errors are not detailed, only summed up in message.

Authorizations

• bearerAuth

Request Body^required

The listing. Other listing fields are stored as sent.

Media typeapplication/json

object

title

required

string

Example

Blue city bike

description

Description. HTML is converted to plain text.

string

Example

<p>A light city bike.</p>

category_id

integer

Example

31

order_type_id

Order type of the listing.

integer

Example

20

order_type_url_token

URL key of the order type, used when order_type_id is not sent.

string

price

Required when the order type has prices enabled.

number

Example

120

sku

Required when the order type has SKUs enabled.

string

Example

SKU-4242

quantity

Stock.

integer

Example

12

external_id

Your own reference.

string

Example

REF-4242

location

string

Example

10 Main Street, Springfield

city

string

Example

Springfield

state

string

Example

IL

country

string

Example

US

lat

number

Example

39.7817

lng

number

Example

-89.6501

weight

number

Example

12.5

visibility

Defaults to both.

string

Allowed values: both catalog search none

status

Defaults to published.

string

Allowed values: draft published archived

attributes

Attribute values keyed by attribute alias (see GET /listings/attributes). Unknown aliases are dropped. For select and checkbox attributes, send option titles, as an array or as one string separated by ##; titles that do not exist yet are added to the attribute’s options.

object

key

additional properties

any

Example

{
  "color": "Blue",
  "size": [
    "S",
    "M"
  ]
}

images

Public image URLs. Each image is downloaded and stored by the marketplace; the order of the array is the display order. Images that cannot be fetched are skipped.

Array<string>

Example

[
  "https://example.com/bike-front.jpg"
]

Responses

200

Outcome of the creation. success is false and id is null when the title is missing (Title is missing), when the listing is invalid (Error. Listing could not be created) or when no order type is defined (Order type is not defined).

Media typeapplication/json

object

id

ID of the new listing.

integer

nullable

message

string

success

boolean

Example

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

403

No valid access token was sent.

Media typeapplication/json

Error body returned by the Front API when it refuses a request.

object

code

HTTP status code, repeated in the body.

integer

status

string

message

Human-readable reason.

string

Example

{
  "code": 403,
  "status": "error",
  "message": "Token not found in request"
}