Purchase object

This article explains the different components of a purchase object, how to use it correctly, best practices, and examples to draw from.

What is a purchase object?

A purchase object is an object that gets passed through the API when a purchase has been made. Each purchase object is located within a purchase array, with each object being a single purchase by a particular user at a particular time. The purchase object has many different fields that allow Braze’s backend to store and use this information for customization, data collection, and personalization.

Object body

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  // One of "external_id" or "user_alias" or "braze_id" is required.
  "external_id" : (optional, string) External User ID,
  "user_alias" : (optional, User Alias Object), User Alias,
  "braze_id" : (optional, string) Braze User Identifier,
  "app_id" : (optional, string) see App Identifier,
  // See the following product_id naming conventions for clarification.
  "product_id" : (required, string), identifier for the purchase, e.g., Product Name or Product Category,
  "currency" : (required, string) ISO 4217 Alphabetic Currency Code,
  //Revenue from a purchase object is calculated as the product of quantity and price.
  "price" : (required, float) value in the base currency unit (e.g., Dollars for USD, Yen for JPY),
  "quantity" : (optional, integer) the quantity purchased (defaults to 1, must be <= 100 -- currently, Braze treats a quantity _X_ as _X_ separate purchases with quantity 1),
  "time" : (required, datetime as string in ISO 8601), Time of purchase,
  // See the following purchase object explanation for clarification.
  "properties" : (optional, Properties Object) properties of the event,
  // Setting this flag to true will put the API in "Update Only" mode.
  // When using a "user_alias", "Update Only" mode is always true.
  "_update_existing_only" : (optional, boolean)
}

• External User ID
• App identifier
• ISO 4217 Currency Code Wiki
• ISO 8601 Time Code Wiki

Purchase product_id

Within the purchase object, The product_id is an identifier for the purchase (e.g, Product Name or Product Category):

• Braze allows you to store a max of 5000 product_ids in the dashboard.
• product_id max is 255 characters

Product ID naming conventions

At Braze, we offer some general naming conventions for the purchase object product_id. When choosing product_id, Braze suggests using simplistic names such as the product name or product category (instead of SKUs) with the intention of grouping all logged items by this product_id.

This helps make products easy to identify for segmentation and triggering.

Log purchases at the order level

If you would like to log purchases at the order level instead of the product level, you can use order name or order category as the product_id (e.g., Online Order or Completed Order).

For example, to log purchases at the order level in the Web SDK:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
POST https://YOUR_REST_API_URL/users/track
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "purchases" : [
    {
      "external_id" : "user1",
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "Completed Order",
      "currency" : "USD",
      "price" : 219.98,
      "time" : "2013-07-16T19:20:30+01:00",
      "properties" : {
        "products" : [ { "name": "Monitor", "category": "Gaming", "product_amount": 19.99, },
        { "name": "Gaming Keyboard", "category": "Gaming ", "product_amount": 199.99, }
        ]
      }
    }
  ]
}

Purchase properties object

Custom events and purchases may have event properties. The “properties” values should be an object where the keys are the property names and the values are the property values. Property names must be non-empty strings less than or equal to 255 characters, with no leading dollar signs.

Property values can be any of the following data types:

Event property objects that contain array or object values can have an event property payload of up to 50 KB.

Purchase properties

Purchase properties can be used to trigger messages and for personalization using Liquid, also allowing you to segment based on these properties.

Purchase property naming conventions

It is important to note that this feature is enabled per product, not per purchase. For example, if a customer has a high volume of distinct products, but each has the same properties, segmenting becomes rather meaningless,

In this instance, this is why when setting the data structures, we recommend using product names at a “group-level” instead of something granular. For example, a train ticket company should have products for “single trip”, “return trip”, “multi-city”, and not specific transactions such as “transaction 123”, “transaction 046”, etc. Or for example, with the purchase event ‘food’, properties would be best set as “cake” and “sandwich”.

Example purchase object

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
POST https://YOUR_REST_API_URL/users/track
Content-Type: application/json
Authorization: Bearer YOUR-REST-API-KEY
{
  "purchases" : [
    {
      "external_id" : "user1",
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "backpack",
      "currency" : "USD",
      "price" : 40.00,
      "time" : "2013-07-16T19:20:30+01:00",
      "properties" : {
        "color" : "red",
        "monogram" : "ABC",
        "checkout_duration" : 180,
        "size" : "Large",
        "brand" : "Backpack Locker"
      }
    },
    {
      "external_id" : "user1",
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "pencil",
      "currency" : "USD",
      "price" : 2.00,
      "time" : "2013-07-17T19:20:20+01:00",
      "properties" : {
        "number" : 2,
        "sharpened" : true
      }
    },
    {
      "user_alias" : { "alias_name" : "device123", "alias_label" : "my_device_identifier"},
      "app_id" : "11ae5b4b-2445-4440-a04f-bf537764c9ad",
      "product_id" : "pen",
      "currency" : "USD",
      "price" : 2.50,
      "time" : "2013-07-17T19:20:20+01:00",
      "properties" : {
        "color" : "blue",
      }
    }
  ]
}

Purchase objects, event objects, and webhooks

Using the example provided, we can see that someone bought a backpack with the properties: color, monogram, checkout duration, size, and brand. While we cannot go into a campaign and segment the users based on these properties, we can use these properties strategically by using them in the form of a receipt, to send a custom message through a channel using Liquid. For example, “Hello Ann F., Thanks for purchasing that red, medium backpack for $40.00! Thanks for shopping at Backpack Locker!”

If you do want to save, store and track properties to segment with, you need to set them up as custom attributes. This can be done with the power of webhooks! Using webhooks, you can tell Braze to “listen” for whenever a purchase event happens and then set up the webhook so that it parses the properties and saves them as custom attributes. Now that these properties are custom attributes, we can see and segment these properties in the dashboard.

For information on how to set up this type of webhook, check out Braze to Braze webhooks.