Item Timers

Timers are an additional way to manage the payment life cycle. They can be useful when providing temporary access to your products and services like subscriptions or premium app features. Timers require the customerId property to be passed with the request. customerId values are generated on your side.

OmniCart remembers the relation between the customerId value and the item identifier and prevents buying an item with an active timer for the specified customer. A timer is considered active in the pending, started, and paused statuses (see Timer Life Cycle section below).

Timer Life Cycle

Timer statuses can be retrieved using the status request. These statuses are returned per item.

Timer Statuses (clickable)

pending

The pending status means that the current item has not entered a set timer trigger event. It is an active state, meaning that you cannot initiate another cart containing this item with the same customerId value.

From the pending state a timer can be started by a trigger event or manually (see the Starting a timer section above).

started

The started status that the countdown is on. The remaining time (in seconds) is the value of the remainingSecs property of the timerSnapshot object in the status response.

paused

The paused status means that a timer has been manually stopped with the modify request. It is an active state, meaning that you cannot initiate another cart containing this item with the same customerId value. From this state a timer can be manually unpaused or stopped.

stopped

A timer enters the stopped status after it has been manually stopped with the modify request. This is the end of a timer life cycle. From this status, the timer for the current item and customerId cannot be restarted . To start a new timer, initiate a new cart with the init request or enable a timer for an existing cart item with the modify request.

elapsed

A timer enters the stopped status when the number of seconds specified in the timer settings elapses. This is the end of a timer life cycle. From this status, the timer for the current item and customerId cannot be restarted . To start a new timer, initiate a new cart with the init request or enable a timer for an existing cart item with the modify request.

Enabling a Timer

By default, timers are disabled (not set). You can enable a timer at the beginning of the payment life cycle with the init request or at any other stage of the payment process using the modify request. By enabling a timer, you define its settings like starting conditions and the countdown value.

tip

With the modify request, you can disable any timer at any moment regardless of its current status.

Starting a Timer

A timer can be started by a trigger event or manually. Until started, an enabled timer stays in the pending state.

Trigger Events

A trigger event is an item payment status. For example, if you set authorized as a trigger event, the timer will start the countdown as soon as the item enters the authorized status. Any future, current, or past trigger event can be selected. Consider the following examples.

• You set a timer using the init request with the initiated status as the trigger event. The item timer countdown starts immediately after the request is processed with no errors.
• The current item status is captured and you set a timer using the modify request with the authorized status as the trigger event. The item timer countdown starts immediately after the request is processed with no errors as the authorized status is prior to the captured status.
• The item is not initiated or in any status prior to refunded. You set a timer using the init or modify request with the refunded status as the trigger event. The item timer countdown starts if the item enters the refunded state.

tip

It's up to you whether to use timers and how to utilize them. If we refer to the last example, you, for some reason, might want to prevent your customer from purchasing the item they asked to refund for a certain period of time (or forever, if the countdown value is set to 0).

Manual Start

An enabled timer can be started manually from the pending or paused state with the modify request. Note that you can start the timer manually prior to a previously set trigger event. On that event, the timer will continue the countdown. If a timer is manually started and elapses before a previously set trigger event, it is not restarted as the elapsed status is final in the timer life cycle.

Countdown

The timer works as a countdown, its value is specified in seconds. For example, to set a timer for 2 hours, pass 7200 as the timer value in the init or modify request. If you need to set a timer for 3 days, pass 259200 and so on.

tip

If you pass value 0, the timer is infinite. For example, you can utilize this for items that cannot be purchased more than once like unique artifacts in video games or one-time PRO upgrades. Later you can always change the timer settings with the modify request.

End of Timer Life Cycle

When a timer elapses or is stopped manually, it reaches the end of its life cycle and cannot be restarted. To set a new timer for an item, you need to initiate a new cart (or modify an existing one) with the customerId value and timer settings.

Countdown End

A timer's countdown ends when the number of seconds specified in the timer settings of the init or modify request elapses. If a timer is manually paused after it starts, the countdown freezes until manually unpaused. To unpause a timer, pass the start value of the manualAction property in the modify request.

note

A paused timer is still active. That means that you cannot initiate the current item with the same customerId value until the timer elapses or is stopped manually.

Manual Stop

A timer can be manually stopped from the paused or started state. To stop a timer, pass the stop value of the manualAction property in the modify request.

Please, note

You cannot restart a stopped timer for the current item. To start a new timer, initiate a new cart (or modify an existing one) with the customerId value and timer settings.