> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with dates

> Learn how to work with date fields in Layers, including formats, filtering by date ranges, sorting, and ingesting dates from tags and metafields.

Layers provides comprehensive support for working with date and time data across your product catalog. This guide covers date field formats, filtering by date ranges, sorting by dates, and how Layers automatically detects and handles dates from various sources.

## Date field formats

Layers uses different date formats depending on the source of the date data:

### ISO 8601 format (product and metafield dates)

Layers returns product date fields and metafield dates as ISO 8601 formatted strings. This standardized format includes full date, time, and timezone information.

**Core date fields:**

| Field          | Description                       | Example Value                   |
| :------------- | :-------------------------------- | :------------------------------ |
| `created_at`   | When the product was created      | `"2022-02-05T01:22:05.000000Z"` |
| `updated_at`   | When the product was last updated | `"2023-10-25T20:47:04.000000Z"` |
| `published_at` | When the product was published    | `"2022-02-05T01:22:05.000000Z"` |

**Variant date fields:**

| Field                 | Description                       | Example Value                   |
| :-------------------- | :-------------------------------- | :------------------------------ |
| `variants.created_at` | When the variant was created      | `"2022-02-05T01:22:05.000000Z"` |
| `variants.updated_at` | When the variant was last updated | `"2023-10-25T20:47:04.000000Z"` |

**Metafield dates:**

Layers also returns date and datetime metafields from Shopify in ISO 8601 format.

### Unix timestamps (named tag dates)

When you use the `date` type hint in named tags, Layers automatically converts the date to a Unix timestamp (seconds since epoch) for efficient filtering and sorting.

**Named tag format:**

```
{key}:date:{value}
```

**Example tags:**

* `ReleaseDate:date:2024-03-15`
* `AvailableUntil:date:2024-12-31`
* `RestockDate:date:2024-06-01T10:00:00Z`

**Resulting named\_tags object:**

Layers converts the dates to Unix timestamps and stores them as numeric values in the `named_tags` object.

## Filtering products by date ranges

Use the `filter_group` parameter in Search or Browse API requests to filter products by date ranges. For product date fields (`created_at`, `updated_at`, `published_at`) and metafield dates, use ISO 8601 formatted strings. For named tag dates, use Unix timestamps.

### Filtering by product date fields

Filter products created after a specific date using the `gt` operator with an ISO 8601 formatted date string.

Filter products published before a specific date using the `lt` operator with an ISO 8601 formatted date string.

### Date range filtering

Filter products within a date range using the `between` operator with two ISO 8601 formatted date strings.

### Available date operators

| Operator  | Description           | Example                               |
| :-------- | :-------------------- | :------------------------------------ |
| `eq`      | Equal to              | Products published on a specific date |
| `gt`      | Greater than          | Products created after a date         |
| `gte`     | Greater than or equal | Products updated on or after a date   |
| `lt`      | Less than             | Products published before a date      |
| `lte`     | Less than or equal    | Products created on or before a date  |
| `between` | Between two dates     | Products published in a date range    |

### Filtering by metafield dates

Metafield dates use ISO 8601 format. Use the appropriate comparison operator with an ISO 8601 formatted date string.

### Filtering by named tag dates

Layers stores named tag dates as Unix timestamps, so use numeric values when filtering.

### Complex date filters

You can combine multiple date conditions using the `AND` conditional to filter products that meet all date criteria.

You can also use the `OR` conditional to filter products that meet any of the specified date criteria.

## Sorting by date fields

You can use date fields in sort orders to arrange products chronologically. All date fields marked as sortable can be used in custom sort orders.

### Creating date-based sort orders

You can create custom sort orders in the Layers dashboard that use date fields:

**Sort by newest products first:**

Create a sort order with `created_at` in descending order to show the most recently created products first.

**Sort by recently updated:**

Create a sort order with `updated_at` in descending order to show products with the most recent changes.

**Sort by publication date:**

Create a sort order with `published_at` to arrange products by when they were made available to customers.

**Sort by named tag dates:**

Named tag dates (stored as Unix timestamps) can also be used in sort orders. For example, sort by `named_tags.ReleaseDate` to arrange products by their custom release date.

### Combining date sorting with other criteria

You can combine date-based sorting with other sort criteria in multi-level sort orders:

1. **Primary sort:** `published_at` (descending) - Newest products first
2. **Secondary sort:** `price_range.from` (ascending) - Lowest price first within each date group

This creates a "New Arrivals by Price" sort order.

## Automatic date detection and handling

Layers automatically detects and handles date values from multiple sources, using the appropriate format for each source.

### Date detection from named tags

Layers can automatically detect dates in named tags when you use the `date` type hint:

**Tag format:**

```
{key}:date:{value}
```

**Example tags:**

* `ReleaseDate:date:2024-03-15`
* `AvailableUntil:date:2024-12-31`
* `RestockDate:date:2024-06-01T10:00:00Z`

When Layers detects a `date` type hint, it automatically:

1. Parses the date value (supports ISO 8601 and other common formats)
2. Converts it to a Unix timestamp
3. Stores it in the `named_tags` object as a numeric value
4. Makes it available for filtering and sorting

**Resulting named\_tags object:**

Layers converts the dates to Unix timestamps and stores them as numeric values in the `named_tags` object.

**Filtering by named tag dates:**

Since named tag dates are stored as Unix timestamps, use numeric values in filters.

### Date detection from metafields

Layers automatically handles Shopify metafields with date types, returning them in ISO 8601 format:

**Supported date metafield types:**

* `date` - Date values formatted as YYYY-MM-DD
* `date_time` - DateTime values formatted as ISO 8601

The API returns metafield dates in ISO 8601 format.

**Filtering by metafield dates:**

Use ISO 8601 formatted strings when filtering by metafield dates.

### Ingesting epoch timestamps from named tags

You can also ingest Unix timestamps directly from named tags using the `number` type hint. Use the format `key:number:timestamp` where timestamp is a Unix timestamp value.

This is useful when you already have Unix timestamps in your product data and want to preserve them without conversion.

## Best practices

### Use the correct format for each date type

* **Product date fields** (`created_at`, `updated_at`, `published_at`): Use ISO 8601 format (`"2024-01-15T10:30:00.000000Z"`)
* **Metafield dates**: Use ISO 8601 format (`"2024-01-15T10:30:00.000000Z"`)
* **Named tag dates**: Use Unix timestamps (numeric values like `1704067200`)

### Store custom dates in metafields or named tags

If you need to track custom dates beyond `created_at`, `updated_at`, and `published_at`, you have two options:

1. **Metafields** (recommended for dates that need to be human-readable): Use Shopify metafields with the `date` or `date_time` type. Layers returns these in ISO 8601 format.

2. **Named tags** (recommended for dates used primarily for filtering/sorting): Use the `date` type hint format (`key:date:value`). Layers converts these to Unix timestamps for efficient filtering.

### Use type hints for named tags

When storing dates in product tags, always use the `date` type hint format (`key:date:value`) to ensure Layers correctly parses and converts the date value to a Unix timestamp.

### Consider time zones

All dates in Layers use UTC timezone. ISO 8601 dates include the `Z` suffix to indicate UTC. When displaying dates to your customers, convert them to the appropriate time zone for your audience.

### Test date filters with known values

When testing date filters, use known date values to verify the results. Ensure you're using the correct format (ISO 8601 for product/metafield dates, Unix timestamps for named tag dates).

## Common use cases

### New arrivals collection

Filter products published within the last 30 days by calculating the date 30 days ago and using it in ISO 8601 format with the `gte` operator on the `published_at` field.

### Recently updated products

Filter products updated within the last 7 days by calculating the date 7 days ago and using it in ISO 8601 format with the `gte` operator on the `updated_at` field.

### Seasonal products

Filter products for a specific season using custom metafields. Use two filter expressions to check if the current date falls between `season_start` and `season_end` metafields.

### Products by custom release date

Filter products by a custom release date stored in named tags using the Unix timestamp value with the appropriate comparison operator.

## Troubleshooting

### Date filter returns no results

**Issue:** Your date filter returns no results even though you expect matches.

**Solutions:**

* Verify you're using the correct format for the date field type:
  * ISO 8601 format for product date fields and metafields
  * Unix timestamps for named tag dates
* Check that the date field exists on your products
* Ensure the date value is in the correct range
* Test with a broader date range to verify data exists

### Incorrect date sorting

**Issue:** Products are not sorting correctly by date.

**Solutions:**

* Verify the date field is marked as sortable in your attributes configuration
* Check that you've created a sort order that includes the date field
* Ensure you're using the correct sort direction (ascending vs descending)
* For named tag dates, verify the dates were properly converted to Unix timestamps

### Named tag dates not working

**Issue:** Dates in named tags are not being detected or converted.

**Solutions:**

* Verify you're using the correct type hint format: `key:date:value`
* Check that the date value is in a supported format (ISO 8601 recommended)
* Ensure there are no extra spaces in the tag format
* Review the `named_tags` object in your product data to verify the conversion to Unix timestamp
* When filtering, use numeric Unix timestamp values, not ISO 8601 strings

### Metafield dates not appearing

**Issue:** Date metafields are not appearing in API responses.

**Solutions:**

* Verify the metafield type is set to `date` or `date_time` in Shopify
* Check that the metafield value is in the correct format for its type
* Ensure the metafield is properly synced to Layers
* Review the `metafields` object in your product data to verify the value
* When filtering, use ISO 8601 formatted strings, not Unix timestamps

## See also

* [Product Schema](/developers/product-schema) - Complete reference for product data structure
* [Filtering Language](/engine/filtering) - Comprehensive guide to filter expressions
* [Catalog Attributes](/platform/attributes) - Managing searchable, filterable, and sortable attributes
* [Metafields & Metaobjects](/shopify-integration/metaobjects-metafields) - Working with Shopify metafields