Skip to main content
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)

Product date fields and metafield dates are returned as ISO 8601 formatted strings. This standardized format includes full date, time, and timezone information. Core date fields:
FieldDescriptionExample Value
created_atWhen the product was created"2022-02-05T01:22:05.000000Z"
updated_atWhen the product was last updated"2023-10-25T20:47:04.000000Z"
published_atWhen the product was published"2022-02-05T01:22:05.000000Z"
Variant date fields:
FieldDescriptionExample Value
variants.created_atWhen the variant was created"2022-02-05T01:22:05.000000Z"
variants.updated_atWhen the variant was last updated"2023-10-25T20:47:04.000000Z"
Metafield dates: Date and datetime metafields from Shopify are also returned 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: The dates are converted to Unix timestamps and stored 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

OperatorDescriptionExample
eqEqual toProducts published on a specific date
gtGreater thanProducts created after a date
gteGreater than or equalProducts updated on or after a date
ltLess thanProducts published before a date
lteLess than or equalProducts created on or before a date
betweenBetween two datesProducts 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

Named tag dates are stored 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

Date fields can be used 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: The dates are converted to Unix timestamps and stored 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
Metafield dates are returned in ISO 8601 format in API responses. 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. These will be returned 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 will convert 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 users, 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