Get Attribute Options

About

The getAttributeOptions query retrieves attribute options (values) for a specific attribute. This query is essential for:

• Building product filter and search interfaces
• Displaying color swatches and size options
• Creating configurable product selectors
• Building faceted navigation systems
• Multi-language product attribute support

The query supports cursor-based pagination and optional translation fetching, making it ideal for displaying product attribute values in various UI contexts.

Arguments

Argument	Type	Required	Description
first	Int	❌ No	Number of options to retrieve from the start (forward pagination). Max: 100.
after	String	❌ No	Cursor to start after for forward pagination.
last	Int	❌ No	Number of options to retrieve from the end (backward pagination). Max: 100.
before	String	❌ No	Cursor to start before for backward pagination.

Possible Returns

Field	Type	Description
edges	[AttributeOptionEdge!]!	Array of attribute option edges containing options and cursors.
edges.node	AttributeOption!	The actual attribute option object with id, name, swatch, and translations.
edges.cursor	String!	Pagination cursor for this option. Use with after or before arguments.
pageInfo	PageInfo!	Pagination metadata object.
pageInfo.hasNextPage	Boolean!	Whether more options exist after the current page.
pageInfo.hasPreviousPage	Boolean!	Whether options exist before the current page.
pageInfo.startCursor	String	Cursor of the first option on the current page.
pageInfo.endCursor	String	Cursor of the last option on the current page.

AttributeOption Fields

Field	Type	Description
id	String!	Unique option identifier in format /api/shop/attribute-options/{id}.
_id	Int!	Numeric ID of the option.
adminName	String!	Admin-facing name (e.g., "Red", "Large", "Cotton").
sortOrder	Int!	Display order of the option (0, 1, 2, ...).
swatchValue	String	Swatch value - hex color code for color attributes or text representation.
swatchValueUrl	String	URL to swatch image file for image-based swatches.
translation	OptionTranslation	Single translation for the default/current locale.
translations	[OptionTranslation!]	Collection of all translations for multi-language support.

Translation Fields

Field	Type	Description
id	String!	Translation ID in format /api/attribute_option_translations/{id}.
_id	Int!	Numeric translation ID.
locale	String!	Language locale code (e.g., "en", "ar", "fr", "de").
label	String!	Translated label for the option in the specified locale.

Common Use Cases

Display Color Picker in Product Page

query ColorPicker {
  attributeOptions(first: 50) {
    edges {
      node {
        adminName
        swatchValue
        translation { label }
      }
    }
  }
}

Build Size Selector with Sorting

query SizeSelector {
  attributeOptions(first: 100) {
    edges {
      node {
        adminName
        sortOrder
        translation { label }
      }
    }
  }
}

Multi-language Attribute Support

query MultiLanguageOptions {
  attributeOptions(first: 20) {
    edges {
      node {
        adminName
        translations(first: 10) {
          edges {
            node {
              locale
              label
            }
          }
        }
      }
    }
  }
}

Error Handling

Missing Attribute ID

{
  "errors": [
    {
      "message": "Field \"attributeOptions\" argument \"attributeId\" of type \"Int!\" is required but not provided."
    }
  ]
}

Non-existent Attribute

{
  "data": {
    "attributeOptions": {
      "edges": [],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": null
      }
    }
  }
}

Invalid Pagination Cursor

{
  "errors": [
    {
      "message": "Invalid cursor provided"
    }
  ]
}

Best Practices

1. Use Appropriate Pagination Size - Request 10-50 options per page
2. Cache Results - Attribute options change infrequently, cache them
3. Request Translations When Needed - Only fetch translations if supporting multiple languages
4. Optimize Field Selection - Request only fields your UI actually needs

Related Resources

• Pagination Guide - Cursor pagination documentation
• Attribute Options API - Detailed API documentation
• Products API - Related product queries
• Shop API Overview - Overview of Shop API resources