purchase

Record the items included in a user's purchase or 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 purchase and incomplete (current abandoned cart) data is stored on the user's profile and accessible in Zephyr, Audience Builder, and Lifecycle Optimizer.
If a purchased item's URL does not yet exist in your Content Library, it is added to the Content Library along with all provided metadata (similar to a Content API call); if the URL does exist, none of the item's metadata in your Content Library is affected, except the inventory level, if previously supplied via the Content API; in that case, the inventory it is decremented by the purchased quantity.
Note: The item's SKU will be added to the user's purchase tab on the User Profile if the item does not exist in the Content Library. The SKU will not be added to the Content Library
You can associate the purchase with an email campaign if you pass the message_id parameter with the value contained in the sailthru_bid cookie which is set when a user visits your site from a link in an email. message_id is required to associate a purchase with an email campaign.
Purchases cannot be edited once they are posted, however, it is recommended that you also use the return endpoint to record all returns/refunds and keep revenue attribution up to date.
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.
If you need to backfill historical purchase data, use the purchase_import call of the job API, instead.

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

GET a purchase

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

By sid

Example Call:

Copy

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

By External extid

Example Call:

Copy

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

Response

Example Response:

Copy

{
    "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": 5050,
                "title": "tax"            },
            {
                "price": -1000,
                "title": "discount"            },
            {
                "price": 1000,
                "title": "shipping"            }
        ],
    "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 for purchase source attribution
`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.

Minimum Purchase Parameters

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

Copy

{
    "email":"user@example.com",
    "items":
        [
            {
                "qty":2,
                "title":"Water Bottle",
                "price":1099,
                "id":1234,
                "url":"https://example.com/1234/water_bottle"            }
        ]
}

Example Response

Copy

{
    "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"    }
}

Minimum Cart-Update Parameters

Example call for updating with the user's current cart items, specifying optional abandoned-cart reminder parameters.

Copy

{
    "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"    
}

The reminder_template and reminder_time parameters have been deprecated. Use a Lifecycle Optimizer flow to handle abandoned cart messaging.

Example Response

Copy

{
    "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",
    }
}

All Optional Parameters

Example Call:

Copy

{
    "email":"steve@example.com",
    "items":
        [
            {
                "qty":2,
                "title":"Water Bottle",
                "price":1099,
                "id":1234,
                "url":"https://example.com/1234/water_bottle",
                "images": {
                    "full": {
                        "url": "http://example.com/images/product_full.jpg"                },
                    "thumb": {
                        "url": "http://example.com/images/product_thumb.jpg"                    }
                },
                "tags":
                    ["type-bottle",
                    "price-10-15",
                    "size-medium",
                    "color-blue"],
                "vars":
                {
                    "color":"blue",
                    "material":"stainless steel"                }
            }
        ],
        "message_id":"23432.231",
        "adjustments":
        [
                {
                "price": 5050,
                "title": "tax"            },
            {
                "price": -1000,
                "title": "discount"            },
            {
                "price": 1000,
                "title": "shipping"            }  
        ],
       "date":"2014-02-14",
       "incomplete":0,
       "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

Copy

{
    "purchase" : {
        "_id" : "5849b2b383ba8833008b4567",
        "items" : [
            {
                "qty" : 2,
                "title" : "Water Bottle",
                "price" : 1099,
                "id" : 1234,
                "url" : "https://example.com/1234/water_bottle",
                "images": {
                    "full": {
                        "url": "http://example.com/images/product_full.jpg"                },
                    "thumb": {
                        "url": "http://example.com/images/product_thumb.jpg"                    }
                },
                "tags":
                    ["type-bottle",
                    "price-10-15",
                    "size-medium",
                    "color-blue"],
                "vars":
                {
                    "color":"blue",
                    "material":"stainless steel"                }
            }
        ],
        "price" : 1198,
        "qty" : 2,
        "time" : "Fri, 14 Feb 2014 09:30:00 -0500",
        "adjustments" : [
                {
                "price": 5050,
                "title": "tax"            },
            {
                "price": -1000,
                "title": "discount"            },
            {
                "price": 1000,
                "title": "shipping"            }
        ],
        "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, if `user_id` isn't used	`email`	Purchasing customer's email.
Optional	`user_key`	The key type of the 'user_id' value used to identify the user. The default is email. Specify one of the following: sid - The default, system-specified identifier for a user's profile extid - A unique, user-specified identifier for a user's profile (only available if you enable extid lookup) email - The user's email address sms - The user's SMS number (only available if you enable SMS) fb - The user's Facebook ID (only available if you enable Facebook lookup) twitter - The user's Twitter ID (only available if you enable Twitter lookup)
Required, if `email` isn't used	`user_id`	Object to set some or all of the user keys. A hash of key names and values. If `user_key` was not provided and a `user_id` was provided it will return sid (Sailthru ID).
Required	`items`	An array containing each item in the user's cart, with each item being a hashed set of data.In most cases, each item URL already exists in your Content Library. In that case, the quantity (qty) will be used to update the item's inventory, but no other metadata will be added to (or updated for) the item in the Content Library. It will only exist on the stored purchase on the user's profile.If the item URL does not yet exist in the Content Library, the item is added. For each item: Required: `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 fields and values to attach to each item for later retrieval in templates or use in Audience Builder or Lifecycle Optimizer. For example, you may want to specify item attributes such as color, size, material, or an item-specific coupon code that was used.Notes These may be referred to as "item vars" or "custom item fields", while the order itself also accepts a vars object, intended for custom data applicable to the entire order. If you wish to leverage your item SKU in a Lifecycle Optimizer flow, you must pass it as a var. `images` - A map of image types full and/or thumb to objects specifying the URL for each image. Use the name "full" to denote the full-sized image, and "thumb" to denote the thumbnail-sized image. For example, the value of images might be: {"full" : { "url" : "http://example.com/f.jpg" }, "thumb" : { "url" : "http://example.com/t.jpg" } } This allows you to easily include product images when messaging users with order confirmations and abandoned-cart reminders.
Optional	`message_id`	`message_id` is required to have revenue data matched to email sends. Pass the identifying `message_id` of the email the user is coming from; this will be the value stored in the `sailthru_bid` cookie for your domain. Note: In some client libraries `message_id` should be passed as a string. The message attribution will be displayed in your Campaign Summary, Transactional Report, Purchase Log, and in Lifecycle Optimizer Metrics.
Optional	`adjustments`	An array of the adjustments (positive or negative) that should be applied to the total order value. Title and price (in cents) are required. The amount should be negative to factor in a deduction to the final price, such as a discount; the amount should be positive to factor in an additional cost, such as shipping. 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 Business Intelligence, 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. Note: The `reminder_template` parameter has been deprecated. We recommend that you use a Lifecycle Optimizer flow to handle abandoned cart messaging.
Conditionally Required	`reminder_time`	The time to send the abandonment-reminder email. Required if `reminder_template` is being passed. Note: The `reminder_time` parameter has been deprecated.
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). The array must include `title` and `price` parameters. See the All Optional Parameters example.
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 `app_id` is the id assigned to a mobile app within the mobile platform. This can be found in the URL of the browser when viewing a specific app.
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 Business Intelligence in order to report net revenue.

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
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
400	99	Invalid JSON provided

purchase

GET a purchase

By sid

By External extid

Response

Required Parameters for GET

Response Parameters

POST a purchase

Minimum Purchase Parameters

Minimum Cart-Update Parameters

All Optional Parameters

Parameters for POST

Related Topics

Error Codes