Skip to content

List an Item

POST /api/v1.0/items
Try it out ↗

Creates an Item

Create an item based on payload data. Attributes like brand and category should be fetched from catalog API. Other attributes described as enum in documentation, for example "Color" attribute have defined list of values. Listing happen asynchronously, to verify if item listed check "state" attribute.

Usage Notes

Items are listed asynchronously, so it is normal for the item to remain in processing state for a while.

Request Headers

X-Thredup-Access-Token string required

Authentication token

Request Body

title string required

description string optional

mpn string optional

external_id string optional

Unique item id provided by the dropshipper, which is used for preventing listing duplicate items

price integer required

Price in cents

discount Discount optional

msrp integer required

MSRP in cents

brand_id integer required

category_id integer required

warehouse_id integer required

quality string required

Quality of the item

condition_description string optional

Describe any issues with items here, like "stains" or "minor fading"

with_tag boolean optional

Set 'true' if item has attached tag

authentication_type string optional

Authentication type for the item

photos array[Photo] required

size Size optional

attributes Attributes optional

Example Request Body
{
  "title": "Louis Vuitton x Takashi Murakami Neverfull MM Multicolor White Tote",
  "description": "Authentic Louis Vuitton x Takashi Murakami Neverfull MM in iconic white multicolor monogram canvas. Features colorful LV monogram print with rainbow colors on white background. Interior in excellent condition with minimal signs of use. Vachetta leather handles show light honey patina. Includes original pouch.",
  "mpn": "M40049",
  "external_id": "LUX-LVTM-NF-12345",
  "price": 124999,
  "discount": {
    "max_discount": {
      "percentage": 10
    }
  },
  "msrp": 200000,
  "brand_id": 65673,
  "category_id": 865,
  "warehouse_id": 10053,
  "quality": "Q1",
  "condition_description": "Light patina on handles, minor wear on corners, interior clean",
  "with_tag": false,
  "authentication_type": "THIRD_PARTY",
  "photos": [
    {
      "url": "https://example.com/photos/lv-murakami-neverfull-front.jpg",
      "subtype": "front"
    },
    {
      "url": "https://example.com/photos/lv-murakami-neverfull-side.jpg",
      "subtype": "side"
    },
    {
      "url": "https://example.com/photos/lv-murakami-neverfull-interior.jpg",
      "subtype": "inside"
    }
  ],
  "size": {
    "scale": "Fits All",
    "name": "One Size"
  },
  "attributes": {
    "color": [
      "Multi Color",
      "White"
    ],
    "material": [
      {
        "value": "Coated Canvas",
        "percentage": 85
      },
      {
        "value": "Leather",
        "percentage": 15
      }
    ],
    "pattern": [
      "Graphic"
    ]
  }
}

Responses

Item created, will be listed asynchronously.

Returns a ItemCreateResponse object.

Example Response Body
{
  "item_number": "1234567890"
}

Unauthorized

No response body

This endpoint returns no response body for current status code.

Unprocessable entity. Item has invalid attributes.

No response body

This endpoint returns no response body for current status code.

Too many requests

No response body

This endpoint returns no response body for current status code.

Common Validation Errors

Error Message Cause Solution
size: not allowed for this category The scale/name combination is invalid for this category Verify the size exists in the category's allowed_sizes from the Categories API response
size: cannot be empty for this category Size is required but was omitted Include the size field with valid scale and name values
size.type: cannot be empty for this category The type field is required but was omitted Add the type field with a valid size type identifier

For more details on the size field structure and valid values, see The Size Object.