Company Blog Support
Martin Cogburn
posted

Contents

    Back to Top

    Products API

    UPDATE:

    We have a new and improved API for ONTRAPORT users. You can find the documentation HERE. 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

    1. Sale - log a sale
    2. Refund - mark an existing sale as refunded
    3. Delete - delete a sale
    4. Add - add a new product
    5. Update - update an existing product
    6. Fetch - fetch a list of products in the account
    7. Key - request a template of a product
    8. Search - search for a product
    9. Search Purchase - search for a purchase
    10. Purchase History - request purchase history for a contact
    11. 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)

    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)

    Delete

    Request: delete

    Action: Deletes the indicated purchase from the contact's purchase history

    Return: Success or fail Message

    Required Data: Purchase ID

    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. 

    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

    Fetch

    Request: fetch

    Return: Details of indicated products

    Required Data: Product ID(s)

    Key

    Request: key

    Return: Templates for both a product and a purchase log entry (provides proper syntax for adding/updating a product/purchase)

    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 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)

    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.

    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.

    Have more questions? Submit a request

    Comments

    Powered by Zendesk