Hip eCommerce

            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.
            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.
            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.

            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"
                  }
            }

            Updated: 03 Feb 2019 10:26 AM
            Helpful?  
            Help us to make this article better
            1 3