purchase API

Record that a user has made a purchase or has added items to their shopping cart.

Make a purchase call when a user completes a purchase, and optionally post cart data each time a user adds an item to their shopping cart, enabling abandoned-cart reminder emails.

  • Completed purchases reduce the inventory level of the purchased items in your Content Library.
  • Completed purchase data is attached to the user profile. You can also associate the purchase with an email campaign if you pass the bid (blast ID) parameter.
  • Purchases cannot be edited once they are posted.
  • A user’s first_purchase_time will match the date you set on their earliest purchase.
  • You can also use the Purchase API to retrieve purchase data for the past year. To export earlier Purchase data, use the Purchase Log in My Sailthru.
  • If you need to backfill historical purchase data, use the purchase_import call of the job API, instead.

To get started, use the API Client Library for your preferred language, or learn how to make Sailthru API calls with curl on the API Technical Details page. When using either method, or the API Test tool, you can use this page as a reference for building calls and interpreting responses.


Endpoint URL: https://api.sailthru.com/purchase


GET a purchase

You can retrieve data on a purchase by that purchase’s sid – a unique Sailthru-provided identifier for the purchase – or your own external system ID that you may choose to store with each purchase as its extid.

By Sailthru sid

Example Call:
{
    "purchase_id":"abcd1234",
    "purchase_key":"sid"
}

By External extid

Example Call:
{
    "purchase_id":"abcd1234",
    "purchase_key":"extid"
}

Response

Example Response:
{
    "items": 
        [
            {
                "qty":1,
                "title":"Item 1",
                "price":1,
                "id":1234
                "url":"https://example.com/1234/Item_1"
                "tags": 
                    [
                        "water",
                        "bottle"
                    ],
                "vars": 
                    {
                        "var_a":2,
                        "var_b":"variable b"
                    }
             }
        ],
    "time":"Fri, Sep 5 2014, 12:33 am EDT",
    "tenders":
        [
            {
                "price":895
                "title":"GP"
            }
        ],
    "message_id":"23432.231",
    "email":"user@example.com",
    "purchase_keys":
        {
            "sid":"54f787c2975910e24cb478b1"
        },
    "adjustments":
        [
            {
                "price":-5, 
                "title":"Bottle Sale"
            }
        ],
    "send_template":"purchase-receipt"
    "vars":
        {
            "promo":"spring track",
            "referrer":"Facebook"
        }
}
The entire purchase object is returned. Note that vars can exist at the item and/or purchase level, depending on what you submit. In this case, both kinds are included.

Required Parameters for GET

Parameter Description
purchase_id The unique id of the purchase. If a purchase_id is not passed, the system requires an extid.
Note: Purchases older than one year cannot be viewed via the purchase API. To export this purchase data, use the Purchase Log to export all data for the desired date.
purchase_key The key type for the purchase_id. There are two types: sid and extid. The default value is sid. However, a client can provide a custom extid. If an extid is not performed, the system defaults to sid. purchase_key must be used with the purchase_id parameter.

Response Parameters

Parameter Description
items A list of items purchased by the user
price Price paid for the purchase
qty Number of items purchased
time Time the purchase occurred
purchase_keys Returns a sid or extid key type for purchase_key. sid is the default key type, while extid is client-specified.
adjustments Discounts applied to the purchase
tenders Method(s) of payment used for purchase
message_id Identifies email campaign for purchase source attribution in Sailthru
send_template Template to send for purchase confirmation
email Template to send for purchase confirmation

 

POST a purchase

Submit updated cart contents or a completed purchase.

  • Example call to submit a completed purchase with the minimum required parameters.

    {
        "email":"user@example.com",
        "items":
            [
                {
                    "qty":2,
                    "title":"Water Bottle",
                    "price":1099,
                    "id":1234,
                    "url":"https://example.com/1234/water_bottle"
                }
            ]
    }
    Example Response
    {
        "purchase" : {
            "_id" : "584890ac83ba882e008b456b",
            "items" : [
                {
                    "qty" : 2,
                    "title" : "Water Bottle",
                    "price" : 1099,
                    "id" : 1234,
                    "url" : "https://example.com/1234/water_bottle"
                }
            ],
            "price" : 2198,
            "qty" : 2,
            "time" : "Wed, 07 Dec 2016 17:43:56 -0500",
            "unique_id" : "584890ac83ba882e008b456b",
            "channel" : "online"
        }
    }
  • Example call for updating Sailthru with the user’s current cart items, specifying optional abandoned-cart reminder parameters.

    {
        "email":"user@example.com",
        "items":
            [
                {
                    "qty":2,
                    "title":"Water Bottle",
                    "price":1099,
                    "id":1234,
                    "url":"https://example.com/1234/water_bottle"
                }
            ]
        "incomplete":1,
        "reminder_template":"Abandoned",
        "reminder_time":"+45 minutes"    
    }
    Example Response
    {
        "purchase" : {
            "_id" : "584890ac83ba882e008b456b",
            "items" : [
                {
                    "qty" : 2,
                    "title" : "Water Bottle",
                    "price" : 1099,
                    "id" : 1234,
                    "url" : "https://example.com/1234/water_bottle"
                }
            ],
            "price" : 2198,
            "qty" : 2,
            "time" : "Wed, 07 Dec 2016 17:43:56 -0500",
            "unique_id" : "584890ac83ba882e008b456b",
            "channel" : "online"
            "reminder_template":"Abandoned",
            "reminder_time" : "Thu, 08 Dec 2016 17:21:23 -0500",
        }
    }
  • Example Call:

    {
        "email":"sample@sample.com",
        "items":
            [
                {
                    "qty":2,
                    "title":"Water Bottle",
                    "price":1099,
                    "id":1234,
                    "url":"https://example.com/1234/water_bottle"
                    "vars":
                    {
                        "color":"blue",
                        "material":"stainless steel"
                    }
                }
            ],
            "Message_id":"23432.231",
            "adjustments":
            [
                {
                    "price":-1000,
                    "title":"Sale"
                }    
            ],
           "date":"2014-02-14 9:30:00 America/New_York",
           "incomplete":0,
           "reminder_template":"abandoned-shopping-cart",
           "reminder_time":"+3 hours",
           "send_template":"purchase_receipt",
           "tenders":
            [
                {
                    "price":"1099",
                    "title":"Amex"
                }
            ],
            "channel":"app",
            "app_id":"ABCDE12345.com.company.appname",
            "cookies": {
                "sailthru_pc": "003f54695cfdcf42189a680a030aa4d45d9c230940-1ba3-11e6-860e-0242ac1300080000000000000000000000009c230940-1ba3-11e6-860e-0242ac1300089c230940-1ba3-11e6-860e-0242ac1300080000"
            },
            "device_id":"2b6f0cc904d137be2e1730235f5664094b831186",
            "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.93 Safari/537.36",
            "purchase_keys": {
                "extid":"123"
            },
           "vars":
            {
                "shipping_details":
                {
                    "ship_name":"Douglas Crockford","addr_1":"730 N Franklin St","addr_2":"#700",
                    "city":"Chicago", "state":"IL", "zip":"60654"    
                },
                "estimated_delivery":"January 7, 2017"
            }
    }
    Example Response
    {
        "purchase" : {
            "_id" : "5849b2b383ba8833008b4567",
            "items" : [
                {
                    "qty" : 2,
                    "title" : "Water Bottle",
                    "price" : 1099,
                    "id" : 1234,
                    "url" : "https://example.com/1234/water_bottle"
                    "vars":
                    {
                        "color":"blue",
                        "material":"stainless steel"
                    }
                }
            ],
            "price" : 1198,
            "qty" : 2,
            "time" : "Fri, 14 Feb 2014 09:30:00 -0500",
            "adjustments" : [
                {
                    "price" : -1000,
                    "title" : "Sale"
                }
            ],
            "tenders" : [
                {
                    "price" : "1099",
                    "title" : "Amex"
                }
            ],
            "vars" : {
                "shipping_details":
                {
                    "ship_name":"Douglas Crockford","addr_1":"730 N Franklin St","addr_2":"#700",
                    "city":"Chicago", "state":"IL", "zip":"60654"    
                },
                "estimated_delivery":"January 7, 2017"
            }
            "channel" : "app",
            "user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/27.0.1453.93 Safari/537.36",
            "browser" : "Chrome",
            "app_id" : "ABCDE12345.com.company.appname",
            "device_id" : "2b6f0cc904d137be2e1730235f5664094b831186",
            "purchase_keys" : {
                "extid" : "123"
            }
        },
        "reminder_time" : "Thu, 08 Dec 2016 17:21:23 -0500",
        "reminder_template" : "abandoned-shopping-cart",
        "optout" : null
    }

    The entire purchase object is returned.

Parameters for POST

Type Parameter Description
Required email Purchasing customer’s email
Required items An array containing each item in the user’s cart, with each item being a hashed set of data. For eachRequired:

  • qty – Quantity of the item purchased
  • title – Short user-readable name/title of the item purchased
  • price – Price of one item, in cents (so if the user purchases two items that cost $10.99 each for a total of $21.98, the value of this field should be 1099)
  • id – Your unique identifier (for example, SKU) for the item
  • url – The URL of the item. Note: The domain and scheme are case sensitive but paths are not. For example, if the stored URL is https://sailthru.com/Product, then Https://Sailthru.com/product would fail to match the product, but https://sailthru.com/product would.

Optional:

  • tags – A list of tags applicable to the product
  • vars – Any number of custom variables to attach to each item for later retrieval. For example, you may want to specify item attributes such as color, size, material, or an item-specific coupon code that was used.
    Note: These may be referred to as “item vars”, while the order itself also accepts a vars object, intended for order-specific data, not item-specific data.
Optional message_id Required to have revenue data matched to campaigns in Sailthru. Pass the identifying message_id of the email campaign the user is coming from (this will be stored in the sailthru_bid cookie on your domain). Note: In some client libraries message_id should be passed as a string.
Optional adjustments An array of the amount that an item has been discounted. Title and price (in cents) are required. The amount should be negative to factor in a deduction to the final price. For example, -1000 on an item originally priced at $25 would reduce the price and pass $15 to the user’s profile under the price field for that item. Recommended keys:

  • tax – Taxes applied to order
  • shipping – Any shipping and/or handling fees applied to order
  • discount – Discount off order from promotion code, coupon, etc.
  • gift_card – Amount of order covered by gift card payment
  • gift_wrap – Additional fee for gift wrapping.
  • credits – Amount of order covered by account credit
  • tip – Any gratuity added to purchase

If you are using Retention Analytics, these keys or similar custom keys are highly recommended.

Optional incomplete Set to 1 if the purchase is not complete (i.e. the user still has the items in the “shopping cart”), but has not completed the transaction
Optional date The date/time of the purchase (defaults to now). Usually only useful for backfilling old data
Optional reminder_template The template to send to the user if they have abandoned their incomplete purchase
Conditionally
Required
reminder_time The time to send the abandonment-reminder email.
Required if reminder_template is being passed.
Optional send_template Send a transactional email such as a receipt or order confirmation, even if the user is opted out
Optional tenders Array of the payment method and price (in cents)
Optional channel Identifies where the purchase took place. Values can be app, online (passed by default if channel is not set, or left blank), or offline.
Note: When channel is used, the additional top-level parameter app_id may be used.
Optional app_id Available when channel is set to app. The Apple Id provided to the client by Apple when app is registered with the Apple store.
Optional cookies Used to submit user cookie values along with the purchase. For example, to ensure attribution for purchased products shown in Site Personalization Manager sections by including the optional sailthru_pc value as the value of the cookie named sailthru_pc.
Optional sailthru_pc The value of the sailthru_pc cookie created by Site Personalization Manager. If Site Personalization Manager is enabled anywhere on your site, submit this cookie value with every purchase to ensure purchased products displayed using Site Personalization Manager are properly attributed to their section(s).
Optional device_id Available when channel is set to app. This is a unique device identifier (UDID).
Optional user_agent The user agent string of the user making the purchase
Optional purchase_keys Defines an extid key type for purchase_key. If an extid is not set, the system defaults to sid.
Note the differences between  purchase_key and purchase_keys:In POST mode, purchase_keys sets keys.
In GET mode, purchase_key retrieves keys.
In returned data, the system outputs purchase_keys.
Optional vars Any number of custom variables to attach to the order. These are commonly used with the Audience Builder “Purchase Order Var Is” query.

For example, you could specify the shipping address, estimated delivery date given, credit card type used, whether a deal was used, the promo code used, etc.

Note that a vars object may also exist at the item level. See the example code, and the items definition in this table.

You may use any custom order variable name(s). Note that the following variable name is reserved at the order level, for a particular purpose:

  • st_cost – The client’s cost for the items in the purchase, in cents. The value should be an integer, and is recommended if you are using Retention Analytics in order to report net revenue.

Related Topics

Error Codes

GET

HTTP Response Error Code Error Message Notes
400 99 Missing required parameter: purchase_id
400 99 Missing required parameter: purchase_key
400 99 Please use sid or extid for purchase_key value Value should be “sid” or “extid”
400 99 Error sid/extid not found in database
400 99 The purchase with [purchas_key] [id] does not exist or is older than one year. Purchases older than one year cannot be accessed via this API call. Please use the Purchase Log export in my.sailthru.com.

POST

HTTP Response Error Code Error Message Notes
400 99 Purchase id object was improperly formatted, please verify syntax Occurs when purchase_keys is submitted as a string rather than an array.
400 99 Cookies sailthru pc was improperly formatted, please verify syntax “Cookies” value sent as string rather than {“cookieName”:”cookieValue”} object.
400 99 Duplicate extid: [extid] ID already exists. Must be unique, and existing purchases cannot be modified.
400 99 Cannot submit an incomplete purchase with extid set  
400 99 Inconsistent unique_id(X) and extid(Y) are specified. Please use only extid.  
403 99 Invalid channel Specified device_id exists, but channel is set to something other than “app”, ”offline” or “online”
200 99 Invalid app_id. Must be a string  
200 99 Invalid app_id  
403 99 To pass the app_id parameter please set ‘channel’ to ‘app’ app_id passed but channel is not app.
403 99 To pass the device_id parameter please set ‘channel’ to ‘app’ device_id passed but channel is not app.
400 99 The tenders must be an array  
400 99 Missing field: price  
400 99 Missing field: title  
403 99 user_agent must be a string  
400 99 The adjustments must be an array  
400 2 Missing required parameter: items  
400 99 No items in purchase Empty items array
400 99 Missing field: qty  
400 99 Missing field: title  
400 99 Missing field: url  
400 99 Missing field: price  
400 99 SKU is not string  
400 99 Invalid SKU SKU exceeds 1000-character max
Top