This article describes the various endpoints related to Purchases / Sales. Using the various endpoints in this API, you can export data of the purchases shared, referral sales information or sales recorded by the system.


Referral Sales Endpoint


The Referral Sales endpoint allows you to export the referral sales that have occurred. Referral Sales are the sales the user generated posts drive in your store. For example, a user (Person A) makes a purchase on your store and at the end of the purchase, shares the purchase on Facebook. A friend of Person A (let's call her Person B) discovers the post on Facebook, clicks on it, lands on your online store and makes a purchase. This purchase by Person B is a referral sale. This endpoint will allow to export the referral sales that have occurred.


The above is an example of how a referral sale can occur. There are various ways which can generate referral sales for your store. The sources which can generate referral sales are - 

  1. Share-a-Purchse : When a person shares a purchase on Facebook.
  2. Social Connect   : When a person connects with Facebook on your store via the SocialConnect app and posts on Facebook.
  3. Share-on-Mobile  : When a person shares a picture of the purchase received on Facebook via Share-on-Mobile


Type of Request: POST

Endpoint : /resource/purchases/referrals

Full URL : https://api.shopsocially.com/v2/resource/purchases/referrals


Request Parameters


The following table outlines the POST request parameters that you can use with this endpoint.


Parameter Value Description
start_date Date in the format "yyyy-mm-ddTHH:MM:SSZ" in the UTC timezone. (Optional) Signifies the date from which you want the data. Referral Sales that have occurred on and after this date will be returned. The date is inclusive, that is, you will get the data for this date as well.
end_date Date in the format "yyyy-mm-ddTHH:MM:SSZ" in the UTC timezone. (Optional) Signifies the date till which you want the data. Referral Sales that have occurred on and before this date will be returned. This date is inclusive, that is, you will get the data for this date as well.


Response


On a successful request, this API returns a JSON response containing the list of referral sales. The meaning of the various fields are included in the following response - 


{

    "success": true,

    "referrals": [

        {

            "order_id": "<The order ID of the referred sale>",

            "date": "<The date and time when the referred sale occurred in the format yyyy-mm-ddTHH:MM:SSZ>",

            "referred_buyer_info": {

                "first_name": "<The first name of the person who bought as a result of the referral>",

                "last_name": "<The last name of the person who bought as a result of the referral>",

                "email": "<The email address of the person who bought as a result of the referral>",

                "zipcode": "<The zipcode of the person who bought as a result of the referral>"

            },

            "referred_product_info": {

                "product_url": "<The URL of the product which was purchased as a result of the referral>",

                "image_url": "<The URL of the product image which was purchased as a result of the referral>",

                "product_id": "<The product ID of the product which was purchased as a result of the referral>",

                "price": "<The price of the product which was purchased as a result of the referral>"

            },

            "referrer_info": {

                "first_name": "<The first name of the original referrer>",

                "last_name": "<The last name of the original referrer>",

                "email": "<The email address of the original referrer>",

                "facebook_profile": "<The facebook profile URL of the original referrer>"

            },

            "referring_entity": {

                "entity_url": "<The URL of the entity which caused the referral click>",

                "image_url": "<The URL of the entity image which caused the referral click>"

            }

        }

    ]

}


As you find in the example response above, the referral sales are in a list in the referrals field.



< Back to Main