The Item Object
category_id
Item category must be mapped to a valid ThredUp category ID, which can be retrieved using the Get Categories endpoint.
Category Hierarchy
Only leaf nodes (i.e., categories at the third level of the hierarchy) represent actual assignable categories. Parent nodes above them serve only as category groups and cannot be used for item classification.
brand_id
Brand ID of the item has to be found in the response of the Get Brands endpoint by searching for a desired brand name.
warehouse_id
The partner must provide a list of warehouses that will be used for delivery and each of them will receive an ID. The ID should be specified in the listing request which will ThredUp know where the item is, which taxes are applicable, etc.
Warehouse Configuration
Warehouses are created as part of the onboarding process and are not created via the API.
photos
The API accepts URLs to photos, so photos should be uploaded somewhere prior to listing. Photos should be matched with the available subtypes: for example, front subtype should be the frontal photo etc. The more photos are provided in a listing request, the better.
Required Photo
An item must have a photo of front subtype in order to be listed. If this is not provided, the item will not be listed.
Photo URL Validation
The URLs to photos must be valid regardless of the environment. If photos cannot be downloaded, then the item will not be listed.
size
The size field uses a structured format with scale, name, and optional type fields. Valid sizes must match those available for the item's category.
For comprehensive documentation on size field structure, validation rules, sizing systems, and examples, see The Size Object.
external_id
If there's a need to prevent listing of duplicate items, an external id field can be specified and the API will verify that no other item with the provided external id is listed.
price
Price Rounding Rules
There are rounding rules for item prices that are applied when items are listed, which usually means that the actual price of an item on ThredUP will be slightly higher than the price provided by the partner. For example, if an item costs $11.00 the price will be $11.99.
discount
If the partner wants an item to participate in ThredUP sales, a max percentage can be specified for the item and that will mean that the discount cannot be higher than the specified percentage.
Sale Participation
Items with a discount percentage greater than 0 will be included in ThredUP sales. By default items are excluded from any sales.
authentication_type
Indicates whether the item has been authenticated and by whom.
Valid Values:
THIRD_PARTY: Item has been authenticated by an independent third-party authentication service and includes a certificate of authenticitySELLER: Item has been authenticated by the partner/seller, but ThredUp has not independently verified authenticityNONE: Item has not been authenticated
Default Behavior
If authentication_type is not provided in the request, a default value will be applied based on your account configuration. To find out what default authentication type is configured for your account, please contact ThredUp support.
Best Practice
We recommend providing this value when listing an item, especially for luxury items (designer handbags, jewelry, watches, high-end fashion). Customers may return items if they have authenticity concerns, so indicating authentication status upfront helps reduce returns and increase buyer confidence.
attributes
None of the attributes are required, but we highly recommend them to be provided because they impact the discoverability of items.
Measurement Units
All measurements are in inches.