API Call: purchase
- Overview
- Specification
  - Base URL
  - POST mode

API Call: 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.

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

Specification

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 the items in the user's shopping cart, as detailed below

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 normally be stored in the `sailthru_bid` cookie on your shared domain);	`23423.231`

Optional Parameters

Parameter	Description	Example
`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`

Important Note

Please be sure that you pass the sailthru bid_cookie 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 card 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

Implementation examples

In PHP (using Sailthru PHP5 Client), you can make a request like the following:

$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('praj@sailthru.com', items)

Return Value

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