Items

The item model

The item model contains all the information about a vendor's approved items.

Properties

Name
id
Type
integer
Description
The RealReal Variant ID for the item. Not used for API requests but required for internal functions.
Name
item_id
Type
integer
Description
The RealReal vi-agent ID. Used for API requests.
Name
address_id
Type
integer
Description
Address ID
Name
description
Type
string
Description
Detailed description of the item.
Name
updated_at
Type
string
Description
ISO 8601 formatted timestamp of when the item was last updated.
Name
designer
Type
string
Description
Name of the item's designer/brand. See Valid Designers for all available options.
Name
price
Type
integer
Description
Price of the item in cents.
Name
taxon
Type
string
Description
Category path of the item (e.g., "women/handbags/backpacks"). See Valid Taxon Permalinks for all available options.
Name
consignment_id
Type
string
Description
Associated consignment ID for the item.
Name
created_at
Type
string
Description
ISO 8601 formatted timestamp of when the item was created.
Name
condition
Type
string
Description
Current condition of the item. See Valid Conditions for all available options.
Name
vendor_sku
Type
string
Description
Vendor's SKU identifier for the item. This is different than The RealReal SKU.
Name
quantity
Type
integer
Description
The quantity of this item.

GET/v1/items

List all items

Retrieves a list of items belonging to your user. If no validation_status parameter is provided, only non-approved items will be returned.

By default, this endpoint returns only non-approved items. Use the optional validation_status parameter to filter by a specific status (case-insensitive). See the statuses in the Glossary.

Use the optional vendor_sku parameter to return only items with that vendor SKU. Matching is case-insensitive. If no matching products are found, the response will contain an empty products array.

Optional attributes

Name
validation_status
Type
string
Description
Filter items by validation status (case-insensitive). Valid values: reconciliation, pending, approved, rejected, deleted.
Name
vendor_sku
Type
string
Description
Filter items by vendor SKU. Case-insensitive.
Name
page_size
Type
integer
Description
Limit the number of items returned.
Name
after
Type
boolean
Description
Cursor for forward pagination.
Name
before
Type
boolean
Description
Cursor for backward pagination.

Request

GET

/v1/items

curl -G https://vendor.trr-apps.com/v1/items \
  -H "Authorization: Bearer {token}" \
  -d page_size=10 \
  -d vendor_sku=ABC1234 \
  -d validation_status=pending

200 Response

{
  "products": [
    {
      "id": 1234,
      "description": "description string",
      "updated_at": "2025-07-16T18:29:08Z",
      "designer": "Michael Kors",
      "price": 26123,
      "taxon": "women/handbags/backpacks",
      "consignment_id": 2345,
      "created_at": "2025-07-16T18:29:08Z",
      "condition": "Light wear",
      "vendor_sku": "SKU12345",
      "item_id": 6789
    },
  ],
  "page_info": {
    "start_cursor": "string",
    "end_cursor": "string",
    "has_previous_page": false,
    "has_next_page": true
  }
}

GET/v1/items/non_approved

List all non-approved items

Retrieves a list of items belonging to your user that are not approved internally. This includes items with statuses such as reconciliation, pending, rejected, or deleted.

This endpoint returns items that are not currently live or slated to be launched. Use this to review or manage items that are not yet approved for sale.

Optional attributes

Name
status
Type
string
Description
Filter items by validation_status. Valid values: reconciliation, pending, approved, rejected, deleted.
Name
vendor_sku
Type
string
Description
Filter items by vendor SKU. Case-insensitive.
Name
page_size
Type
integer
Description
Limit the number of items returned.
Name
after
Type
string
Description
Cursor for forward pagination.
Name
before
Type
string
Description
Cursor for backward pagination.

Request

GET

/v1/items/non_approved

curl -G https://vendor.trr-apps.com/v1/items/non_approved \
-H "Authorization: Bearer {token}" \
-d page_size=20 \
-d status=pending \
-d vendor_sku=ABC1234

200 Response

{
  "page_info": {
    "has_next_page": false,
    "has_previous_page": true,
    "start_cursor": "...",
    "end_cursor": "..."
  },
  "products": [
    {
      "description": "another description string",
      "updated_at": "2024-10-28T18:16:02.941659Z",
      "quantity": 0,
      "designer": "Rolex",
      "price": {
        "currency_code": "USD",
        "price": "5895.00"
      },
      "taxon": "watches/bracelet",
      "consignment_id": "11626625",
      "created_at": "2024-10-28T18:16:02.941659Z",
      "condition": "Good",
      "vendor_sku": "29883",
      "item_status": "reconciliation",
      "item_id": 5136
    }
  ]
}

POST/v1/consignments/:consignment_id/items

Create an item

Creates new items associated with a consignment.

Required attributes

Name
vendor_sku
Type
string
Description
Your unique identifier for the item.
Name
upc
Type
string
Description
Universal Product Code for the item.
Only required for watches.
Name
taxon_permalink
Type
string
Description
Category path of the item (e.g., "watches/strap", "women/handbags/clutches"). See Valid Taxon Permalinks for all available options.
Name
condition
Type
string
Description
Condition of the item. See Valid Conditions for all available options.
Name
with_tags
Type
boolean
Description
Indicates if the item includes original tags.
Name
designer
Type
string
Description
Brand name of the item. See Valid Designers for all available options.
Name
image
Type
object
Description
Object containing URLs for front and back images:
- front: URL string
- back: URL string
Name
quantity
Type
integer
Description
Number of items being consigned.
Name
msrp
Type
integer
Description
Manufacturer's Suggested Retail Price in cents.
Name
price
Type
integer
Description
Selling price in cents.
Name
gender
Type
array
Description
Array of strings indicating target gender(s) ("Men", "Women").
Name
taxon_specific_attributes
Type
object
Description
Category-specific attributes that vary based on the item type. See Taxon Specific Attributes for the complete list of valid values.

Optional attributes

Name
address_id
Type
string
Description
Associated address identifier.
Name
designer_specific_attributes
Type
object
Description
Designer-specific attributes. See Designer Specific Attributes for available options.

Ensure that you have turned on webhook notifications

Once the item is successfully created, your Webhook URL would receive the request which contains the item_id . You would need to use the item_id for other API requests, e.g., PATCH /v1/items/{item_id}

Request

POST

/v1/consignments/:consignment_id/items

curl https://vendor.trr-apps.com/v1/consignments/:consignment_id/items \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "vendor_sku": "watches-example",
      "upc": "99887766",
      "address_id": "",
      "taxon_permalink": "watches/strap",
      "condition": "Good",
      "with_tags": true,
      "designer": "Breitling",
      "image": {
        "front": "https://example.com/RLX26832_1_enlarged.jpg",
        "back": "https://example.com/RLX26832_1_enlarged.jpg"
      },
      "quantity": 15,
      "msrp": 22500,
      "price": 12250,
      "gender": ["Men"],
      "taxon_specific_attributes": {
        "condition-description": "freeform string",
        "size": "Large",
        "color": "Blue",
        "material": ["Cotton", "Polyester"],
        "hardware": "Antiqued Gold-Tone",
        "pattern": "Tweed Pattern",
        "handbags-lining": "Canvas Lining", // optional
        "handbags-closure": "Zip Closure at Front", // optional
        "handbags-type": "Backpack",
        "height": "0.25\"",
        "width": "0.25\"",
        "depth": "0.25\"",
        "image-base": "https://example.com/image.jpg",
        "image-interior": "https://example.com/image.jpg",
        "primary-material": "Alligator"
      },
    },
    {
      "vendor_sku": "handbag-example",
      "address_id": "",
      "taxon_permalink": "women/handbags/clutches",
      "condition": "Pristine",
      "designer": "<designer_name>",
      "image": {
        "front": "http://example.com/front.jpg",
        "back": "http://example.com/back.jpg"
      },
      "quantity": 10,
      "msrp": 1000,
      "price": 900,
      "gender": ["Men", "Women"],
      "with_tags": true,
      "taxon_specific_attributes": {},
      "designer_specific_attributes": {}
    }
  ]
}'

200 Response

{}

207 Response - At least 1 of the given items has invalid attributes

{
  "error": [
    {
      "message": "condition is invalid",
      "vendor_sku": null
    }
  ]
}

413 Response - Too many items in payload

{
  "error": "Too many items. Maximum is 500."
}

PATCH/v1/items/:id

Update an item

Updates an existing item. All fields are required, but only the fields you change will be updated.

If item is in the "approved" state, only address_id and quantity (decrease only) can be updated, and the other attribute updates are ignored. For details, please see the explanations in Upsert Behavior.

Resubmitting to update the address_id requires the SAME vendor_sku to be used.

Unapproved items require ALL of the same fields as when creating an item

Pricing updates are only allowed before the item is approved. Quantity can be decreased for approved items, but no webhook notifications will be sent for these updates.

Optional attributes

Name
vendor_sku
Type
string
Description
Your unique identifier for the item.
Name
upc
Type
string
Description
Universal Product Code for the item.
Name
address_id
Type
string
Description
Associated address identifier.
Name
taxon_permalink
Type
string
Description
Category path of the item. See Valid Taxon Permalinks for all available options.
Name
condition
Type
string
Description
Condition of the item. See Valid Conditions for all available options.
Name
with_tags
Type
boolean
Description
Indicates if the item includes original tags.
Name
designer
Type
string
Description
Brand name of the item. See Valid Designers for all available options.
Name
image
Type
object
Description
Object containing URLs for front and back images.
Name
quantity
Type
integer
Description
Number of items being consigned.
Name
msrp
Type
integer
Description
Manufacturer's Suggested Retail Price in cents.
Name
price
Type
integer
Description
Selling price in cents.
Name
gender
Type
array
Description
Array of strings indicating target gender(s).
Name
taxon_specific_attributes
Type
object
Description
Category-specific attributes.

Request

PATCH

/v1/items/:id

curl -X PATCH https://vendor.trr-apps.com/v1/items/{id} \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_sku": "Updated-watch-example",
    "upc": "99887766",
    "address_id": "<address_id>",
    "taxon_permalink": "watches/strap",
    "condition": "Good",
    "with_tags": true,
    "designer": "Breitling",
    "image": {
      "front": "https://example.com/RLX26832_1_enlarged.jpg",
      "back": "https://example.com/RLX26832_1_enlarged.jpg"
    },
    "quantity": 15,
    "msrp": 22500,
    "price": 12250,
    "gender": ["Men"],
    "taxon_specific_attributes": {}
  }'

200 Response

{
  "id": "12345",
  "status": "updated"
}

400 Response

{
  "error": "with_tags is invalid"
}

404 Response

{
  "error": "Item not found"
}