Order Life Cycle on
All Platforms

Order Life Cycle

This guide reviews the order life cycle and how it applies to Button transactions and commissions. We'll go over:

Finalization Date

Each order that is reported to Button's Order API, by default, will be automatically assigned a finalization_date, which is the date and time when a particular order can no longer be modified or deleted (Note: Most merchants should not pass the optional finalization_date parameter when reporting orders to Button's Order API. For more information and to see if you should be passing this parameter, see here). The finalization date and time is automatically calculated by taking the date and time when the order is reported to Button's Order API and adding your account's default finalization window (i.e. the time allowable for an order to be modified or deleted). The value for your default finalization window was set when you were initially onboarded with Button and is immutable through the API and the Dashboard. To update this value, contact our integrations team.

It's important to note, after an order has passed its finalization_date, commissions can be generated against it. This means that Button will charge you to payout Publishers their appropriate commission. To avoid any incorrect charges, please make sure to update and cancel orders to Button that are changed on your API (for more information on how to do this, see this guide).

Default Finalization Date Example

An order is reported to Button's API on January 1st 2017 at 12pm EST (2017-01-01T17:00:00Z) and the account's default finalization window is one week. When the order is reported to Button's API, the state of the order will be

{
  ...
  "status": "open",
  "finalized_date": "2017-01-08T17:00:00Z",
  ...
}

Note that the finalization_date is January 8th, 2017 at 12pm EST, which is one week (i.e. the account's default finalization window) from when the order was reported. It is until this date and time that the order can be modified or deleted. Once this date and time has passed, Button will automatically update the state and it will be

{
  ...
  "status": "finalized",
  "finalized_date": "2017-01-08T17:00:00Z",
  ...
}

After this, this order can no longer be modified or deleted.

When to Use Custom Finalization Date

In some cases an order should be finalized at a custom time. This is specified by passing the optional parameter finalization_date when reporting an order to Button's API. This 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. If the finalization_date parameter is passed when reporting an order to Button's API, it will override the automatic assignment of it, as described in the above section.

Next Steps

Line item (line_items) level details are not required when reporting orders to Button but we highly encourage including these. If you haven't already done so, you should continue reading about it.


Line Items

Including line item (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.

View Guide