Skip to Content

Image

Represents an image, including its metadata, file information, and variant associations.

Type Definition

type Image { alt: String url: String title: String description: String tags: [String] aiProcessed: Boolean width: Int height: Int aspectRatio: String mimeType: String fileExtension: String fileSize: Int fileName: String orientation: String sortOrder: Int type: String attachedToVariant: Boolean variants: [ProductVariant] }

Fields

FieldTypeNullableDescriptionRelated Type
altStringYesThe alt text for the image, used for accessibility and SEO.
urlStringYesThe direct URL to the image file.
titleStringYesThe title of the image, often used as alt text.
descriptionStringYesThe description of the image, if available.
tags[String]YesThe tags associated with the image.String
aiProcessedBooleanYesIndicates whether the image has been processed by AI.
widthIntYesThe width of the image in pixels.
heightIntYesThe height of the image in pixels.
aspectRatioStringYesThe aspect ratio of the image, such as 16:9.
mimeTypeStringYesThe MIME type of the image file.
fileExtensionStringYesThe file extension of the image, such as jpg or png.
fileSizeIntYesThe size of the image file in bytes.
fileNameStringYesThe file name of the image.
orientationStringYesThe orientation of the image, such as landscape or portrait.
sortOrderIntYesThe sort order of the image among other images.
typeStringYesThe type of media, which is always ‘image’ for this drop.
attachedToVariantBooleanYesIndicates whether the image is attached to a product variant. Only available through product image or media methods.
variants[ProductVariant]YesThe product variants this image is attached to. Only available through product image or media methods.ProductVariant

Relationships

  • variants: This field links the image to one or more ProductVariant objects. It represents the product variants that this image is attached to. This relationship is only available when the image is accessed through product image or media methods.
  • tags: An array of strings representing tags associated with the image, useful for categorization or filtering.

Usage Examples

Basic Query

Fetch basic metadata about an image including its URL and alt text:

{ image(id: 12345) { url alt title } }

Field Selection

Retrieve detailed information about an image including file details and AI processing status:

{ image(id: 12345) { url alt description tags aiProcessed width height mimeType fileExtension fileSize fileName orientation sortOrder type } }

Nested Queries

Query an image along with the product variants it is attached to, retrieving variant IDs and titles:

{ image(id: 12345) { url alt attachedToVariant variants { id title sku } } }

Filtering and Sorting

Filter images by tags and sort by sortOrder (assuming the API supports arguments on image collections):

{ images(filter: { tags_contains: ["summer", "sale"] }, sort: SORT_ORDER_ASC, first: 10) { edges { node { url alt sortOrder } } } }

Implements

This type does not explicitly implement any interfaces.

Connections

The variants field connects Image to the ProductVariant type, enabling traversal from an image to the product variants it represents.

  • ProductVariant: Represents product variations that can be associated with images.
  • String: Used for tags and various descriptive fields.

Best Practices

  • Use the alt field to provide meaningful alternative text for accessibility and SEO.
  • When querying images attached to product variants, use the variants field to retrieve related variant details efficiently.
  • Limit the number of images retrieved in bulk queries with filtering and pagination to optimize performance.
  • Use the sortOrder field to display images in a consistent and user-friendly order.
  • Check the aiProcessed flag to determine if AI-based enhancements or metadata are available for the image.

Notes

  • All fields on the Image type are optional and may return null if data is not available.
  • The attachedToVariant and variants fields are only available when the image is accessed through product image or media methods.
  • The type field will always have the value "image" for this object type.
  • The API currently requires no authentication, but this may change in future versions. Plan your integration accordingly.
  • Consider caching image URLs and metadata on the client side to reduce repeated network requests, especially for static images.
  • Filtering and sorting capabilities depend on the API’s support for arguments on image collections; always check the schema for available options.
Last updated on