Listing

Listing

Listing

Overview

Listings on Hip eCommerce are items for sale. Each Listing is associated with a User, and with a Store (Users own Stores). Hip eCommerce Listings have a creation date, and are either auctions which last 1 to 10 days (selected by the User), or products which last until they are sold out (or are closed by the User). Listings have a price and a quantity, and when they're sold out, the User must relist them before they can be sold again.

Searching Listings

By default, the method findAllListingsActive returns all active Listings on Hip eCommerce, paginated by best match. Use the optional parameters (such as keyword, price_from, etc.) to narrow these results. The sort parameter can be used to change the order of returned results.

To search within a shop, use findAllStoreListingsActive.

Creating Listings and Bill Charges

Note that certain types of actions, such as creating a new auction Listing, will incur fees as noted on our Site Fees page.

Fields

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
A valid Category ID (see HipStamp IDs , HipPostcard IDs  or HipComic IDs ).
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
A valid State ID or string (see State ID documentation).
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.

Additional Fields - HipStamp

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 

Additional Fields - HipPostcard

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 .

Additional Fields - HipComic

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 .
Note: Additional Fields may not be returned if empty.

Associations

Association
Visibility
Type
Description
Bids
private
array( Bid )

Methods

createListing

Method Name: createListing
Synopsis: Creates a new Listing.
HTTP Method: POST
URI: /listings
Parameters:
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
Must be a valid (leaf) Category ID (see HipStamp IDs , HipPostcard IDs  or HipComic IDs ).
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
Must be a valid  State ID or string (see State ID documentation).
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.
Note: If omitted: currency, enable_make_offer, country, state, postal_code, accept_returns, returns_policy and shipping_details will default to the settings the User has selected in Members Area > Selling > Seller Tools > Default Listing Settings
Note: The return request for getListing will include the new Listing in the results. You should record the id of the newly created Listing, if you want to update or close the Listing in the future, as you will need the Listing id.

updateListing

Method Name: updateListing
Synopsis: Updates an existing Listing.
HTTP Method: PUT
URI: /listings/:id
Parameters:
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
Must be a valid (leaf) Category ID (see HipStamp IDs , HipPostcard IDs  or HipComic IDs ).
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
Must be a valid  State ID or string (see State ID documentation).
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.

getListing

Method Name: getListing
Synopsis: Retrieves a Listing by id.
HTTP Method: GET
URI: /listings/:id
Parameters:
Name
Required
Type
Notes
id
Y
int
The id of the Listing you want to update.

deleteListing

Method Name: deleteListing
Synopsis: Closes a Listing by id.
HTTP Method: DELETE
URI: /listings/:id
Parameters:
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.
Note: This call will close the Listing, it will not actually delete the listing.

findAllListingsActive

Method Name: findAllListingsActive
Synopsis: Finds active Listings.
HTTP Method: GET
URI: /listings
Parameters:
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 .

findAllStoresListingsActive

Method Name: findAllStoresListingsActive
Synopsis: Finds active Listings associated with a Store, using the Store Owner's username as the username key in the URI.
HTTP Method: GET
URI: /stores/:username /listings/active
Parameters:
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 .

findAllStoresListingsClosed

Method Name: findAllStoresListingsClosed
Synopsis: Finds closed Listings associated with a Store, using the Store Owner's username as the username key in the URI.
HTTP Method: GET
URI: /stores/:username /listings/closed
Parameters:
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 .

findAllStoresListingsScheduled

Method Name: findAllStoresListingsScheduled
Synopsis: Finds scheduled Listings associated with a Store, using the Store Owner's username as the username key in the URI.
HTTP Method: GET
URI: /stores/:username /listings/scheduled
Parameters:
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 .

findAllStoresListingsDrafts

Method Name: findAllStoresListingsDrafts
Synopsis: Finds draft Listings associated with a Store, using the Store Owner's username as the username key in the URI.
HTTP Method: GET
URI: /stores/:username /listings/drafts
Parameters:
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 .


Examples

getListing

Request:
Response:
{
      "count": 1,
      "type": "listing",
      "results": [
            {
                  "id": "16669938",
                  "listing_type": "auction",
                  "name": "Antigua SG98/109 1937 KGVI Set Including ALL Shades Very Fine Used",
                  "description": "Including ALL Shades Very Fine Used \n\n A Beautiful Set",
                  "user_id": "77510",
                  "username": "Bloxhamstamps",
                  "category_id": "130",
                  "currency": "GBP",
                  "quantity": "1",
                  "start_price": "0.01",
                  "enable_make_offer": "0",
                  "start_time": "2017-11-09 13:11:06",
                  "end_time": "2017-11-16 19:52:34",
                  "duration": "7",
                  "hpfeat": "0",
                  "country": "2083",
                  "state": "2106",
                  "postal_code": "ABC 123",
                  "accept_returns": 1,
                  "returns_policy": " - Returns Accepted within 30 days (Buyer pays Shipping Cost)",
                  "postage": [
                        {
                              "price": 1,
                              "price_addl": 1,
                              "method": "UK_Royal Mail First Class Standard",
                              "location_groups": [
                                    "Domestic"
                              ],
                              "location_countries": [
                                    "2083"
                              ]
                        },
                        {
                              "price": 2.5,
                              "price_addl": 2.5,
                              "method": "UK_Royal Mail Airmail International",
                              "location_groups": [
                                    "Everywhere Else"
                              ],
                              "location_countries": [
                                    "2316"
                              ]
                  ],
                  "item_weight": "0",
                  "item_weight_minor": "0",
                  "package_depth": 0,
                  "package_length": 0,
                  "package_width": 0,
                  "shipping_details": "",
                  "active": "1",
                  "closed": "0",
                  "nb_clicks": "87",
                  "created_at": "2017-11-09 13:11:06",
                  "images": [
                        " https://www.hipstamp.com/uploads/9f0.jpg "
                  ],
                  "item_specifics_01_country": "Antigua",
                  "item_specifics_02_catalog_number": "SG98",
                  "item_specifics_04_condition": "used",
                  "item_specifics_05_stamp_format": "single"
                  "Bids": [
                        {
                              "user_id": "109400",
                              "amount": "36.00",
                              "outbid": "0",
                              "created_at": "2017-11-16 10:41:51"
                        },
                        {
                              "user_id": "104692",
                              "amount": "35.50",
                              "outbid": "1",
                              "created_at": "2017-11-16 10:41:51"
                        }
                  ],
            }
      ],
      "params": {
            "id": "16669938"
      }
}

    • Related Articles

    • Bid

      Bid Overview A bid placed on an auction by a User, which is attached to a listing. To determine the current (or winning) bid of an auction listing, retrieve the Bid where outbid is set to 0 (false). Fields Field Visibility Type Description ...
    • Postage

      Postage Overview A Postage represents a single postage option attached to a Listing. If you do not plan to create different postage costs for different Listings, we recommend that when creating or updating Listings through the API, that you leave the ...
    • Sale

      Sale Overview When a Buyer makes a purchase on Hip eCommerce, whether it is through an auction, offer, or fixed price listing, a Sale (Order) is created. Only the Buyer and Seller of the Sale (Order) will have access to it. Searching Sales As a ...
    • LocationGroup

      LocationGroup Overview A Location Group is a resource that is attached to the Postage resource of a Listing. A Location Group represents a group of one or more countries. By default, all Sellers have two Location Groups set: "Domestic" which ...