Sale

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.
gateway_transaction_code
private
string
If the API caller is the seller, this will be the PayPal Transaction ID associated with the sale, if applicable. 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: /stores/: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

gateway_transaction_code
N
string
Filter by an external transaction code (ie: PayPal)

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

gateway_transaction_code
N
string
Filter by an external transaction code (ie: PayPal)

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 canceled, etc. It's recommended 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

gateway_transaction_code
N
string
Filter by an external transaction code (ie: PayPal)

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 not set to 0 (unpaid / processing). Note that this will not include Sales where the payment status is set to canceled, 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

gateway_transaction_code
N
string
Filter by an external transaction code (ie: PayPal)

findAllStoresSalesPaidNotShipped

Method Name: findAllStoresSalesPaidNotShipped
Synopsis: Finds all Sales for the specified User (by username) who is the Seller of the Sales, where the flag_payment is not set to 0 (unpaid / processing) and the flag_shipping is set to 0 (not yet shipped). Note that this may include Sales where the payment status is set to canceled, etc. It's recommended to review the flag_payment for appropriate action.
HTTP Method: GET
URI: /stores/:username/sales/paid_unposted
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

gateway_transaction_code
N
string
Filter by an external transaction code (ie: PayPal)

findAllStoresSalesShipped

Method Name: findAllStoresSalesShipped
Synopsis: Finds all Sales for the specified User (by username) who is the Seller of the Sales, where the flag_shipping is set to 1 (shipped).
HTTP Method: GET
URI: /stores/:username/sales/posted_sent
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

gateway_transaction_code
N
string
Filter by an external transaction code (ie: PayPal)

Examples

findAllStoresSalesPaid

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

    • Related Articles

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

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

    • Message

      Message  Overview Member to member communication is handled through the Hip eCommerce Message system. Only the Sender and Receiver of the Message will have access to it. Searching Messages By default, the method findAllMessages returns all unarchived ...

    • SaleListing

      SaleListing Overview A SaleListing is attached to a Sale (Order) and represents a single line item, with financial information such as price and quantity, as well as a summary of the Listing for the line item. Only the Buyer or Seller of the Sale ...