thredUP Item Search API Documentation Search thredUP second-hand fashion in the US. Every item has the id, item number, url, title, brand and brand id, department and category tags, colors, materials, size with size ids, condition with label, price and original retail price (msrp) as numbers with currency, discount percent against the retail price, clearance and final sale flags, availability, favorites, style tags and full size photos. Filters are enforced on every returned item: a price, brand, size, condition, color or department filter holds for each row. A page can hold fewer items than per_page after this check, and pagination.filtered_out says how many rows were dropped. thredUP serves at most 10001 matches per search. Each request costs 1 credit. A search without a match, a failed request and a 404 are not billed.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
This endpoint has no required query parameters.
12 optional filters available.
string
Optional
Search text, e.g. gucci bag. Required unless you send a department.
coffee shops
string
Optional
women, girls or boys. Required unless you send a query. Men is not available on thredUP.
example
string
Optional
Category slug as in thredUP urls, e.g. jeans, dresses or handbags. Best used with a department.
example
string
Optional
thredUP brand ids, comma separated. Take the brand_id of a result row, e.g. 138 for Gucci.
1234567890
string
Optional
thredUP size ids, comma separated. Take them from size.size_ids of a result row, e.g. 798 for women Size 8.
1234567890
string
Optional
excellent, very-good, good or flawed-gems, comma separated.
example
string
Optional
Color names as on result rows, e.g. black or blue, comma separated.
example
number
Optional
Lowest price in USD. Applied to the shown price.
10
number
Optional
Highest price in USD. Applied to the shown price.
10
string
Optional
recommended (default), relevance, newest_first, price_low_high, price_high_low or marked_down_at_desc.
relevance
integer
Optional
Page number, default 1. Page times per_page is at most 10001.
1
integer
Optional
Items per page, 1 to 120, default 40.
10
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
meta
items
success
pagination
filters_applied
Common items fields
id
url
msrp
size
{
"meta": {
"credits": 1,
"billable": true,
"endpoint_family": "search"
},
"items": [
{
"id": 219390118,
"url": "https://www.thredup.com/product/women-gucci-gucci-leather-satchel/1501078587",
"msrp": 326,
"size": {
"label": "One size",
"size_ids": [
902
]
},
"brand": "Gucci",
"price": 299.99,
"state": "listed",
"title": "Gucci Leather Satchel",
"colors": [
"Tan"
],
"gender": "women",
"images": [
"https://cf-assets-thredup.thredup.com/assets/1517570766/xlarge.jpg",
"https://cf-assets-thredup.thredup.com/assets/1517570767/xlarge.jpg"
],
"brand_id": 138,
"category": "handbags",
"currency": "USD",
"clearance": true,
"condition": {
"label": "Very good",
"value": "very-good",
"new_with_tags": false
},
"materials": [
"50% Leather",
"50% Canvas"
],
"final_sale": true,
"style_tags": [
"satchels"
],
"description": "Tan monogram GG canvas handbag with beige leather trim and gold-tone hardware, featuring rounded handles and detachable zip closure",
"item_number": 1501078587,
"availability": "InStock",
"category_tags": [
"handbags"
],
"favorite_count": 27,
"original_price": 326,
"department_tags": [
"handbags",
"women",
"designer"
],
"is_peer_to_peer": false,
"discount_percent": 8
},
{
"id": 230408549,
"url": "https://www.thredup.com/product/women-gucci-gucci-leather-shoulder-bag/1501701094",
"msrp": 1175,
"size": {
"label": "One size",
"size_ids": [
902
]
},
"brand": "Gucci",
"price": 944.99,
"state": "listed",
"title": "Gucci Leather Shoulder Bag",
"colors": [
"Yellow"
],
"gender": "women",
"images": [
"https://cf-assets-thredup.thredup.com/assets/1521578053/xlarge.jpg",
"https://cf-assets-thredup.thredup.com/assets/1521578056/xlarge.jpg"
],
"brand_id": 138,
"category": "handbags",
"currency": "USD",
"clearance": false,
"condition": {
"label": "Excellent",
"value": "excellent",
"new_with_tags": false
},
"materials": [],
"final_sale": true,
"style_tags": [
"shoulder"
],
"description": "Yellow nylon Gucci mini bag with black leather accents and logo, double zip compartments, top handles, and detachable shoulder strap",
"item_number": 1501701094,
"availability": "InStock",
"category_tags": [
"handbags"
],
"favorite_count": 2,
"original_price": 1175,
"department_tags": [
"handbags",
"women",
"designer"
],
"is_peer_to_peer": false,
"discount_percent": 19.6
}
],
"success": true,
"pagination": {
"page": 1,
"total": 1715,
"per_page": 40,
"returned": 2,
"filtered_out": 0,
"has_next_page": true
},
"filters_applied": {
"sort": "recommended",
"query": "gucci bag",
"price_max": 500,
"department": "women"
}
}Errors
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
A query parameter is missing or invalid. This response is not billable.
{
"errors": {
"department": [
"Send a search text or a department."
]
},
"message": "The request validation failed"
}Source Unavailable
thredUP did not give a usable answer after the retries. This response is not billable. Retry later.
{
"meta": {
"billable": false,
"retryable": true,
"endpoint_family": "search"
},
"error": {
"code": "upstream_unavailable",
"message": "thredUP is temporarily unavailable. Please retry."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.