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 to 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

photos array[Photo] required

size Size optional

attributes Attributes optional

Example Request Body
{
  "title": "Cashmere Sweater",
  "description": "High-quality designer piece in excellent condition",
  "mpn": "MPN-DEF104",
  "external_id": "EXT-XYZ209",
  "price": 1599,
  "discount": {
    "max_discount": {
      "percentage": 30
    }
  },
  "msrp": 4995,
  "brand_id": 6863,
  "category_id": 7537,
  "warehouse_id": 1423,
  "quality": "Q3",
  "condition_description": "Elegant and sophisticated style perfect for any occasion",
  "with_tag": true,
  "photos": [
    {
      "url": "https://example.com/resource",
      "subtype": "side"
    }
  ],
  "size": {
    "sizing_id": 8529,
    "scale": "example_value",
    "name": "Michael Brown",
    "type": "WomenSize"
  },
  "attributes": {
    "color": [
      "Green"
    ],
    "material": [
      {
        "value": "Corkshell",
        "percentage": 45
      }
    ],
    "necklace_style": "example_value",
    "bracelet_style": "example_value",
    "ring_style": "example_value",
    "ring_size": "5",
    "general_style": "Classic",
    "skirt_length": "Knee Length",
    "neckline": "High Neck",
    "top_style": "Cropped",
    "sleeve_length": "Short Sleeve",
    "jacket_style": "Bomber",
    "pant_cut": "Boyfriend",
    "waist": "mid/reg rise",
    "pant_style": "Kick Flares",
    "shoes_style": "Wedge",
    "serial_number": "example_value",
    "country_of_origin": "example_value"
  }
}

Responses

Item created, will be listed asynchronously.

Returns a ItemCreateResponse object.

Example Response Body
{
  "item_number": "ITM-90793261"
}

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.