Order Life Cycle on
All Platforms

Order Life Cycle

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.