Create Listing

post https://www.hipstamp.com/api/listings

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.

Body Params

listing_type

string

Defaults to product

The type of listing.

name

string

required

length ≤ 80

The name (title) of the listing. Max 80 characters.

description

string

required

length ≤ 8000

The description of the listing. Max 8000 characters, no HTML.

category_id

integer

required

Must be a valid (leaf) Category ID. See HipStamp Category IDs, HipPostcard Category IDs, HipComic Category IDs.

private_id

string

If 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. The API will return a response code of 200 as opposed to 201.

currency

string

The currency of the listing.

quantity

integer

required

The quantity of items available in the listing. Must be greater than 1.

start_price

float

required

Required when listing_type = auction.

buyout_price

float

required

Required when listing_type = product.

enable_make_offer

boolean

If buyers can make offers on the listing.

make_offer_min

float

The hidden minimum offer amount set by the Seller which an offer must meet.

make_offer_max

float

The hidden maximum offer amount set by the Seller which an offer must meet.

start_time

date-time

If set for the future, the listing will be scheduled to start at the indicated time.

duration

integer

The duration of the listing.

hpfeat

boolean

If the listing is homepage featured.

country

integer

A valid Country ID.

state

string

A valid State ID or string (if outside the list of countries where State IDs are defined).

postal_code

string

A zip or postal code.

accept_returns

boolean

Whether the seller accepts returns.

returns_policy

string

Optional text explaining the returns policy.

postage

array of objects

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 postage field blank. This will result in your Listing being assigned your default postage costs and options, which can be set from the Members Area > Selling > Seller Tools > Default Listing Settings page.
Combined Shipping: On Hip eCommerce, when an item is purchased, the cost to ship the item is represented by the price in the Postage resource. If a buyer purchases multiple items from a Seller in a single Sale (Order), the highest price for any of the applicable Postage resources will be used for the attached Listing. All other Listings will be charged the price_addl rate instead (the cost to ship the item as an additional item in a Sale (Order)). If there is a specific item which you do not wish to offer combined shipping on, simply set the price and price_addl to the same rate. However, please keep in mind that Hip eCommerce requires all shipping settings to be reasonable and not excessive.
Table Rate Shipping per Number of Items: The price_addl field can be used to set-up table rate shipping per number of items in a Sale (Order). For example, 3.00/5 where 3.00 would only be added after every 5th additional item in the Sale (Order).

postage

item_weight

integer

Only required if the User is using calculated shipping.

item_weight_minor

integer

Only required if the User is using calculated shipping.

package_depth

integer

The depth of the package.

package_length

integer

The length of the package.

package_width

integer

The width of the package.

shipping_details

string

Additional shipping details.

images

array of urls

An array of URLs which list the images associated with the listing. The first item returned is the main image.

images

item_specifics_*

string

Custom item specifics for the listing, depending on the marketplace.

Response

Response body

object

integer

The ID of the listing.

listing_type

string

The type of listing (auction or product).

auction product

name

string

The name (title) of the listing.

description

string

The description of the listing.

user_id

integer

The ID of the User who owns the listing.

username

string

The username of the User who owns the listing.

category_id

integer

A valid Category ID. See HipStamp Category IDs, HipPostcard Category IDs, HipComic Category IDs.

private_id

string

[Only returned if you are the Seller of the listing] A private ID assigned by the User to the listing.

external_id

integer

[Only returned if you are the Seller of the listing] The listing ID of the same item on an external site, automatically generated when using one of our sync features.

external_id_type

string

[Only returned if you are the Seller of the listing] The name of the external site that external_id is associated with.

currency

string

The currency of the listing.

quantity

integer

The quantity of items available in the listing.

start_price

float

Will be set to 0 for listing_type = 'product'.

buyout_price

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

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

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

boolean

If buyers can make offers on the listing.

make_offer_min

float

[Only returned if you are the Seller of the listing] The hidden minimum offer amount set by the Seller which an offer must meet.

make_offer_max

float

[Only returned if you are the Seller of the listing] The hidden maximum offer amount set by the Seller which an offer must meet.

high_bidder_username

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

integer

Only applies to listing_type = 'auction'. The number of bids placed on an auction. May not be returned if empty.

start_time

date-time

The start time of the listing.

end_time

date-time

The end time of the listing.

duration

integer

The duration of the listing.

hpfeat

boolean

If the listing is homepage featured.

country

integer

A valid Country ID.

state

string

A valid State ID or string (if outside the list of countries where State IDs are defined).

postal_code

string

The postal code of the listing.

accept_returns

boolean

Whether the seller accepts returns.

returns_policy

string

Optional text explaining the returns policy.

postage

array of objects

The postage costs to ship the item.

postage

object

price

float

The cost to ship the item by itself.

price_addl

string

The cost to ship the item as an additional item in a Sale (Order). Can be an integer or a string (e.g., "3.00/5").

method

string

The method of shipment (e.g., First Class Mail).

type

string

Optional. If set, it will override the Account-Based Postage Calculation Type.

item: Represents standard item-based shipping, using the price, price_addl, and method fields to determine the shipping cost. - carriers: Represents calculated shipping, where the shipping cost is automatically calculated based on carrier rates (e.g., USPS, UPS, FedEx).
Note: When type is set to carriers, the fields price, price_addl, and method are optional and will be ignored if set.

item carriers

location_groups

array of strings

The location groups applicable to this postage option.
Notes on Location Groups: The default Location Groups available to all Users are "Domestic" and "Everywhere Else", which represent the Seller's home country, and all other countries respectively. However, please note that Sellers can customize their Location Groups. This can be something as simple as adding a new Location Group named "Europe" which covers all Europe countries. However, Sellers can entirely remove the Location Groups "Domestic" and "Everywhere Else", and create new Location Groups with completely different names. This is of significant importance within the Hip eCommerce API, because all Listings are required to have at least one valid Postage resource attached, which must be attached to a specific Location Group. If the name of the Location Group does not exist within the Seller's Location Groups, the Postage resource will be invalid. To avoid such issues, you can periodically check what Location Groups are available to the current Seller through the getLocationGroups method. Note: Sellers can customize their Location Groups from the Members Area > Selling > Seller Tools > Postage Setup page.

location_groups

location_countries

array of integers

A list of Country IDs, automatically generated from location_groups. Notes on Type: If Type is set, this will override the Account-Based Postage Calculate Type. item represents standard item based shipping, in which the price, price_addl, and method fields will be used to determine the cost to ship an item. carriers represent calculated shipping, in which the cost to ship an item will automatically be calculated based on carrier rates. Which carriers you enable, such as the USPS, UPS or FedEx can be updated from the Members Area > Selling > Seller Tools > Postage Setup page. Note that when setting type to carriers, price, price_addl, and method is optional, and if set, will be ignored. Additionally, please note that if you create a new listing which uses the type carriers, and you do not currently have any carriers enabled from the Postage Setup page, one will be enabled for you by default.

location_countries

item_weight

integer

The weight of the item. May not be returned if empty.

item_weight_minor

integer

The minor weight of the item. May not be returned if empty.

package_depth

integer

The depth of the package. May not be returned if empty.

package_length

integer

The length of the package. May not be returned if empty.

package_width

integer

The width of the package. May not be returned if empty.

shipping_details

string

Additional shipping details.

active

boolean

Whether the listing is active.

closed

boolean

Whether the listing is closed.

deleted

boolean

[Only returned if you are the Seller of the listing] Whether the listing is deleted. Private field.

draft

boolean

[Only returned if you are the Seller of the listing] Whether the listing is a draft. Private field.

nb_clicks

integer

The number of views by buyers.

created_at

date-time

The creation time of the listing.

updated_at

date-time

[Only returned if you are the Seller of the listing] The last update time of the listing. Private field.

images

array of urls

An array of URLs which list the images associated with the listing. The first item returned is the main image.

images

url

string

The URL to the listing on our website.

Bids

array of objects

[Only returned if you are the Seller of the listing]

Bids

object

user_id

integer

The ID of the user who placed the bid.

amount

float

The amount of the bid.

outbid

boolean

Whether the bid was outbid.

created_at

date-time

The time the bid was created.

item_specifics_01_country

string

[HipStamp Only] The country of origin for the stamp.

item_specifics_02_catalog_number

string

[HipStamp Only] The catalog number of the stamp.

item_specifics_03_stamp_type

string

[HipStamp Only] The type of stamp. List of Valid Values

item_specifics_04_condition

string

[HipStamp Only] The condition of the stamp. List of Valid Values

item_specifics_05_stamp_format

string

[HipStamp Only] The format of the stamp. List of Valid Values

item_specifics_06_topic

string

[HipStamp Only] The topic of the stamp. List of Valid Values

item_specifics_07_year_of_issue

integer

[HipStamp Only] The year the stamp was issued.

item_specifics_08_centering

string

[HipStamp Only] The centering of the stamp. List of Valid Values

item_specifics_09_has_a_certificate

string

[HipStamp Only] Whether the stamp has a certificate. List of Valid Values

item_specifics_10_certificate_grade

string

[HipStamp Only] The grade of the certificate. List of Valid Values

item_specifics_02_condition

string

[HipPostcard Only] The condition of the postcard. List of Valid Values

item_specifics_03_postcard_type

string

[HipPostcard Only] The type of postcard. List of Valid Values

item_specifics_10_series_name

string

[HipComic Only] The series name of the comic.

item_specifics_12_issue_number

string

[HipComic Only] The issue number of the comic.

item_specifics_02_publisher

string

[HipComic Only] The publisher of the comic. List of Valid Values

item_specifics_01_main_character

string

[HipComic Only] The main character of the comic. List of Valid Values

item_specifics_03_genre

string

[HipComic Only] The genre of the comic. List of Valid Values

item_specifics_04_grade

string

[HipComic Only] The grade of the comic. List of Valid Values

item_specifics_05_certification

string

[HipComic Only] The certification of the comic. List of Valid Values

item_specifics_06_signed

string

[HipComic Only] Whether the comic is signed. List of Valid Values

201Listing created successfully.