Attribute Options
Attribute options are the selectable values for a select / multiselect attribute (color values, sizes, brands, etc.).
Prefer reading options inline through GET /api/shop/attributes/{id}, which scopes them to one attribute. Use the endpoints here when you want the whole option catalog, or need to resolve an option by ID without knowing its parent attribute.
The URL is flat rather than nested under its attribute — /attribute-options, not /attributes/{id}/options.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /api/shop/attribute-options | Paginated flat list of every option |
| GET | /api/shop/attribute-options/{id} | Single option by ID |
Request Headers
| Header | Required | Description |
|---|---|---|
Accept | Yes | application/json |
X-STOREFRONT-KEY | Yes | Storefront API key (pk_storefront_…) |
Query Parameters (collection only)
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number (1-based) |
per_page | integer | 10 | Items per page. Max 50. |
Pagination headers are emitted on the collection. See Pagination.
Attribute Option Object Fields
| Field | Type | Description |
|---|---|---|
id | integer | Option primary key — use this value when filtering products by an attribute |
adminName | string | Internal admin label |
sortOrder | integer | Display order within its parent attribute |
translation | object | Current-locale translation: { id, attributeOptionId, locale, label } |
translations | array | All locale-specific labels (each { id, attributeOptionId, locale, label }). Empty [] if no other locales have stored labels. |
The parent attribute is not embedded in the response, so an option on its own does not say which attribute it belongs to. Read the attribute when that matters.
Use Cases
- Pre-load all option labels in every storefront locale for offline / SPA caching.
- Resolve historical option IDs stored against orders or carts back to readable labels.
- Build admin-style "find option by label" search.
- Look up the localized label for a specific option in a non-default locale.
Best Practices
- Prefer the attribute's inline
options— Get Attributes already embeds them, and this flat collection cannot be filtered to one attribute. - Order by
sortOrder— it is the order the store configured for display, and it is not guaranteed to match ID order. - Read the localised label from
translation—adminNameis the back-office label, not what a shopper should see.
Related Resources
- Attributes — preferred when you only need options for one attribute
- Attribute Translations — localised attribute labels, keyed by locale