Hip eCommerce

            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 Seller (Orders)

            By default, the method findAllStoresSalesAll returns all Sales on Hip eCommerce, for the specified User, where the User is the Seller, paginated by newest Sales first. Use the optional parameters (such as created_time_from, etc.) to narrow these results. The sort parameter can be used to change the order of returned results. Additionally, the methods findAllStoresSalesPaid and findAllStoresSalesUnpaid can be used.

            As a Buyer (Purchases)

            By default, the method findAllSales returns all Sales on Hip eCommerce, for the specified User, where the User is the Seller, paginated by newest Sales first. Use the optional parameters (such as created_time_from, etc.) to narrow these results. The sort parameter can be used to change the order of returned results.

            Automatically Combined Sales (Orders)

            Important! If you do not take into account automatically combined sales in your application, you will likely run into serious issues.
            On Hip eCommerce, when an auction is won, or an offer is accepted, a Sale (Order) is immediately created. However, that Sale (Order) may change if the buyer then wins an additional auction or offer - before they have paid for the original Sale (Order). This is because the new purchases will be automatically combined with the previous unpaid Sale (Order) and a new Sale (Order) will be created.

            This is important for Buyers on Hip eCommerce, as it allows them to instantly check out and pay at any time with a single, combined Sale (Order), with correct and updated postage costs. For all intents and purposes, we delete the old Sale (Order) when this happens, and move the SaleListings from the old Sale (Order) to the new combined Sale (Order). We keep track of this within the combined_sales_ids field, which is an array of any and all Sale (Order) ids which were combined into the new Sale (Order). This in itself, is our recommended option one to account for this within your application. Like Hip eCommerce, when you come across a new Sale (Order), if it contains Sale (Order) ids in the combined_sales_ids, you can delete all of the previously referred to Sale (Order) ids within your system.

            Our recommended option two, is much simpler, and may be better suited for your workflow (and internal systems), however it has one caveat which we will discuss shortly. Option two would be to only import paid Sale (Orders) into your application / internal systems using the findAllStoresSalesPaid method. As paid Sale (Orders) can never be combined with new unpaid Sale (Orders), there would be no automatically combined sales which you would need to account for.

            The caveat however is that by waiting for the Sale (Order) to be paid, you would not be removing the Listing immediately from your own application, etc. once it sells with Hip eCommerce. This may work from some Sellers, but not for others (if you are worried about the Listing selling somewhere else as well). However, you can alleviate this caveat by using the findAllStoresListingsClosed with the show parameter set to "sold" which will return you all of the individual Listings that you sold with Hip eCommerce. You could then remove these items from your internal systems pending importation of the Sale (Order) once it is paid.

            Fields

            Field
            Visibility
            Type
            Description
            id
            public
            int

            buyer_id
            public
            int

            buyer_username
            public
            username

            buyer_email
            public
            string

            seller_id
            public
            int

            seller_username
            public
            username

            seller_email
            public
            string

            flag_payment
            public
            int
            A valid Payment ID.
            flag_shipping
            public
            int
            A valid Shipping ID.
            flag_buyer_payment
            public
            int
            A valid Buyer Payment ID.
            flag_buyer_shipping
            public
            int
            A valid Buyer Shipping ID.
            flag_payment_name
            public
            string

            flag_shipping_name
            public
            string

            flag_buyer_payment_name
            public
            string

            flag_buyer_shipping_name
            public
            string

            currency
            public
            currency

            tracking_link
            public
            string
            Not returned if empty.
            created_at
            public
            time

            shipping_address_id
            public
            int

            combined_sales_ids
            public
            array(int)
            Not returned if empty.
            postage_method
            public
            string

            sales_listings_amount
            public
            float

            postage_amount
            public
            float

            tax_amount
            public
            float

            total
            public
            float

            Associations

            Association
            Visibility
            Type
            Description
            ShippingAddress
            public

            SaleListings
            public

            Methods

            getSale

            Method Name: getSale
            Synopsis: Retrieves a Sale by id.
            HTTP Method: GET
            URI: /sales/:id
            Parameters:
            Name
            Required
            Type
            Notes
            id
            Y
            int
            The id of the Sale (Order) to retrieve.

            updateSaleBuyerStatus

            Method Name: updateSale
            Synopsis: Updates the buyer status of an existing Sale (Order) where the current User is the Buyer.
            HTTP Method: PUT
            URI: /sales/:id
            Parameters:
            Name
            Required
            Type
            Notes
            id
            Y
            int
            The id of the Sale (Order) you want to update.
            flag_buyer_payment
            N
            int
            A valid Buyer Payment ID.
            flag_buyer_shipping
            N
            int
            A valid Buyer Shipping ID.

            updateSaleSellerStatus

            Method Name: updateSaleSellerStatus
            Synopsis: Updates the seller status of an existing Sale (Order) for the specified User (by username) who is the Seller of the Sale (Order).
            HTTP Method: PUT
            URI: /store/:username/sales/:id
            Parameters:
            Name
            Required
            Type
            Notes
            id
            Y
            int
            The id of the Sale (Order) you want to update.
            username
            Y
            username
            The username of the Seller.
            flag_payment
            N
            int
            A valid Payment ID.
            flag_shipping
            N
            int
            A valid Shipping ID.
            tracking_link
            N
            string
            A shipment tracking number or link.

            findAllSales

            Method Name: findAllSales
            Synopsis: Finds all Sales where the current User is the Buyer.
            HTTP Method: GET
            URI: /sales
            Parameters:
            Name
            Required
            Type
            Notes
            limit
            N
            int
            Default: 25
            page
            N
            int
            Default: 1
            created_time_from
            N
            time
            created_time_to
            N
            time

            findAllStoresSalesAll

            Method Name: findAllStoresSales
            Synopsis: Finds all Sales for the specified User (by username) who is the Seller of the Sales.
            HTTP Method: GET
            URI: /stores/:username/sales/all
            Parameters:
            Name
            Required
            Type
            Notes
            limit
            N
            int
            Default: 25
            page
            N
            int
            Default: 1
            created_time_from
            N
            time
            created_time_to
            N
            time

            findAllStoresSalesPaid

            Method Name: findAllStoresSalesPaid
            Synopsis: Finds all Sales for the specified User (by username) who is the Seller of the Sales, where the flag_payment is set anything besides 0 (unpaid / processing). Note that this may include Sales where the payment status is set to cancelled, etc. It's recommend to review the flag_payment for appropriate action.
            HTTP Method: GET
            URI: /stores/:username/sales/paid
            Parameters:
            Name
            Required
            Type
            Notes
            limit
            N
            int
            Default: 25
            page
            N
            int
            Default: 1
            created_time_from
            N
            time
            created_time_to
            N
            time

            findAllStoresSalesUnpaid

            Method Name: findAllStoresSalesUnpaid
            Synopsis: Finds all Sales for the specified User (by username) who is the Seller of the Sales, where the flag_payment is set to 0 (unpaid / processing). Note that this will not include Sales where the payment status is set to cancelled, etc.
            HTTP Method: GET
            URI: /stores/:username/sales/unpaid
            Parameters:
            Name
            Required
            Type
            Notes
            limit
            N
            int
            Default: 25
            page
            N
            int
            Default: 1
            created_time_from
            N
            time
            created_time_to
            N
            time

            Examples

            findAllStoresSalesPaid

            Request:
            GET https://www.hipstamp.com/api/stores/JoeTheSeller/sales/paid?api_key={YOUR_API_KEY}&limit=1

            Response:
            {
               "count": 65,
               "type": "sale",
               "results": [
                  {
                     "id": "12345678",
                     "buyer_id": "11111",
                     "buyer_username": "BobTheBuyer",
                     "buyer_email": "bob@example.com",
                     "seller_id": "12345",
                     "seller_username": "JoeTheSeller",
                     "seller_email": "joe@example.com",
                     "flag_payment": "2",
                     "flag_shipping": "0",
                     "flag_buyer_payment": "2",
                     "flag_buyer_shipping": "0",
                     "flag_payment_name": "Paid (PayPal)",
                     "flag_shipping_name": "Processing",
                     "flag_buyer_payment_name": "Paid (PayPal)",
                     "flag_buyer_shipping_name": "Waiting",
                     "currency": "USD",
                     "created_at": "2017-11-16 21:01:02",
                     "shipping_address_id": "104262",
                     "combined_sales_ids": [ "1059452" ],
                     "postage_method": "First Class Mail",
                     "sales_listings_amount": 15.5,
                     "postage_amount": 2,
                     "tax_amount": 0,
                     "total": 17.5,
                     "ShippingAddress": {
                        "id": "104262",
                        "user_id": "106270",
                        "name_last": "Bob",
                        "name_first": "Buyer",
                        "address": "123 Main Street",
                        "city": "Brooklyn",
                        "country": "2084",
                        "state": "2197",
                        "postal_code": "11234",
                        "country_name": "United States",
                        "country_iso_code": "US",
                        "state_name": "New York",
                        "state_abbreviation": "NY",
                     },
                     "SaleListings": [
                        {
                           "id": "6353659",
                           "listing_id": "16669896",
                           "sale_id": "1059537",
                           "price": "5.00",
                           "quantity": "1",
                           "listing_name": "Sample Listing #1",
                           "private_id": "M162814"
                        },
                        {
                           "id": "6353773",
                           "listing_id": "16669923",
                           "sale_id": "1059537",
                           "price": "10.50",
                           "quantity": "1",
                           "listing_name": "Sample Listing #1",
                           "private_id": "M190047"
                        }
                     ]
                  }
               ],
               "params": {
                     "limit": "1",
                     "sales": "paid",
                     "username": "JoeTheSeller"
               }
            }

            Updated: 18 Dec 2017 02:06 PM
            Helpful?  
            Help us to make this article better
            0 2