Items

Item Lifecycle

An item transitions through several statuses during its lifecycle in the ThredUp API. The typical lifecycle of an item is as follows:

graph TD
    A[processing] --> B[listed]
    B -->C[**purchased**]
    B -->D[ready_to_delete]
    D -->E[**deleted**]
    A -->F[errored_retryable]
    F -->G[**errored**]
    F -.-> A

Note

The purchased, deleted and errored states are final. Once an item is in one of these states, it cannot be transitioned to another state.

Create the Item

Items are created through the ThredUp API. At this stage, the item payload is validated and the item is saved with a processing status. This status indicates that the item has been accepted and is queued for listing.

Note

A unique item_number is generated for the item and acts as an ID for the item throughout the API.

List the Item

A background process picks up the item and attempts to list it on ThredUp. To determine whether an item has reached the listed status, you need to poll the items endpoint, either by querying a specific item using its item_number, or by retrieving items that have been updated since the last polling timestamp.

Alternatively, instead of polling, you can use a webhook to be notified when an item transitions to the listed status. This allows your system to respond to the status change in real time without the need for repeated API calls.

If the item is successfully listed, its status will transition to listed.

Note

Item listing may fail due to various reasons. While we aim to validate all item fields thoroughly before accepting an item for listing, some issues may still occur during processing.

Certain internal errors are transient and are retried automatically. However, if the failure is caused by invalid or incomplete fields in the item payload (identified at the time of processing), the listing will fail, and the item will be moved to the errored status without further retries.