Home

purchase

Overview

Record that a user has made a purchase, or has added items to their purchase total. You should call this when a user adds an item to their shopping cart (if you want to send abandoned-shopping-cart emails) with the incomplete parameter. Otherwise, you should call this whenever a user completes final purchase.

Please also see Abandoned Shopping Cart emails, Clearing Incomplete Purchase Data and Force Send Receipts.

Note: In order to display revenue data for your campaigns, you must pass the originating message_id as part of the Purchase call.

Base URL

https://api.sailthru.com/purchase

POST Mode

Required Parameters
Parameter Description Example
email The email address of the user making the purchase example@example.com
items An array of a hash (the items) in the user's shopping cart, see details below. [{"qty":2,"title":"High-Impact Water Bottle","price": 1099, "id":234,"url":"http://example.com/234/high-impact-water-bottle"}]
Required for Revenue Data
Parameter Description Example
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). 23423.231
Optional Parameters
Parameter Description Example
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.  "adjustments" : [{"price" : -1000, "title" : "Sale"}}],
incomplete Set to 1 if the purchase is not complete – the user still has the items in the "shopping cart", but has not completed the transaction 1
date The date/time of the purchase (defaults to now). Usually only useful for backfilling old data 2010-02-14 9:30:00 America/New_York
reminder_template The template to send to the user if they have abandoned their incomplete purchase abandoned-shopping-cart
reminder_time The time to send the abandonment-reminder email +3 hours
send_template Send a transactional email such as a receipt or order confirmation, even if the user is opted out. Read more here. "send_template" : "purchase receipt"
tenders Array of the payment method and price (in cents) "tenders" : [{ "price" : "1099","title":"Amex"}]
Important Note

When a subscriber opens and clicks an email link, a cookie called sailthru_bidis set in their browser. (Note that you will need to set up a CNAME for link rewriting and add this to the Link Domain setting in your account.) You will then need to pass this cookie as message_idwhen making the purchasecall to Sailthru api. Pass the cookie from wherever the cookies for your site are stored in the browser.

Please be sure that you pass sailthru_bid exactly as it appears in the cookie otherwise your campaign purchase metrics will not read the cookie properly. 

 

items: Required Fields

Each item in the shopping cart must include the following fields:

Field Description Example
qty Quantity of the item purchased 2
title Short user-readable name/title of the item purchased High-Impact Water Bottle
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) 1099
id Your unique identifier (for example, SKU) for the item 234
url The URL of the item http://example.com/234/high-impact-water-bottle
items: Optional Fields

Each item in the shopping cart may also include the following fields:

Field Description Example
tags A list of tags applicable to the product bottle, water-bottle, sports, promotional, loss-leader
vars Any number of user-defined variables to attach to the product for later retrieval. Note that you can use this parameter to pass an image. "vars":{"image_url":"http://assets/image3.jpg"}

 

Please also see: 

Examples

Purchase

In PHP (using Sailthru PHP5 Client), you can make a request such as:

$email = 'praj@sailthru.com';
$message_id = '23423.231';
$items = array(
    array('id' => 11, 'price' => 26262, 'qty' => '11', 'url' => 'http://example.com/234/high-impact-water-bottle', 'title' => 'High-Impact Water Bottle'),
    array('id' => 171, 'price' => 262, 'qty' => '18', 'url' => 'http://xyz.com/abc', 'title' => 'some title2')
);
$response = $sailthruClient->purchase($email, $items, null, $message_id,);

Similarly, in Python (using Sailthru Python Client):

items = [{'id':'123', 'title':'Product Title', 'price':1099, 'qty':1, 'url':'http://example.com/123/product-title'}, {'id':'123555', 'title':'XYZ product', 'price':699, 'qty':12, 'url':'http://example.com/xyz'}]
response = sailthru_client.purchase('joe@mydomain.com', items)

Incomplete Purchase (in JSON)

{"email":"joe@mydomain.com","items":[{"qty":1,"title":"Hair Gel","price":1099,"id":"A123","url":"http://www.mydomain.com/product/hair-gel","vars":{"image_url":"http://assets.mydomain.com/image3.jpg"}}],"incomplete":1,"reminder_template":"Abandoned","reminder_time":"+45 minutes"}
Return Value

Will return a data structure for the product containing all of the fields above.