Line Items on
All Platforms

Line Items

Line item (line_items) level details are not required when reporting orders to Button but we highly encourage including these. Including line items minimizes errors that can occur when reporting orders to Button while also helping increase ROI you see from Publishers who integrate your inventory into their application. It allows them to customize push notifications, in-app placement, and email promotions for your products based on these qualifying values. We recommend including line items for two major reasons:

  1. Product/Event targeting
    • Including this data will allow Publishers to target specific products for events, promotions, etc. (e.g. "earn 2x cashback when purchasing chicken wings for the big game!")
    • Merchants that run item or brand level campaigns on Button see:
      • 3x greater daily revenue
      • 5x more user engagement
      • 5x more app opens
      • Repeat purchase rates higher than 40%
      • 50% increase in new user app installs
  2. Debugging and Customer Service
    • When a customer service request comes in, if Button has line item level data, we can provide direct support to the customers without having to escalate to you for further details (e.g. "you only received $2.00 cash-back because your order included a single pizza pie, and this is your reward earnings from that"). Without this detail, we may rely on escalations to your team to provide the details of an order.

In this guide, we'll over line items for:

Retail

Items in retail Merchant orders will typically have UPC and SKU codes. These should be passed in the optional attributes parameter within the optional line_items parameter when POSTing to Button's Order API. Here is a sample line_items array with attributes containing UPC and SKU codes.

{
  ...
    "line_items": [
        {
            "identifier": "sku-1234",
            "total": 4000,
            "amount": 2000,
            "quantity":2,
            "description": "Shovels",
            "attributes": {
                "category": "Home&Garden",
                "subcategory": "Tools",
                "brand": "Ames",
                "upc": "049206633742"
            }
        },{
            "identifier": "sku-4567",
            "total": 3000,
            "amount": 3000,
            "quantity":1,
            "description": "Rakes",
            "attributes": {
                "category": "Home&Garden",
                "subcategory": "Tools",
                "brand": "Ames",
                "upc": "049206633745"
            }
        }
    ]
  ...
}

Hospitality and Travel

Items in hospitality and travel orders will typically have the site the reservation was booked, how much the booking costs per night, the checkin and checkout dates, and the number of guests on the reservation. These should be passed in the optional attributes parameter within the optional line_items parameter when POSTing to Button's Order API. In addition, you should include the finalization_date (for more information on this, see this guide). Here is a sample line_items array with attributes containing these:

{
  ...
    "line_items": [
        {
            "identifier": "sku-7890",
            "total": 14941,
            "amount": 14941,
            "quantity":1,
            "description": "A Cool Motel",
            "finalization_date": "2017-08-02T19:26:08Z",
            "attributes": {
                "booking_type": "Website to book stuff",
                "nightly_cost": 16808,
                "checkin": "2017-03-23",
                "checkout": "2017-03-25",
                "guests": 2
            }
        }
    ]
  ...
}

Delivery

Items in retail Merchant orders will typically have a UPC code. These should be passed in the optional attributes parameter within the optional line_items parameter when POSTing to Button's Order API. Here is a sample line_items array with attributes containing the UPC code.

{
  ...
    "line_items": [
        {
            "identifier": "sku-2345",
            "total": 100,
            "amount": 100,
            "quantity":1,
            "description": "Orange Juice",
            "attributes":{
                "upc": "400000000003"
            }
        },{
            "identifier": "sku-6789",
            "total": 400,
            "amount": 200,
            "quantity":2,
            "description": "Milk",
            "attributes":{
                "upc": "400000000004"
            }
        }
    ]
  ...
}

Next Steps

The order life cycle dictates the finalization date (finalization_date) of orders. If you haven't already done so, you should continue reading about it.


Order Life Cycle

The finalization date (finalization_date) should only be used by merchants who offer products and services with finalization dates that vary from order to order. Hotel stays are a good example of this, as they are typically finalized at the end of a reservation, and vary from order to order. Read more to see if you should include these.

View Guide