Using the On-Demand Sales API
The Sales API allows Nanacast publishers a way to securely retrieve information about sales remotely and quickly without the need to download spreadsheets and manually enter data. It provides sales data on demand as a response to properly formatted requests, much like other modern APIs.
Let’s dig in!
Getting Set Up
Log in to your Nanacast account and navigate to the Profile & Preferences page
Open the “Advanced Transaction APIs” section and look for the On-Demand Sales API subsection.
Make note of the API endpoint (this is where you post requests to) and then enter a custom API Passphrase of your choosing in the input field that appears after clicking the “Change” link.
Provide a source URL. This is used to authorize the URL making the request. Provide the domain only. For example, if you are making the request from http://mycooldomain.com/stuff/nanacastSalesAPI.php, only provide http://mycooldomain.com as the source URL.
Click the “Commit” button.
Making a Request
To make a request for sales data, you must first create a request payload consisting of a JSON object wrapped in an object or array that has a name/key of "json". The following JSON object should be the value of the "json" wrapper object/array:
If you’re not familiar with JSON, it is a simple notation standard used to encapsulate data for lightweight transmission between servers. It is also very popular because it is so familiar, lightweight, and efficient to write. It consists of “keys” and “values”, which you can see clearly on lines 14 through 31. The keys and values are separated by a colon. On line 13, you can see the “options” key - it has a corresponding value of another JSON object, which is encapsulated within curly braces. You can create as many levels of JSON objects within a JSON object as you would like, but for our purposes, we’ll stick to a simple 3-level JSON object.
In order to construct the right JSON object for your purposes, you need to know what each parameter does. Parameters in black are required and those in green are optional.
sales - Provides a wrapper for the corresponding sales data request. In the future, we will provide the ability to request other types of data via On-Demand API that will use different wrapper names, such as “affiliates” or “users”. For now, you must place all of your request parameters in the sales object.
offerIds - Offer IDs for which you would like to request sales data. You may supply as many Offer IDs are you would like, or, you may omit this parameter altogether if you would like to retrieve sales data for every offer in your Nanacast account.
Note: It is recommended that you filter by Offer ID if you have over 50 offers in your account.
startDate - Specifies the beginning of the date range for the sales data you would like to retrieve. Must be formatted as yyyy-mm-dd
endDate - Specifies the end of the date range for the sales data you would like to retrieve. Must be formatted as yyyy-mm-dd
affiliateId - An optional parameter that allows you to retrieve sales data for one of your affiliates.
brokerId - An optional parameter that allows you to retrieve sales data for one of your brokers, or 2nd-tier affiliates.
currency - A valid, Nanacast-supported 3 digit currency code. Only offers that use the currency specified will be returned.
options - Options allow you to determine what sales data is returned. You can specify them in any order, just as long as they have numeric keys and valid values. All of the options are, well, optional, but if the options object is omitted, by default, the API will treat your request as if all 18 options had been specified. The values are defined as follows:
totalClientsToDate - The total number of active clients (the startDate and endDate parameters do not apply to this data)
clicks - The total number of unique clicks on the embedded order form or secure checkout page for the date range selected (one click is recorded per visitor per session). Or it is the total number of unique clicks on the affiliate link when viewing the report for an affiliate
clients - The total number of active clients who joined during the date range selected
conversionRate - The conversion rate for the offer, supplied as a decimal. (Clients / Clicks)
sales - The number of sales transactions made during the date range selected
subtotal - The subtotal before shipping, handling, tax or order processing fees
shipping - The shipping charged to the order
handling - The handling charged to the order
tax - The tax charged to the order
gross - The total amount charged to the order
fee - The amount charged by the order processor as a fee
net - Net is the Gross minus the Fee. Fee and Net are calculated automatically by Paypal for Paypal orders, and are calculated by our system for 2Checkout and Credit Card orders based on the fee percentages you've entered in your Preferences
commission - The affiliate commission you have paid or will pay out for the transaction
profit - The Net minus Shipping, Handling, Tax and Commission
forecast - The total amount that will be billed via credit cards during the next billing interval (no PayPal). Ex: If your billing interval is 30 Days, this is the amount that is set to be collected over the next 30 days. (The date range you selected above is not applied to this column)
funnelTotal - The Gross amount collected for the entire sales funnel, including upsells and downsells following this original offer
funnelTotalPerVisitor - The amount collected per visitor, or per unique click
funnelTotalPerClient - The amount collected per client
Once you have decided how to structure your JSON object, you will need to POST it to the API endpoint, wrapped as the value in an object that has a key of “json”. The API script (written in PHP) must be able to decode your JSON by checking if $_POST[‘json’] is set, and then attempts to extract your JSON instructions.
Catching the Response
Once you have successfully formatted your request and are receiving data, you will need to process that data. The data you will receive is formatted according to the JSend standard, as defined by OmniTI Labs.
If there are errors with the parameters provided in the request, e.g., there is a typo, the response will be formatted as follows:
In the example, “parameterName” will be replaced with the user-supplied parameter that caused the failure. The “error message” value will also be replaced with a relevant message and can be helpful while debugging.
If there is an error with our server or on our end, the response will be formatted as follows:
This example shows a real error response, except for the “error message” value. That will be replaced with something more relevant in a real test.
If everything goes as planned and you receive a successful response, it will be formatted as follows:
This is an example of a real response, filled with fake data. The object contains a “status” name-value pair (NVP) with “success” as the value and a “data” NVP with the response payload as the value.
The response is formatted so that the data for each offer is contained within an object that is keyed with the Offer ID of the offer it describes. The data for each offer perfectly mirrors the format of the request you sent to the API endpoint, with the exception of the additional offerName and currency fields found in the response. This makes it very easy to understand the response as it should be immediately familiar.
Every Nanacast account is limited to a maximum of 4 API requests per minute while the API is in beta. As we figure out the system impact this API has, we may modify the limit. Regardless, this should provide ample access to nearly real-time data stats.
Every Nanacast account has a set of permissions associated with API access. Currently, we have no restrictions on access to the API - any Nanacast user with access to the Advanced Transaction APIs settings may make unrestricted requests.
If, after thoroughly reading and understanding this documentation, you have a technical question regarding the API and it’s usage, do not hesitate to contact Nanacast support.