Special Considerations

Upsert Behavior

When to use PATCH vs. POST

• Use POST to create new resources (consignments, items, addresses)
• Use PATCH to update existing resources partially
• Never use PUT for partial updates

Handling Item Attribute Updates

• For items in the "pending" or "draft" state, all attributes can be updated
• For items in the "approved" state, only the address_id and quantity (decrease only) can be updated
• Note: When updating approved products (including quantity decreases), you will not receive webhook notifications for these updates
• For items in the "rejected" state, attributes can be updated with a PATCH request to update the item. After any PATCH request, our system will move the item back to "pending". The vendor_sku value must remain the same.

Important Edge Cases for Item Updates

Pricing Updates

• Pricing can only be updated before approval: Item pricing (msrp and price) can only be updated when the item is in "pending" or "draft" state. Once an item is approved, pricing updates will be ignored.

Quantity Updates from Zero

• Zero to positive quantity requires new item: If you need to update an item's quantity from zero to a positive value, you must create a new item with a new vendor_sku instead of updating the existing item. This is because items with zero quantity are considered inactive in the system. The original item with zero quantity should be left as-is; it will remain in the system as an inactive record and does not need to be deleted or archived.

Maintaining Item Integrity During Updates

• Always include all the fields (including those that you want to update) in the request body
• Use the appropriate content-type (application/json)
• Handle response codes properly (200 for successful updates, 4xx for errors)

Address Management

Address Types and Usage

The RealReal supports associating an address for each item. Addresses are linked to items during item creation by specifying the address_id in the item creation request.

Address Validation Requirements

Required Fields

• name
• address1
• city
• state
• zipcode
• country

Phone Number

Must be in a valid format (see format requirements below)

Email Address

Must be valid

Country Codes

Must follow ISO 3166-1 alpha-2 standards (e.g., "US", "CA", "UK"), or ISO 3166-1 alpha-3 codes (e.g., "USA", "CAN", "GBR"). Until we have international support, we accept the United States and its territories.

State/Province

Must follow standard abbreviations for the country

US Territories

Will have the same value for the city and state_abbr fields

Zip/Postal Code Format Requirements

US Format (we are only supporting US addresses in v1)

• Standard 5-digit format: ##### (e.g., 94105)
• Extended ZIP+4 format: #####-#### (e.g., 94105-0011)
• No spaces accepted
• Only numeric digits and hyphen allowed

Valid Examples

• 94105
• 94105-0011

Invalid Examples

• 941 05 (contains space)
• 94105 0011 (contains space)
• 9410 (too short)
• 941056 (too long)
• 94105-00 (incomplete ZIP+4)

Phone Number Format Requirements

Format Rules

• US phone numbers must contain 10 digits
• Acceptable formats:
  • (###) ###-####
  • ###-###-####
  • ##########

Valid Examples

• (415) 555-1234
• 415-555-1234
• 4155551234

Invalid Examples

• 555-1234 (missing area code)
• 415 555 1234 (spaces in numeric portion)
• +1 (415) 555-1234 (space after country code)
• (415)-555-1234 (incorrect punctuation)

International Address Support

Implications of Address Changes

• Updating an address affects all future shipments using that address
• Historical records maintain the address information at the time of use
• Address updates do not affect shipping labels that have already been generated

Considerations When Deleting Addresses

• Addresses are soft-deleted (marked as inactive) rather than permanently removed
• Deleted addresses cannot be used for new items
• Items already associated with a deleted address maintain the relationship
• Address deletion does not affect historical shipment records
• If an address is in use by active inventory, the system will prevent deletion
  • Active inventory refers to live, in stock items only

Quantity Management

Inventory Synchronization Guidelines

• Update quantities promptly to reflect current inventory levels
• Use the PATCH endpoint to update quantities for specific items
• For approved products, only quantity decreases are allowed (no increases or restocking)
• You will receive updates via webhook notifications for quantity changes due to purchases
• Vendor-initiated quantity decreases for approved products do not trigger webhook notifications
• Implement inventory management systems to prevent overselling

Handling Inventory Changes and Stock Updates

• When an item is sold, The RealReal will automatically decrease the available quantity
• When an order is canceled, quantity is NOT automatically incremented
• Vendors must use the update endpoint to adjust quantities after cancellations
• Set quantity to 0 via PATCH to indicate an item is out of stock (only for approved items that can be decreased)

Cancellations and Returns

Vendor-Initiated Cancellation Process

1. Vendor submits a cancellation request via POST /v1/cancellations
2. The RealReal processes the cancellation request
3. If the item has already been shipped to the warehouse, a Return to Vendor (RTV) is created
4. Vendor receives a notification with the cancellation status and RTV tracking number if applicable

Customer-Initiated Returns Handling

1. Customer initiates a return through The RealReal's system
2. Return Merchandise Authorization (RMA) is created
3. Item is returned to The RealReal warehouse
4. RMA is reviewed and processed
5. If approved, an RTV (Return to Vendor) is created
6. Vendor receives a notification with RTV details

Return to Vendor (RTV) Process

1. The RealReal creates an RTV shipping label using the item's associated address
2. Item is packed and shipped back to the vendor
3. Vendor receives a notification with tracking information
4. Vendor tracks and receives the returned item
5. Inventory is updated by the vendor