Field | Visibility | Type | Description |
id | public | int | |
listing_type | public | enum(auction, product) | |
name | public | string | |
description | public | string | |
user_id | public | int | The id of the User who owns the listing. |
username | public | string | The username of the User who owns the listing. |
category_id | public | int | |
private_id | private | string | A private id assigned by the User to the listing. |
external_id | private | int | The listing id of the same item on an external site, automatically generated when using one of our sync features. |
external_id_type | private | string | The (name) of the external site that external_id is associated with. |
currency | public | currency | |
quantity | public | int | |
start_price | public | float | Will be set to 0 for listing_type = 'product'. |
buyout_price | public | float | May be set to 0 for listing_type = 'auction'. A non-zero value on an auction would indicate a Buy It Now price, which would be available until the first bid is placed. |
current_price | public | float | The current price of the item in the original listing currency. For auction listings, this price is the starting minimum price (if the listing has no bids) or the current highest bid (if bids have been placed) for the item. |
original_price | public | float | The original price of the item in the original listing currency, if the item is currently on sale. If the item is not on sale (discounted) this field will not be returned. |
enable_make_offer | public | boolean | If buyers can make offers on the Listing. |
make_offer_min | private | float | The hidden minimum offer amount set by the Seller which an offer must meet. |
make_offer_max | private | float | The hidden maximum offer amount set by the Seller which an offer must meet. |
high_bidder_username | public | string | Only applies to listing_type = 'auction'. The username of the User who placed the highest bid. May not be returned if empty. |
bid_count | public | int | Only applies to listing_type = 'auction'. The number of bids placed on an auction. May not be returned if empty. |
start_time | public | time | |
end_time | public | time | |
duration | public | int | |
hpfeat | public | boolean | If the Listing is homepage featured. |
country | public | int | A valid Country ID . |
state | public | int or string | |
postal_code | public | string | A zip or postal code. |
accept_returns | public | boolean | |
returns_policy | public | string | Optional text if the Seller accepts returns, explaining the returns policy. |
postage | public | json_array( Postage ) | The postage costs to ship the item. See Postage for more details. |
item_weight | public | int | May not be returned if empty. |
item_weight_minor | public | int | May not be returned if empty. |
package_depth | public | int | May not be returned if empty. |
package_length | public | int | May not be returned if empty. |
package_width | public | int | May not be returned if empty. |
shipping_details | public | string | |
active | public | boolean | |
closed | public | boolean | |
deleted | private | boolean | |
draft | private | boolean | |
nb_clicks | public | int | Number of views by buyers. |
created_at | public | time | |
updated_at | private | time | |
images | public | array(url) | An array of URLs which list the images associated with the Listing. The first item returned is the main image. |
url | public | string | The URL to the listing on our website. |
Field | Visibility | Type | Description |
item_specifics_01_country | public | string | |
item_specifics_02_catalog_number | public | string | |
item_specifics_03_stamp_type | public | enum | Valid values defined here: HipStamp Fields . |
item_specifics_04_condition | public | enum | Valid values defined here: HipStamp Fields . |
item_specifics_05_stamp_format | public | enum | Valid values defined here: HipStamp Fields . |
item_specifics_06_topic | public | enum | Valid values defined here: HipStamp Fields . |
item_specifics_07_year_of_issue | public | int | |
item_specifics_08_centering | public | enum | Valid values defined here: HipStamp Fields . |
item_specifics_09_has_a_certificate | public | enum | Valid values defined here: HipStamp Fields . |
item_specifics_10_certificate_grade | public | enum | Valid values defined here: HipStamp Fields . |
Field | Visibility | Type | Description |
item_specifics_02_condition | public | enum | Valid values defined here: HipPostcard Fields . |
item_specifics_03_postcard_type | public | enum | Valid values defined here: HipPostcard Fields . |
Field | Visibility | Type | Description |
item_specifics_10_series_name | public | string | |
item_specifics_12_issue_number | public | string | |
item_specifics_02_publisher | public | enum | Valid values defined here: HipComic Fields . |
item_specifics_01_main_character | public | enum | Valid values defined here: HipComic Fields . |
item_specifics_03_genre | public | enum | Valid values defined here: HipComic Fields . |
item_specifics_04_grade | public | enum | Valid values defined here: HipComic Fields . |
item_specifics_05_certification | public | enum | Valid values defined here: HipComic Fields . |
item_specifics_06_signed | public | enum | Valid values defined here: HipComic Fields . |
Association | Visibility | Type | Description |
Bids | private | array( Bid ) |
Name | Required | Type | Notes |
listing_type | N | enum(product, auction) | Default: product |
name | Y | string | Max: 80 characters |
description | Y | string | Max: 8,000 characters, no HTML |
category_id | Y* | int | |
private_id | N | string | If the private_id is set, and if there is an active listing for the User with the same private_id, the existing listing will be updated, instead of a new listing being created. In which case the API will return a response code of 200 as opposed to 201. |
currency | N | currency | |
quantity | N | int | Must be greater than 1 |
start_price | Y* | float | Required when listing_type = auction |
buyout_price | Y* | float | Required when listing_type = product |
enable_make_offer | N | boolean | |
make_offer_min | N | float | |
make_offer_max | N | float | |
start_time | N | time | If set for the future, the listing will be scheduled to start at the indicated time. |
duration | Y* | enum(1, 3, 5, 7, 10) | |
hpfeat | N | boolean | |
country | N | int | Must be a valid Country ID . |
state | N | int or string | |
postal_code | N | string | |
accept_returns | N | boolean | |
returns_policy | N | string | |
postage | N | json_array( Postage ) | |
item_weight | N* | int | Only required if the User is using calculated shipping |
item_weight_minor | N* | int | Only required if the User is using calculated shipping |
package_depth | N | int | |
package_length | N | int | |
package_width | N | int | |
shipping_details | N | string | |
images | Y | array(url) | |
item_specifics_* | N | see notes > | Review the Additional Fields section above, to review which item specific fields are available per marketplace, and what type each is, as well as their accepted values. |
Name | Required | Type | Notes |
id | Y | int | The id of the Listing you want to update. |
name | N | string | Max: 80 characters |
description | N | string | Max: 8,000 characters, no HTML |
category_id | N | int | |
private_id | N | string | If the private_id is set, and if there is an active listing for the User with the same private_id, the existing listing will be updated, instead of a new listing being created. In which case the API will return a response code of 200 as opposed to 201. |
currency | N | currency | |
quantity | N | int | Must be greater than 1 |
start_price | N | float | Required when listing_type = auction |
buyout_price | N | float | Required when listing_type = product |
enable_make_offer | N | boolean | |
make_offer_min | N | float | |
make_offer_max | N | float | |
start_time | N | time | Can only be changed on listings currently scheduled to start in the future |
duration | N | enum(1, 3, 5, 7, 10) | Can only be changed on auction listings currently scheduled to start in the future |
hpfeat | N | boolean | |
country | N | int | Must be a valid Country ID . |
state | N | string | |
postal_code | N | string | |
accept_returns | N | boolean | |
returns_policy | N | string | |
postage | N | json_array( Postage ) | |
item_weight | N | int | |
item_weight_minor | N | int | |
package_depth | N | int | |
package_length | N | int | |
package_width | N | int | |
shipping_details | N | string | |
images | N | array(url) | |
item_specifics_* | N | see notes > | Review the Additional Fields section above, to review which item specific fields are available per marketplace, and what type each is, as well as their accepted values. |
Name | Required | Type | Notes |
id | Y | int | The id of the Listing you want to update. |
Name | Required | Type | Notes |
id | Y | int | The id of the Listing you want to close. |
by_private_id | N | boolean | If set to 1, the id parameter will match the Private ID of the Listing, instead of the Listing ID. |
Name | Required | Type | Notes |
limit | N | int | Default: 25 |
page | N | int | Default: 1 |
sort | N | enum(default, catalog, price_asc, price_desc, started_desc, started_asc, ending_asc, ending_desc, clicks_desc, clicks_asc) | |
keywords | N | string | |
parent_id | N | int | Must be a valid Category ID. Will match all listings in this category, or any of it's sub-categories. |
listing_type | N | enum(product, auction) | |
price_from | N | float | |
price_to | N | float | |
start_time_from | N | time | |
start_time_to | N | time | |
end_time_from | N | time | |
end_time_to | N | time | |
show_only | N | enum(make_offer, one_match_per_seller, one_per_seller_catalog, listed_today, listed_this_week, listed_this_month, on_sale, on_sale_25, on_sale_50) | |
country | N | int | Must be a valid Country ID . |
ships_to | N | int | Must be a valid Country ID . |
Name | Required | Type | Notes |
limit | N | int | Default: 25 |
page | N | int | Default: 1 |
sort | N | enum(default, catalog, price_asc, price_desc, started_desc, started_asc, ending_asc, ending_desc, clicks_desc, clicks_asc) | |
keywords | N | string | |
private_id | N | string | |
parent_id | N | int | Must be a valid Category ID. Will match all listings in this category, or any of it's sub-categories. |
listing_type | N | enum(product, auction) | |
price_from | N | float | |
price_to | N | float | |
start_time_from | N | time | |
start_time_to | N | time | |
end_time_from | N | time | |
end_time_to | N | time | |
show_only | N | enum(make_offer, one_match_per_seller, one_per_seller_catalog, listed_today, listed_this_week, listed_this_month, on_sale, on_sale_25, on_sale_50) | |
country | N | int | Must be a valid Country ID . |
ships_to | N | int | Must be a valid Country ID . |
Name | Required | Type | Notes |
limit | N | int | Default: 25 |
page | N | int | Default: 1 |
sort | N | enum(default, catalog, price_asc, price_desc, started_desc, started_asc, ending_asc, ending_desc, clicks_desc, clicks_asc) | |
show | N | enum(sold, pending, unsold) | |
keywords | N | string | |
private_id | N | string | |
parent_id | N | int | Must be a valid Category ID. Will match all listings in this category, or any of it's sub-categories. |
listing_type | N | enum(product, auction) | |
price_from | N | float | |
price_to | N | float | |
start_time_from | N | time | |
start_time_to | N | time | |
end_time_from | N | time | |
end_time_to | N | time | |
show_only | N | enum(make_offer, one_match_per_seller, one_per_seller_catalog, listed_today, listed_this_week, listed_this_month, on_sale, on_sale_25, on_sale_50) | |
country | N | int | Must be a valid Country ID . |
ships_to | N | int | Must be a valid Country ID . |
Name | Required | Type | Notes |
limit | N | int | Default: 25 |
page | N | int | Default: 1 |
sort | N | enum(default, catalog, price_asc, price_desc, started_desc, started_asc, ending_asc, ending_desc, clicks_desc, clicks_asc) | |
keywords | N | string | |
private_id | N | string | |
parent_id | N | int | Must be a valid Category ID. Will match all listings in this category, or any of it's sub-categories. |
listing_type | N | enum(product, auction) | |
price_from | N | float | |
price_to | N | float | |
start_time_from | N | time | |
start_time_to | N | time | |
end_time_from | N | time | |
end_time_to | N | time | |
show_only | N | enum(make_offer, one_match_per_seller, one_per_seller_catalog, listed_today, listed_this_week, listed_this_month, on_sale, on_sale_25, on_sale_50) | |
country | N | int | Must be a valid Country ID . |
ships_to | N | int | Must be a valid Country ID . |
Name | Required | Type | Notes |
limit | N | int | Default: 25 |
page | N | int | Default: 1 |
sort | N | enum(default, catalog, price_asc, price_desc, started_desc, started_asc, ending_asc, ending_desc, clicks_desc, clicks_asc) | |
keywords | N | string | |
private_id | N | string | |
parent_id | N | int | Must be a valid Category ID. Will match all listings in this category, or any of it's sub-categories. |
listing_type | N | enum(product, auction) | |
price_from | N | float | |
price_to | N | float | |
start_time_from | N | time | |
start_time_to | N | time | |
end_time_from | N | time | |
end_time_to | N | time | |
show_only | N | enum(make_offer, one_match_per_seller, one_per_seller_catalog, listed_today, listed_this_week, listed_this_month, on_sale, on_sale_25, on_sale_50) | |
country | N | int | Must be a valid Country ID . |
ships_to | N | int | Must be a valid Country ID . |