Dates and Times

BGL has first-class support for dates and times. Date literals always start with @, and there are dedicated operators for arithmetic and period checks.

when
  order.ordered_at > 1D before @now
then
  set order.custom.is_recent to true
end

Reads as: when the order’s ordered_at time is more recent than 1 day before now, mark it as recent.

Date literals

Every date literal begins with @.

Form	Example	Meaning
Named	@now, @today, @tomorrow, @yesterday	Reference points
ISO timestamp	@2024-01-15T10:30:00+00:00	Specific moment
Date only	@2024-01-15	A specific day
Time only	@T10:30:00	A time of day
Weekday	@monday … @sunday	A day of the week
Month	@january … @december	A month
Year	@2024	A year

Durations

A duration is a length of time, written as a number followed by a unit:

Unit	Meaning
s	Seconds
m	Minutes
h	Hours
D	Days
W	Weeks
M	Months
Y	Years

Examples: 30s, 15m, 1h, 2D, 1W, 3M, 1Y.

Note the case: lowercase m is minutes, uppercase M is months.

Date arithmetic

To compute a date relative to another, use before or after:

1D after @now              # 24 hours from now
2h before order.ordered_at # 2 hours before the order time
1W after @today            # 1 week from today

The form is <duration> before|after <date> — duration first, then the keyword, then the reference date.

Heads up: @now + 1D doesn’t work. The arithmetic always uses the before/after keywords.

Comparing dates

Standard comparison operators work on dates the same way they do on numbers:

order.ordered_at < @now             # in the past
order.shipped_at > @yesterday       # since yesterday
order.requested_ship_date >= @today # today or later

For checking what day, month, or year a date falls in, use is_on and is_in:

order.ordered_at is_on @monday    # on a Monday
order.ordered_at is_on @2024-01-15 # on Jan 15, 2024
order.ordered_at is_in @december  # any time in December (any year)
order.ordered_at is_in @2024      # any time in 2024

is_on matches a specific day; is_in matches a range like a month or year.

Setting a date

set order.custom.scheduled_for to @tomorrow
set order.custom.deadline to 1W after @today
set order.custom.holiday_check to @2024-12-25

Holds based on dates

The hold action takes a date or a duration:

# Hold until a specific time
hold order until 1D before order.requested_ship_date

# Hold for a duration
hold order waiting 2h

# Hold until next Monday at 8am
hold order until @monday at @T08:00:00

Timezones

By default, dates are interpreted in UTC. To work in another timezone, set it as a rule option:

rule "Eastern hours"
  timezone "Eastern Time (US & Canada)"

  when
    order.ordered_at is_on @friday
    and order.ordered_at > @T17:00:00
  then
    hold order until @monday at @T08:00:00
  end
end

The timezone string follows the standard tz database names (like "America/New_York", "Eastern Time (US & Canada)", "UTC").

What’s not supported

BGL doesn’t have:

• Date-component extraction — there’s no year(date), month(date), or day(date). To check parts of a date, use period operators: is_on @monday, is_in @january, is_in @2024.
• Date subtraction returning a duration — you can’t write order.shipped_at - order.ordered_at to get the time between two dates.
• Custom date formats for parsing — when casting a string as date, the engine parses ISO formats and a few common variants. Non-standard formats won’t parse.

Common patterns

Recent orders:

when order.ordered_at > 1D before @now then ... end

Friday orders to ship Monday:

when
  order.ordered_at is_on @friday
  and order.shipping_carrier_service_level is "Standard"
then
  hold order until @monday at @T08:00:00
end

Holiday season tag:

when order.ordered_at is_in @december then
  set order.custom.tag to "holiday-season"
end

Schedule fulfillment 1 day before requested delivery:

hold order until 1D before order.requested_delivery_date