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

TypeParameterDescription
Required, if user_id isn't usedemailPurchasing customer's email.
Optionaluser_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 useduser_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).

RequireditemsAn 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.
Optionalmessage_idmessage_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.
OptionaladjustmentsAn 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.
OptionalincompleteSet 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.
OptionaldateThe date/time of the purchase (defaults to now). Usually only useful for backfilling old data.
Optionalreminder_templateThe 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 Requiredreminder_timeThe time to send the abandonment-reminder email. Required if reminder_template is being passed. Note: The reminder_time parameter has been deprecated.
Optionalsend_templateSend a transactional email such as a receipt or order confirmation, even if the user is opted out.
OptionaltendersArray of the payment method and price (in cents). The array must include title and price parameters. See the All Optional Parameters example. 
OptionalchannelIdentifies 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.
Optionalapp_idAvailable 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.
OptionalcookiesUsed 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.
Optionalsailthru_pcThe 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).
Optionaldevice_idAvailable when channel is set to app. This is a unique device identifier (UDID).
Optionaluser_agentThe user agent string of the user making the purchase.
Optionalpurchase_keysDefines 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.
OptionalvarsAny 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.

 Related Topics

Error Codes

GET
HTTP ResponseError CodeError MessageNotes
40099Missing required parameter: purchase_id
40099Missing required parameter: purchase_key
40099Please use sid or extid for purchase_key valueValue should be "sid" or "extid"
40099Errorsid/extid not found in database
40099The 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 ResponseError CodeError MessageNotes
40099Purchase id object was improperly formatted, please verify syntaxOccurs when purchase_keys is submitted as a string rather than an array.
40099Cookies sailthru pc was improperly formatted, please verify syntax"Cookies" value sent as string rather than {"cookieName":"cookieValue"} object.
40099Duplicate extid: [extid]ID already exists. Must be unique, and existing purchases cannot be modified.
40099Cannot submit an incomplete purchase with extid set
40099Inconsistent unique_id(X) and extid(Y) are specified. Please use only extid.
40399Invalid channelSpecified device_id exists, but channel is set to something other than "app", "offline" or "online"
20099Invalid app_id. Must be a string
20099Invalid app_id
40399To pass the app_id parameter please set 'channel' to 'app'app_id passed but channel is not app.
40399To pass the device_id parameter please set 'channel' to 'app'device_id passed but channel is not app.
40099The tenders must be an array
40399user_agent must be a string
40099The adjustments must be an array
4002Missing required parameter: items
40099No items in purchaseEmpty items array
40099Missing field: qty
40099Missing field: title
40099Missing field: url
40099Missing field: price
40099SKU is not string
40099Invalid SKUSKU exceeds 1000-character max
40099Invalid JSON provided