Products API (deprecated)
About the Products API
Applies to: ONTRAPORT Plus and above.
Note: We have a new and improved API for ONTRAPORT users. You can find the documentation HERE. The old API code found here previously is now deprecated.
For the examples below, we've added the equivalent calls using the new API (where available). While we don't have any plans to disable the old API, we do suggest switching over to this faster, more powerful version. Please note that with the new API, authentication is handled via the request headers (as opposed to being passed in the POST data). Please refer to the documentation page for more information.
Products API
All of our example code can be found on GitHub
Table of Contents
- Sale - log a sale
- Refund - mark an existing sale as refunded
- Delete - delete a sale
- Add - add a new product
- Update - update an existing product
- Fetch - fetch a list of products in the account
- Key - request a template of a product
- Search - search for a product
- Search Purchase - search for a purchase
- Purchase History - request purchase history for a contact
- Log Transaction - logs a transaction for a contact
Introduction
The Products API allows for adding and updating products and purchase logs within your account.
Authentication
Use of the Products API requires an API App ID and API Key. These can be generated within your Ontraport account by going to Account > Ontraport API Instructions and Key Manager.
Also, be sure to select the appropriate permissions for the key you are about to generate (for example, if a key does not have "add" permissions selected, it will not be able to be used to add type requests.
Note that if you have not done so already, you will need to submit a request for access to the API. Once access is granted, you can generate as many API App ID/API Key combinations as you want. For more information on how to generate a key or how to request access, please contact customer support.
Requests Overview
Currently we use REST Requests to handle requests to the web server. Typically XML data is posted via POST to the feed URL and a 'success', 'failure' or 'return data' will be returned depending on the type of call. REST supports a number of web server environments for development, and it's a pretty easy system to learn. Learn all about REST.
A typical request consists of two parts; a URL and post data.
The post URL is comprised of the API address (in this case, http://api.ontraport.com/pdata.php) along with the following paramenters.
| Parameter | Data | Description |
| Appid | string (Required) | You must first generate an App ID to use the API. Instructions to generate a key are in the "Authentication" section (above). |
| Key | string (Required) | This is a unique key that you can generate for use in your App ID. |
| reqType | string (Required) | Request type. See "Request Types" (below) for information detailing each request type. |
| data | string (Required in all but key requests) | XML data (varies based on request type) |
| return_id | numeric |
1 - full purchase/product details are returned in addition to the standard Success/Failure message |
A basic request should resemble the following:
Request URL:
https://api.ontraport.com/pdata.php
POST data:
appid=abc12345&key=xyz54321&returnID=[return_id]&reqType=[request_type]
Date Format
All dates passed to the ONTRAPORT API must be in Unix Time format (also known as seconds since epoch). To get the Unix Time version of a standard date/time, you can use a converter (such as EpochConverter). Most programming languages should have built in methods for date conversion as well.
ID Precedence
Products use 3 different fields in order to match a sale/transaction with an existing product; external_id(hidden), product_id, and name - in that order. If a match is not found, the API will attempt to create a new product based on the provided information.
Returns:
Unless otherwise noted, most requests return a simple Success or Failed message formatted as follows:
<result><status>Success</status></result>
<result><status>Failed</status></result>
Maximum Requests per Minute
Up to 180 requests per minute are allowed per ONTRAPORT account
Request Types
Sale
Request: sale
Action: Logs a purchase for a given product in the contact's contact record
Return: Success or fail message. If return_id is set, product details (name, price, description, quantity, commissions, date) are returned in addtion to success/fail
Required Data: Contact ID, product ID
Optional Data: Product Data (in order to overwrite saved product information)
<?php <purchases contact_id="12345" product_id='1'> <field name="Price">10.00</field> //Override the standard price of the product </purchases>
//The following return was a result of setting return_id=1 on the original request <result> <purchases contact_id="12345" product_id="1" id="1234"> <field name="Name">Product 1</field> <field name="Price">$10.00</field> <field name="Quantity">1</field> <field name="Date">11-27-2012</field> </purchases> <status>Success</status> </result>
URL: http://api.ontraport.com/1/objects
Method: POST
Data:
{
"objectID": 17,
"contact_id": 12345,
"trans_date": 1354003200,
"product_id": 1,
"price": 10
"quantity": 1
}
Doc: http://api.ontraport.com/doc/#!/objects/createObject
Refund
Request: refund
Action: Refunds the indicated purchase. Purchase Status is set to "Refunded". Purchase price is set to the original purchase price minus the refund amount (varies depending on request)
Return: Success or fail Message
Required Data: Purchase ID
Optional Data: Refund amount (cannot exceed original purchase price)
<purchases id='1234'> <refund>5.00</refund> //optional data to issue partial refund </purchases>
URL: https://api.ontraport.com/1/transaction/refund
Method: PUT
Data:
{
"objectID": 0,
"ids": [
1234
],
"performAll": true,
"condition": "string",
"sort": "string",
"sortDir": "asc",
"range": 0,
"start": 0,
"group_id": 0,
"search": "string",
"searchNotes": "string",
"externs": "string",
"date_range": [
0
]
}
Doc:
https://api.ontraport.com/doc/#!/transactions/refund
Delete
Request: delete
Action: Deletes the indicated purchase from the contact's purchase history
Return: Success or fail Message
Required Data: Purchase ID
<purchases id='4178' />
Add
Request: add
Action: Adds a new product to the account with the provided information
Return: Success or fail message. If return_id flag is set, complete product information is returned.
Required Data: At least one product related field inside <product> and <Group_Tag> tags.
Optional Data: Any of the following fields can be passed upon creation of a new product.
Name
Price
Note: As stated above, at least one of these fields needs to be passed in order to successfully create a new product.
<product> <Group_Tag name="Product Details"> <field name="Name">New Product</field> <field name="Price">250.00</field> </Group_Tag> </product>
URL: https://api.ontraport.com/1/objects?objectID=16 Method: POST Data: name=New%20Product&price=250 Doc: https://api.ontraport.com/doc/#!/objects/createObject
Update
Request: update
Action: Updates an existing product with the provided details
Return: Success or fail message
Required Data: Product ID
Optional Data: Name, Price
<product id="2"> <Group_Tag name="Product Details"> <field name="Name">Name</field> <field name="Price">250.00</field> </Group_Tag> </product>
URL: https://api.ontraport.com/1/objects Method: PUT Data: objectID=16&id=2&name=Name&price=250 Doc: https://api.ontraport.com/doc/#!/objects/updateObjects
Fetch
Request: fetch
Return: Details of indicated products
Required Data: Product ID(s)
<product_id>1</product_id> <product_id>2</product_id>
<result> <product id="1"> <Group_Tag name="Product Details"> <field name="Name">Product 1</field> <field name="Price">$10.00</field> </Group_Tag> </product> <product id="2"> <Group_Tag name="Product Details"> <field name="Name">Product 2</field> <field name="Price">$15.00</field> </Group_Tag> </product> </result>
URL: https://api.ontraport.com/1/object?objectID=16&id=40 Method: GET Doc: https://api.ontraport.com/doc/#!/objects/getObject
Key
Request: key
Return: Templates for both a product and a purchase log entry (provides proper syntax for adding/updating a product/purchase)
<?php
// Replace the strings with your API credentials located in Admin > OfficeAutoPilot API Instructions and Key Manager
$appid = "XXXXXXXXXXX";
$key = "XXXXXXXXXXX";
$reqType= "key";
$postargs = "appid=".$appid."&key=".$key."&reqType=".$reqType;
$request = "https://api.ontraport.com/pdata.php";
$session = curl_init($request);
curl_setopt ($session, CURLOPT_POST, true);
curl_setopt ($session, CURLOPT_POSTFIELDS, $postargs);
curl_setopt($session, CURLOPT_HEADER, false);
curl_setopt($session, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($session);
curl_close($session);
header("Content-Type: text/xml");
echo $response;
<result> <product id=""> <Group_Tag name="Product Details"> <field name="Name" type="text"/> <field name="Price" type="price"/> </Group_Tag> </product> <purchases contact_id="" product_id="" id=""> <field name="Name" type="text"/> <field name="Price" type="price"/> <field name="Status" type="tdrop"/> <field name="Quantity" type="numeric"/> <field name="Date" type="timestamp"/> <field name="Order Number" type="text"/> <field name="Date Modified" type="timestamp"/> <field name="Quantity" type="number"/> <field name="Date" type="timestamp"/> </purchases> </result>
Search
Request: search
Return: Product details of matching entries (if any), 0 if no results are found
Required Data: Search criteria
Search Operators:
To run a search, surround your data with a <search> tag and use the <equation> tag for each type of query you would like to search for. Every equation requires a field, an op (operation) and a value
<search>
<field>
<operator>
<value>
Here are the availabe operators:
'e' Equal
'n' Not equal
's' Starts with
'c' Like (Ex: Email <op>c</op>@gmail.com will return a search of all the emails that match gmail.com)
'k' Not Like
'l' Less than
'g' Greater Than
'm' Less Than or Equal to
'h' Greater Than or Equal to
The data for a standard search request would look something like this:
<search>
<equation>
<field>Price</field>
<op>e</op>
<value>10.00</value>
</equation>
</search>
This would return any products whose price is equal to 10.00
Note: Search requests are limited to 500 results. Pagination is available for results which return more than 500 records. The "page" attribute can be added to the opening search tag to indicate the desired page number.
Example:
<search page='2'>
<equation>
<field>Price</field>
<op>e</op>
<value>10.00</value>
</equation>
</search>
<search>
<equation>
<field>Price</field>
<op>e</op>
<value>150.00</value>
</equation>
</search>
<result> <product id="1"> <Group_Tag name="Product Details"> <field name="Name">Product 1</field> <field name="Price">$150.00</field> </Group_Tag> </product> </result>
URL: https://api.ontraport.com/1/objects?objectID=16&condition=
[
{
"field": { "field": "name" },
"op": "=",
"value": { "value": "Product 1" }
},
"AND",
{
"field": { "field": "price" },
"op": "=",
"value": { "value": "150" }
}
]
Method: GET
Doc:
https://api.ontraport.com/doc/#!/objects/getObjects
Search Purchase
Request: search_purchase
Return: Details of purchases matching the search criteria (if any)
Required Data: Search criteria
Search Operators: See syntax for searches in Search (above)
<search><equation>
<field>Price</field>
<op>e</op>
<value>150.00</value>
</equation>
</search>
<purchases> <purchase contact_id="12345" product_id="1" id="123"> <field name="Product Name">Product 1</field> <field name="Price">150</field> <field name="Quantity">1</field> <field name="Date">1337884760</field> <field name="Total"/> </purchase> <purchase contact_id="54321" product_id="1" id="456"> <field name="Product Name">Product 1</field> <field name="Price">150</field> <field name="Quantity">1</field> <field name="Date">1347636099</field> <field name="Total"/> </purchase> </result>
URL: http://api.ontraport.com/1/objects?objectID=17&condition=
[
{
"field": { "field": "price" },
"op": "=",
"value": { "value": "150" }
}
]
Method: GET
Doc:
https://api.ontraport.com/doc/#!/objects/getObjects
Purchase History
Request: purchase_history
Return: Details of purchases matching the search criteria (if any)
Required Data: <purchase_history> tags (if no search criteria is included inside them, a full purchase history for the past 10 days will be returned)
Optional Data: Any combination of the following can be used in the data portion of the request:
<contact_id>
<product_id>
<start_date>
<end_date>
<quantity>
Note that if a start and/or end date is not passed, the purchase history will return the search within the last 10 days. Therefore, if only a start date is passed, the return will be purchases matching the search criteria up to 10 days since the start date.
// The following will search for any purchase log entries between 11/1/2012 and 11/28/2012 where exactly 2 of product 1 or product 2 were purchased <purchase_history> <start_date>1351753200</start_date> <end_date>1354176000</end_date> <product_id>1,2</product_id> //multiple products can be searched by separating with commas <quantity>2</quantity> </purchase_history>
URL: http://api.ontraport.com/1/objects?objectID=17&date_range=1429554727%2C1431109778&condition=
[
{
"field": { "field": "product_id" },
"op": "IN",
"value": { "list": [ {"value": "1"}, {"value": "2"} ] }
},
"AND",
{
"field": { "field": "quantity" },
"op": "=",
"value": { "value": "2" }
}
]
Method: GET
Doc:
https://api.ontraport.com/doc/#!/objects/getObjects
Log Transaction
Request: log_transaction
Return: Details of purchases matching the search criteria (if any)
Required Data: contact ID and JSON encoded transaction data.
Optional Data: Either product ID of existing product or new product data. Date of transaction will default to current date/time, but can be overridden in purchase data. You may also use an existing product and override the price and adjust quantity purchased on a per transaction basis.
Example:
{
"contact_id" : 123456,
"date":1366625710,
"products":[
{
"product_id":6,
"quantity":2,
"external_id":13,
"price":275
},
{
"product_id":13
}
]
}
NOTE: The "external_id" field is a hidden field that allows you to use an alternative to the ONTRAPORT product id (for an external id, sku, etc). If external_id is passed, the API will attempt to use that to match up the product. If it is not passed or doesn't match, it will attempt to use the product_id. If product_id is not passed, the API will attempt to create a new product based on the information provided. If no product_id is passed and no product name is specified, the transaction will fail.
{
"contact_id": 123456,
"date": 1366625710,
"products": [
{
"product_id": 6,
"quantity": 2,
"external_id": 13,
"price": 275
},
{
"product_id": 13
}
]
}
URL: http://api.ontraport.com/1/transaction/processManual
Method: POST
Data:
{
"objectID": 0,
"contact_id": 123456,
"chargeNow": "chargeLog",
"trans_date": 1366625710,
"invoice_template": 1,
"offer": {
"products": [
{
"quantity": 2,
"owner": 1,
"name": "new test",
"tax": true,
"shipping": true,
"id": 6,
"uid":0,
"price": [
{
"price": "275.00",
"payment_count": 1,
"unit": "day"
}
]
}
],
"hasTaxes": false,
"hasShipping": false,
"delay": 0
}
}
Doc:
http://api.ontraport.com/doc/#!/transactions/processManual
Comments