> For the complete documentation index, see [llms.txt](https://help.orderdesk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.orderdesk.com/guided-walkthroughs/orders-and-folders/how-to-work-with-timestamps.md).

# How to Work with Timestamps

If you want to take action on orders based on a time, you can apply timestamps to your orders and then set up custom events and rules to watch the timestamp and apply the actions when you want.

This guide covers how to set a timestamp on an order with a rule, how to create a custom event to regularly check the orders in a specific folder, and how to use a rule to apply actions at the appropriate time.

### Add Timestamp to Orders

**IMPORTANT**\
If you only need to know when a certain amount of time has passed since the order was created, use the **If Order Date Created** filter instead of setting a timestamp. Follow the instructions in the rest of this guide for how to search against the date created time.

To add a timestamp to your orders, click **Rule Builder** under the **Settings** menu in the left sidebar and select the **Order Rule** rule type.

![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FjalvhSLXHlkV3UqsIKaI%2Flegacy-26243dd8aeac6d420770.png?alt=media)

Choose the event you want your rule to run on. This event is when the timestamp will be applied, such as when the order is imported, when it moves into a certain folder or when the shipment is added.

![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FTDvPIcKOgSBl9V0HCUVe%2Flegacy-7c5d07d7dcc57b3f7163.png?alt=media)

Add any filters to the rule if you need to only apply the timestamp to certain orders.

Select one of the two timestamp actions as the action:

![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FZn3QmSSQcprmumEbyNcJ%2Flegacy-8dccd3467cb656d8e30f.png?alt=media)

**Set Order Metadata Local Timestamp** will apply the timestamp in your store’s local time, which is determined by your [Store Settings](https://app.orderdesk.com/settings/details).

**Set Order Metadata UTC Timestamp** will apply the timestamp in UTC time. If you are going to create a custom event to regularly check for timestamps, use UTC time. When custom events run, they look at UTC time and will apply to that time if different from the store’s timezone. If you notice that your custom events aren’t acting on orders at the right time, check that your rule is applying UTC timestamps rather than local timestamps.

After choosing your timestamp action, name your timestamp any custom name you want to call it:

![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FCX6bggkQxGOvBoWR6XmU%2Flegacy-6dc08743923b8362bd0c.png?alt=media)

When your rule runs, a timestamp will be added to the order metadata of any order the rule applies to:

![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2Fcyng1RBwn3DtdchbrH5j%2Flegacy-6e9964bcc39832a2b52f.png?alt=media)

### Create Custom Event

A custom event is an event that you create in your store to run on one specific folder. You can choose how often the event runs and which folder you want it to run on.

If you haven’t already created the folder you want your event to run on, do that [now](/start-here/getting-started-series/quick-start-overview.md#working-with-folders).

To create a custom event, follow the steps [in this guide](/guided-walkthroughs/rules-and-automations/how-to-use-custom-events.md), then come back to finish these steps.

A custom event by itself will not do anything to your orders, but the next step will be to create a rule that runs when the custom event looks at your folder, if all the filters in the rule apply.

### Apply Action to Orders

When creating a rule, the first step is to select the event you want the rule to run on. You’ll now find your custom event as one of the available events:

![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2F3zw3bUC3RSUx3UTiZ7Qi%2Flegacy-78c590e9c109a5b7e929.png?alt=media)

This rule requires a filter to check against the timestamp in the order, which will be found in the order metadata, so select **Order Metadata Field** as the filter type:

![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FKgf3qXF46HIQAxG33hKr%2Flegacy-bf2a52f804d548d57c9f.png?alt=media)

In the Field Name, add the name you gave to the timestamp. This must be an exact match:

![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FObEhDsEdCqxRuFnuzSnz%2Flegacy-df169ee10596da3aa128.png?alt=media)

Choose the *before time* operator and then add the amount of time you want to have passed, followed by a – sign:

![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FIghBkMtwA2Z9ZkgGSAQ5%2Flegacy-1b8d364d3df4f7f1897b.png?alt=media)

Examples:

**wait\_period** ***before time***** -5days** means to wait until 5 days or more *after* the time of the wait\_period timestamp.

**wait\_period** ***before time***** -10minutes** means to wait 10 minutes or more *after* the timestamp time for the filter to be true.

If the timestamp on an order is set right at 12:00:00, *before time -10minutes* will be true at 12:10:00, and the next time your custom event scans the folder, the rule will apply to the order.

To finish the rule, select any actions you want to have happen when the filter becomes true against the timestamp:

![](https://251457507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FAQOLMUJWMYtrpQ7Oxxca%2Fuploads%2FlRB4Lh3VQa13dZwhmtya%2Flegacy-befd5b3cdc478a8453ba.png?alt=media)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.orderdesk.com/guided-walkthroughs/orders-and-folders/how-to-work-with-timestamps.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.