Skip to main content
Layers supports 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: Variant date fields: Metafield dates: Layers also returns date and datetime metafields from Shopify in ISO 8601 format.

​
Unix timestamps (named tag dates)

Named tags don’t have a date type. To store a date in a product tag, write it as a Unix timestamp (seconds since epoch) with the number type hint. Layers stores the value as a number in the named_tags object, so you can filter and sort on it. Named tag format:
Example tags:
  • ReleaseDate:number:1710460800 (2024-03-15)
  • AvailableUntil:number:1735603200 (2024-12-31)
Resulting named_tags object:
Layers only recognizes the number and boolean type hints. A tag such as ReleaseDate:date:2024-03-15 is not converted to a date and does not appear in named_tags. Values that contain extra colons, such as a time like 10:00:00, are also skipped, so always use a plain Unix timestamp.

​
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. See Filtering Language for the full expression format.

​
Filtering by product date fields

Filter products created after a specific date using the after operator (or gt) with an ISO 8601 formatted date string. Filter products published before a specific date using the before operator (or lt) with an ISO 8601 formatted date string. Filter products published recently using the inLast operator with a number of days. Layers evaluates the window at query time, so a saved filter for the last 30 days always means the 30 days before now.

​
Date range filtering

Filter products within a date range using the between operator with exactly two ISO 8601 formatted date strings. Use notBetween to exclude a range.

​
Available date operators

after, before, and inLast work on date and timestamp fields, such as the product date fields and date metafields. For named tag dates, which are stored as numbers, use gt, gte, lt, lte, or between with Unix timestamps.

​
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 with gt, gte, lt, lte, or between 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 with the number type hint) 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 date values in Shopify metafields. Dates in product tags are not detected automatically. Store them as Unix timestamps, as described in Unix timestamps (named tag dates).

​
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.

​
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 number type hint with a Unix timestamp (key:number:1710460800). See Unix timestamps (named tag dates).

​
Use the number type hint for named tag dates

When storing dates in product tags, convert the date to a Unix timestamp yourself and use the number type hint (key:number:value). Layers does not parse date strings in tags.

​
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 with the inLast operator and a value of 30 on the published_at field. Because the window is evaluated at query time, you don’t need to update the date as time passes.

​
Recently updated products

Filter products updated within the last 7 days with the inLast operator and a value of 7 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 tags use the number type hint so the values are stored as Unix timestamps

​
Named tag dates not working

Issue: Dates in named tags are not being detected or converted. Solutions:
  • Verify you’re using the number type hint with a Unix timestamp: key:number:1710460800. Tags that use date as the type hint are skipped.
  • Make sure the value has no extra colons. A tag like RestockDate:number:2024-06-01T10:00:00Z has too many parts and is skipped.
  • Ensure there are no extra spaces in the tag format
  • Review the named_tags object in your product data to verify the value appears as a number
  • When filtering, use numeric Unix timestamp values with gt, gte, lt, lte, or between, not ISO 8601 strings or inLast

​
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