Retrieve your unsold items

Retrieves a list of the authenticated user's unsold listings. Multiple-quantity auctions count as unsold if there is a least one item remaining (i.e. Quantity > 0). Listings that are in the closing state are not included in the list.

URL:	https://api.trademe.co.nz/v1/MyTradeMe/UnsoldItems/{filter}.{file_format}
HTTP Method:	GET
Requires Authentication?	Yes
Permission Required:	MyTradeMeRead: Read your membership & listing data.
Supported Formats:	XML, JSON
Rate Limited?	Yes

URL parameters

filter

String (required)

A filter on the results.

Last45Days	Returns items unsold in the last 45 days.
Last7Days	Returns items unsold in the last 7 days.
Last24Hours	Returns items unsold in the last 24 hours.
LastHour	Returns items unsold in the last hour.
ItemsIHaveOffered	Returns items with pending offers.
ItemsICanRelist	Returns unsold items that can be relisted.

file_format

Enumeration (required)

The format of the response.

xml	Serialize responses into XML.
json	Serialize responses into JSON.

Query String parameters

deleted

Boolean (optional)

Indicates whether deleted items should be included in the results.

page

Integer (optional)

The page number of the set of results to return, starting from 1. Defaults to 1.

photo_size

Enumeration (optional)

The size of the images to return in the results. Defaults to Thumbnail.

Thumbnail	The thumbnail sized photo (always 85x64, with white borders).
List	The list view sized photo (scaled down to fit 160x120).
Medium	The medium sized photo (scaled down to fit 175x175).
Gallery	The gallery sized photo (scaled down to fit 233x176).
Large	The large sized photo (scaled down to fit 352x264).
FullSize	The full sized photo (scaled down to fit 670x502).
JobSearchCard	The SearchCard photo (scaled down to fit 670x502).

rows

Integer (optional)

The number of results per page; also the maximum number of results to return. Defaults to 50.

Returns

A list of unsold items.

TotalCount

Integer

The total number of results in the collection. Can be larger than the number of returned results.

Page

Integer

The index of the current page of results (starts at 1).

PageSize

Integer

The number of results in the current page.

List

Collection of <UnsoldItem> or null

A list of the results in the current page.

ListingId

Long Integer

The ID of the listing.

Title

String or null

The listing title.

Category

String or null

The listing category.

StartPrice

Number

The start price.

BuyNowPrice

Number

The Buy Now price.

StartDate

DateTime

The date the listing was created.

EndDate

DateTime

The date the listing will end.

ListingLength

String or null

The listing length.

Restrictions

String or null

The restictions associated with the listing.

IsFeatured

Boolean

Is this a featured listing?

HasGallery

Boolean

Is this a gallery listing?

IsBold

Boolean

Is this a bold listing?

IsHighlighted

Boolean

Is this a highlighted listing?

HasHomePageFeature

Boolean

Is this a homepage feature listing?

HasExtraPhotos

Boolean

Is this a listing with extra photos?

HasScheduledEndDate

Boolean

Is this a listing with a scheduled end date?

BidderAndWatchers

Integer

The number of bidders and watcher for this listing.

MaxBidAmount

Number

The current leading bid amount.

AsAt

DateTime

The date and time the response was generated on the server.

CategoryPath

String or null

The category path.

PictureHref

String or null

The URL of the primary photo for the listing (if the listing has a photo). By default you'll get a thumbnail-sized photo, but you can control the size of the photo using the photo_size parameter.

PhotoId

Long Integer

The ID of the primary photo for the listing (if the listing has a photo).

BidCount

Integer

The number of bids on the item.

ViewCount

Integer

The number of times the listing has been viewed.

IsReserveMet

Boolean

Indicates whether the item's reserve has been met.

HasReserve

Boolean

Indicates whether the item has a reserve.

HasBuyNow

Boolean

Indicates whether the item has Buy Now.

Note

String or null

The note on an item.

NoteId

Integer

The note id on an item.

NoteDate

DateTime

The date of the note on an item.

CategoryName

String or null

The display name of the category.

ReserveState

Enumeration

The flag to display on an item.

None	0	There is no reserve on the item (i.e. the reserve price is the same as the starting price).
Met	1	The value of the highest bid has exceeded the reserve price.
NotMet	2	The value of the highest bid has not reached the reserve price.
NotApplicable	3	The listing cannot have a reserve because bidding is not allowed. This may be because it is a classified or because it is a Buy Now Only auction.

Attributes

Collection of <Attribute> or null

The attributes for the item that are intended to be displayed on the UI.

Name	String or null	A name which uniquely identifies the attribute. Required when selling or editing.
DisplayName	String or null	The name of the attribute, in a form suitable for displaying to users. Not required when selling or editing.
Value	String or null	The string value of the attribute. When listing, the valid values for the attribute can be determined using the "Retrieve attributes for a category" API. Use "false" or "true" for boolean attributes. Required when selling or editing.

IsClassified

Boolean

Indicates whether the item is a classified.

RelistedItemId

Long Integer

The ID of the new listing if this listing was relisted.

Subtitle

String or null

The subtitle, if present.

ReservePrice

Number

The reserve price for the auction. This is available in the sold/unsold items APIs and, if you are the seller, the listing details API.

IsBuyNowOnly

Boolean

Indicates whether or not this is a Buy Now Only listing.

Quantity

Integer

The total quantity available of the item. Only applicable for Buy Now Only listings. When retrieving won items this value represents the number sold, not the total quantity. When retrieving sold items, this value is not present (use QuantitySold instead). When retrieving listing details, this value is only present if you are the seller.

RemainingGalleryPlusRelists

Integer or null

The number of times the item can be relisted and get the gallery promotion for free. This value is only present if you are the seller and the listing had the gallery promotion applied due to the gallery plus promotion. Note that for this field, a value of zero is not the same as if the field is missing (a value of zero means gallery plus is in effect whereas if the field is missing it means that you are not the seller or gallery plus is not in effect).

PriceDisplay

String or null

The price, in a format suitable for displaying to the user. Some categories may have special pricing rules, e.g. properties may have "Price by negotiation".

ExternalReferenceId

String or null

The external reference ID, if one exists. Only available to the seller of a listing.

SKU

String or null

SKU or Stock Keeping Unit. Used to uniquely identify an auction's product line.

IsClearance

Boolean

This indicates that the listing is a clearance item. Clearance listings include listings with was/now pricing and general clearance stock.

WasPrice

Number or null

The usual price that a product is sold at, or the price before it was marked down. This is always more than the Buy Now price for Auctions, or more than the asking price for Classifieds.This field will only be populated if IsClearance is true.

PercentageOff

Integer or null

The percentage that a product has been discounted. This has been rounded for display purposes. This field will only be populated if IsClearance is true.

Options

Collection of <Option> or null

The combination of variant options that this variant represents.

(This type has already been defined)

ListingGroupId

Long Integer or null

The identifier of the group of related multi-variant listings. Blank if the listing is not multi-variant

OfferIsActive

Boolean or null

This indicates if the listing has an offer (not null) and whether the offer is active (true) or not active (false). Not active includes expired, withdrawal, sold, declined by all offerees, etc.

IsWithdrawn

Boolean

Indicates whether the listing has been withdrawn.

QuantityUnsold

Integer

The number of items unsold. Only valid for listings with a quantity > 1.

CanMakeOffer

Boolean

If the seller can make a fixed price offer

CanRelist

Boolean

If the seller can relist

Example XML Response (switch to JSON)

<UnsoldItems xmlns="http://api.trademe.co.nz/v1">
  <TotalCount>123</TotalCount>
  <Page>123</Page>
  <PageSize>123</PageSize>
  <List>
    <UnsoldItem>
      <ListingId>123</ListingId>
      <Title>ABC</Title>
      <Category>ABC</Category>
      <StartPrice>123.0</StartPrice>
      <BuyNowPrice>123.0</BuyNowPrice>
      <StartDate>2018-01-01T00:00:00Z</StartDate>
      <EndDate>2018-01-01T00:00:00Z</EndDate>
      <ListingLength>ABC</ListingLength>
      <Restrictions>ABC</Restrictions>
      <IsFeatured>false</IsFeatured>
      <HasGallery>false</HasGallery>
      <IsBold>false</IsBold>
      <IsHighlighted>false</IsHighlighted>
      <HasHomePageFeature>false</HasHomePageFeature>
      <HasExtraPhotos>false</HasExtraPhotos>
      <HasScheduledEndDate>false</HasScheduledEndDate>
      <BidderAndWatchers>123</BidderAndWatchers>
      <MaxBidAmount>123.0</MaxBidAmount>
      <AsAt>2018-01-01T00:00:00Z</AsAt>
      <CategoryPath>ABC</CategoryPath>
      <PictureHref>ABC</PictureHref>
      <PhotoId>123</PhotoId>
      <BidCount>123</BidCount>
      <ViewCount>123</ViewCount>
      <IsReserveMet>false</IsReserveMet>
      <HasReserve>false</HasReserve>
      <HasBuyNow>false</HasBuyNow>
      <Note>ABC</Note>
      <NoteId>123</NoteId>
      <NoteDate>2018-01-01T00:00:00Z</NoteDate>
      <CategoryName>ABC</CategoryName>
      <ReserveState>None</ReserveState>
      <Attributes>
        <Attribute>
          <Name>ABC</Name>
          <DisplayName>ABC</DisplayName>
          <Value>ABC</Value>
        </Attribute>
        <Attribute>
          <Name>ABC</Name>
          <DisplayName>ABC</DisplayName>
          <Value>ABC</Value>
        </Attribute>
      </Attributes>
      <IsClassified>false</IsClassified>
      <RelistedItemId>123</RelistedItemId>
      <Subtitle>ABC</Subtitle>
      <ReservePrice>123.0</ReservePrice>
      <IsBuyNowOnly>false</IsBuyNowOnly>
      <Quantity>123</Quantity>
      <RemainingGalleryPlusRelists>123</RemainingGalleryPlusRelists>
      <PriceDisplay>ABC</PriceDisplay>
      <ExternalReferenceId>ABC</ExternalReferenceId>
      <SKU>ABC</SKU>
      <IsClearance>false</IsClearance>
      <WasPrice>123.0</WasPrice>
      <PercentageOff>123</PercentageOff>
      <Options>
        <Option />
        <Option />
      </Options>
      <ListingGroupId>123</ListingGroupId>
      <OfferIsActive>false</OfferIsActive>
      <IsWithdrawn>false</IsWithdrawn>
      <QuantityUnsold>123</QuantityUnsold>
      <CanMakeOffer>false</CanMakeOffer>
      <CanRelist>false</CanRelist>
    </UnsoldItem>
    <UnsoldItem>
      <ListingId>123</ListingId>
      <Title>ABC</Title>
      <Category>ABC</Category>
      <StartPrice>123.0</StartPrice>
      <BuyNowPrice>123.0</BuyNowPrice>
      <StartDate>2018-01-01T00:00:00Z</StartDate>
      <EndDate>2018-01-01T00:00:00Z</EndDate>
      <ListingLength>ABC</ListingLength>
      <Restrictions>ABC</Restrictions>
      <IsFeatured>false</IsFeatured>
      <HasGallery>false</HasGallery>
      <IsBold>false</IsBold>
      <IsHighlighted>false</IsHighlighted>
      <HasHomePageFeature>false</HasHomePageFeature>
      <HasExtraPhotos>false</HasExtraPhotos>
      <HasScheduledEndDate>false</HasScheduledEndDate>
      <BidderAndWatchers>123</BidderAndWatchers>
      <MaxBidAmount>123.0</MaxBidAmount>
      <AsAt>2018-01-01T00:00:00Z</AsAt>
      <CategoryPath>ABC</CategoryPath>
      <PictureHref>ABC</PictureHref>
      <PhotoId>123</PhotoId>
      <BidCount>123</BidCount>
      <ViewCount>123</ViewCount>
      <IsReserveMet>false</IsReserveMet>
      <HasReserve>false</HasReserve>
      <HasBuyNow>false</HasBuyNow>
      <Note>ABC</Note>
      <NoteId>123</NoteId>
      <NoteDate>2018-01-01T00:00:00Z</NoteDate>
      <CategoryName>ABC</CategoryName>
      <ReserveState>None</ReserveState>
      <Attributes>
        <Attribute>
          <Name>ABC</Name>
          <DisplayName>ABC</DisplayName>
          <Value>ABC</Value>
        </Attribute>
        <Attribute>
          <Name>ABC</Name>
          <DisplayName>ABC</DisplayName>
          <Value>ABC</Value>
        </Attribute>
      </Attributes>
      <IsClassified>false</IsClassified>
      <RelistedItemId>123</RelistedItemId>
      <Subtitle>ABC</Subtitle>
      <ReservePrice>123.0</ReservePrice>
      <IsBuyNowOnly>false</IsBuyNowOnly>
      <Quantity>123</Quantity>
      <RemainingGalleryPlusRelists>123</RemainingGalleryPlusRelists>
      <PriceDisplay>ABC</PriceDisplay>
      <ExternalReferenceId>ABC</ExternalReferenceId>
      <SKU>ABC</SKU>
      <IsClearance>false</IsClearance>
      <WasPrice>123.0</WasPrice>
      <PercentageOff>123</PercentageOff>
      <Options>
        <Option />
        <Option />
      </Options>
      <ListingGroupId>123</ListingGroupId>
      <OfferIsActive>false</OfferIsActive>
      <IsWithdrawn>false</IsWithdrawn>
      <QuantityUnsold>123</QuantityUnsold>
      <CanMakeOffer>false</CanMakeOffer>
      <CanRelist>false</CanRelist>
    </UnsoldItem>
  </List>
</UnsoldItems>

Example JSON Response (switch to XML)

{
  "TotalCount": 123,
  "Page": 123,
  "PageSize": 123,
  "List": [
    {
      "ListingId": 123,
      "Title": "ABC",
      "Category": "ABC",
      "StartPrice": 123.0,
      "BuyNowPrice": 123.0,
      "StartDate": "\/Date(1514764800)\/",
      "EndDate": "\/Date(1514764800)\/",
      "ListingLength": "ABC",
      "Restrictions": "ABC",
      "IsFeatured": false,
      "HasGallery": false,
      "IsBold": false,
      "IsHighlighted": false,
      "HasHomePageFeature": false,
      "HasExtraPhotos": false,
      "HasScheduledEndDate": false,
      "BidderAndWatchers": 123,
      "MaxBidAmount": 123.0,
      "AsAt": "\/Date(1514764800)\/",
      "CategoryPath": "ABC",
      "PictureHref": "ABC",
      "PhotoId": 123,
      "BidCount": 123,
      "ViewCount": 123,
      "IsReserveMet": false,
      "HasReserve": false,
      "HasBuyNow": false,
      "Note": "ABC",
      "NoteId": 123,
      "NoteDate": "\/Date(1514764800)\/",
      "CategoryName": "ABC",
      "ReserveState": 0,
      "Attributes": [
        {
          "Name": "ABC",
          "DisplayName": "ABC",
          "Value": "ABC"
        },
        {
          "Name": "ABC",
          "DisplayName": "ABC",
          "Value": "ABC"
        }
      ],
      "IsClassified": false,
      "RelistedItemId": 123,
      "Subtitle": "ABC",
      "ReservePrice": 123.0,
      "IsBuyNowOnly": false,
      "Quantity": 123,
      "RemainingGalleryPlusRelists": 123,
      "PriceDisplay": "ABC",
      "ExternalReferenceId": "ABC",
      "SKU": "ABC",
      "IsClearance": false,
      "WasPrice": 123.0,
      "PercentageOff": 123,
      "Options": [
        {
        },
        {
        }
      ],
      "ListingGroupId": 123,
      "OfferIsActive": false,
      "IsWithdrawn": false,
      "QuantityUnsold": 123,
      "CanMakeOffer": false,
      "CanRelist": false
    },
    {
      "ListingId": 123,
      "Title": "ABC",
      "Category": "ABC",
      "StartPrice": 123.0,
      "BuyNowPrice": 123.0,
      "StartDate": "\/Date(1514764800)\/",
      "EndDate": "\/Date(1514764800)\/",
      "ListingLength": "ABC",
      "Restrictions": "ABC",
      "IsFeatured": false,
      "HasGallery": false,
      "IsBold": false,
      "IsHighlighted": false,
      "HasHomePageFeature": false,
      "HasExtraPhotos": false,
      "HasScheduledEndDate": false,
      "BidderAndWatchers": 123,
      "MaxBidAmount": 123.0,
      "AsAt": "\/Date(1514764800)\/",
      "CategoryPath": "ABC",
      "PictureHref": "ABC",
      "PhotoId": 123,
      "BidCount": 123,
      "ViewCount": 123,
      "IsReserveMet": false,
      "HasReserve": false,
      "HasBuyNow": false,
      "Note": "ABC",
      "NoteId": 123,
      "NoteDate": "\/Date(1514764800)\/",
      "CategoryName": "ABC",
      "ReserveState": 0,
      "Attributes": [
        {
          "Name": "ABC",
          "DisplayName": "ABC",
          "Value": "ABC"
        },
        {
          "Name": "ABC",
          "DisplayName": "ABC",
          "Value": "ABC"
        }
      ],
      "IsClassified": false,
      "RelistedItemId": 123,
      "Subtitle": "ABC",
      "ReservePrice": 123.0,
      "IsBuyNowOnly": false,
      "Quantity": 123,
      "RemainingGalleryPlusRelists": 123,
      "PriceDisplay": "ABC",
      "ExternalReferenceId": "ABC",
      "SKU": "ABC",
      "IsClearance": false,
      "WasPrice": 123.0,
      "PercentageOff": 123,
      "Options": [
        {
        },
        {
        }
      ],
      "ListingGroupId": 123,
      "OfferIsActive": false,
      "IsWithdrawn": false,
      "QuantityUnsold": 123,
      "CanMakeOffer": false,
      "CanRelist": false
    }
  ]
}