The Real Real

Addresses

The address model

The address model contains all the information about the vendor's virtual inventory addresses.

Properties

  • Name
    address_id
    Type
    string
    Description

    The address ID. The value needed in order to update an existing active address.

  • Name
    active
    Type
    boolean
    Description

    Whether an address has been deleted and can or cannot be linked to items.

  • Name
    name
    Type
    string
    Description

    Name of the contact in the address.

  • Name
    address1
    Type
    string
    Description

    Address line 1 of the contact in the address.

  • Name
    address2
    Type
    string
    Description

    Address line 2 of the contact in the address.

  • Name
    city
    Type
    string
    Description

    City of the contact in the address.

  • Name
    state_abbr
    Type
    string
    Description

    State abbreviation of the contact in the address.

  • Name
    zipcode
    Type
    string
    Description

    Zip code of the contact in the address. Must be either 5 or 9 digits.

  • Name
    country_iso
    Type
    string
    Description

    Country ISO code of the contact in the address. Must be a valid ISO2 or ISO3 code.

  • Name
    phone
    Type
    string
    Description

    Phone number of the contact in the address. Must be at least 10 digits.

  • Name
    email
    Type
    string
    Description

    Email address of the contact in the address.

GET/v1/vendor/addresses

List all addresses

Lists all addresses for the vendor that can be used for items.

Optional attributes

  • Name
    page_size
    Type
    integer
    Description

    Limit the number of entries returned.

  • Name
    after
    Type
    boolean
    Description

    Cursor for forward pagination.

  • Name
    before
    Type
    boolean
    Description

    Cursor for backward pagination.

Request

GET
/v1/vendor/addresses
curl -G https://vendor.trr-apps.com/v1/vendor/addresses \
-H "Authorization: Bearer {token}" \
-d page_size=10
POST/v1/vendor/addresses

Create an address

This endpoint allows you to add a new virtual inventory address for a vendor.

Required attributes

  • Name
    first_name
    Type
    string
    Description

    First name of the contact in the address.

  • Name
    last_name
    Type
    string
    Description

    Last name of the contact in the address.

  • Name
    address1
    Type
    string
    Description

    Address line 1 of the contact in the address.

  • Name
    address2
    Type
    string
    Description

    Address line 2 of the contact in the address.

  • Name
    city
    Type
    string
    Description

    City of the contact in the address.

  • Name
    state_abbr
    Type
    string
    Description

    State abbreviation of the contact in the address.

  • Name
    zipcode
    Type
    string
    Description

    Zip code of the contact in the address. Must be at least 5 digits.

  • Name
    country_iso
    Type
    string
    Description

    Country ISO code of the contact in the address. Must be a valid ISO2 or ISO3 code.

  • Name
    phone
    Type
    string
    Description

    Phone number of the contact in the address. Must be at least 10 digits.

Request

POST
/v1/vendor/addresses
curl https://vendor.trr-apps.com/v1/vendor/addresses \
-H "Authorization: Bearer {token}" \
-d '{
  "first_name": "Bobby",
  "last_name": "Joe",
  "address1": "1234 Hollywood Blvd",
  "address2": "Apt 42",
  "city": "San Francisco",
  "state_abbr": "CA",
  "zipcode": "90210",
  "country_iso": "US",
  "phone": "string"
}'
PATCH/v1/vendor/addresses/:address_id

Update an address

Updates an existing address for the vendor.

Address must be active to be updated. See Implications of Address Changes for important details about how address updates affect shipments and historical records.

Required attributes

  • Name
    first_name
    Type
    string
    Description

    First name of the contact in the address.

  • Name
    last_name
    Type
    string
    Description

    Last name of the contact in the address.

  • Name
    address1
    Type
    string
    Description

    Address line 1 of the contact in the address.

  • Name
    address2
    Type
    string
    Description

    Address line 2 of the contact in the address.

  • Name
    city
    Type
    string
    Description

    City of the contact in the address.

  • Name
    state_abbr
    Type
    string
    Description

    State abbreviation of the contact in the address.

  • Name
    zipcode
    Type
    string
    Description

    Zip code of the contact in the address. Must be either 5 or 9 digits.

  • Name
    country_iso
    Type
    string
    Description

    Country ISO code of the contact in the address. Must be a valid ISO2 or ISO3 code.

  • Name
    phone
    Type
    string
    Description

    Phone number of the contact in the address.

Request

PATCH
/v1/vendor/addresses/:address_id
curl -X PATCH https://vendor.trr-apps.com/v1/vendor/addresses/:address_id \
-H "Authorization: Bearer {token}" \
-d '{
  "first_name": "Bobby",
  "last_name": "Joe",
  "address1": "1234 Hollywood Blvd",
  "address2": "Apt 42",
  "city": "San Francisco",
  "state_abbr": "CA",
  "zipcode": "90210",
  "country_iso": "US",
  "phone": "1234567890"
}'
DELETE/v1/vendor/addresses/:address_id

Delete an address

Marks an address as inactive or archived, preventing its further use while maintaining historical records.

If there are any live items associated with an address, the address deletion will return errors until the item becomes historical.

Request

DELETE
/v1/vendor/addresses/:address_id
curl -X DELETE https://vendor.trr-apps.com/v1/vendor/addresses/:address_id \
-H "Authorization: Bearer {token}"

Validation Requirements

Only US addresses are supported in V1.

Required Fields

  • Name
    name
    Type
    string
    Description

    Full name of the contact person

  • Name
    address1
    Type
    string
    Description

    Primary street address

  • Name
    city
    Type
    string
    Description

    City name

  • Name
    state
    Type
    string
    Description

    State abbreviation

  • Name
    zipcode
    Type
    string
    Description

    ZIP or postal code

  • Name
    country
    Type
    string
    Description

    Country code in ISO format

Phone Number Format

  • Name
    Format Rules
    Description

    US phone numbers must contain 10 digits and follow one of these formats:

    • (###) ###-####
    • ###-###-####
    • ##########
  • Name
    Valid Examples
    Description
    • (415) 555-1234
    • 415-555-1234
    • 4155551234
  • Name
    Invalid Examples
    Description
    • 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)

Country and State Codes

  • Name
    Country Format
    Description

    Must follow ISO 3166-1 standards:

    • Alpha-2 codes (e.g., "US", "CA", "UK")
    • Alpha-3 codes (e.g., "USA", "CAN", "GBR")
  • Name
    State Format
    Description

    Must use standard abbreviations for the country

  • Name
    US Territories
    Description

    Will have the same value for the city and state_abbr fields

In our current release, the API only supports addresses in the United States and its territories.

ZIP Code Format

  • Name
    Format Rules
    Description
    • Standard 5-digit format: ##### (e.g., 94105)
    • Extended ZIP+4 format: #####-#### (e.g., 94105-0011)
    • No spaces allowed
    • Only numeric digits and hyphen permitted
  • Name
    Valid Examples
    Description
    • 94105
    • 94105-0011
  • Name
    Invalid Examples
    Description
    • 941 05 (contains space)
    • 94105 0011 (contains space)
    • 9410 (too short)
    • 941056 (too long)
    • 94105-00 (incomplete ZIP+4)

Address Changes and Their Impact

  • Name
    Future Shipments
    Description

    Updating an address affects all future shipments using that address

  • Name
    Historical Records
    Description

    Historical records maintain the address information at the time of use

  • Name
    Shipping Labels
    Description

    Address updates do not affect already-created shipping labels

  • Name
    Item Associations
    Description

    To change the association between an address and an item, use the PATCH /v1/items/:item_id endpoint

By "Address Changes", we mean changing any data of an address. To change which address is associated with an item, use the item update endpoint.