Admin-API/ext/product.graphql

# The Product resource lets you manage products in a merchant’s store.
# You can use ProductVariants to create or update different versions of the same product.
# You can also add or update product Media. Products can be organized by grouping them into a Collection.
type Product
    implements HasMetafieldDefinitions&HasMetafields&HasPublishedTranslations&LegacyInteroperability&Navigable&Node&OnlineStorePreviewable&Publishable
    @key(fields: "id") {
    # The number of publications a resource is published to without feedback errors.
    availablePublicationCount: Int!

    # A list of the collections that include the product.
    collections(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
        sortKey: CollectionSortKeys = ID
        query: String
    ): CollectionConnection!

    # The pricing that applies for a customer in a given context.
    contextualPricing(context: ContextualPricingContext!): ProductContextualPricing!

    # The date and time (ISO 8601 format) when the product was created.
    createdAt: DateTime!

    # A default cursor that returns the single next record, sorted ascending by ID.
    defaultCursor: String!

    # A stripped description of the product, single line with HTML tags removed.
    description(truncateAt: Int): String!

    # The description of the product, complete with HTML formatting.
    descriptionHtml: HTML!

    # The featured image for the product.
    featuredImage: Image

    # The featured media for the product.
    featuredMedia: Media

    # Information about the product that's provided through resource feedback.
    feedback: ResourceFeedback

    # The theme template used when viewing the gift card in a store.
    giftCardTemplateSuffix: String

    # A unique human-friendly string of the product's title.
    handle: String!

    # Whether the product has only a single variant with the default option and value.
    hasOnlyDefaultVariant: Boolean!

    # Whether the product has out of stock variants.
    hasOutOfStockVariants: Boolean!

    # A globally-unique identifier.
    id: ID!

    # The images associated with the product.
    images(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
        sortKey: ProductImageSortKeys = POSITION
    ): ImageConnection!

    # Whether the product is in a given collection.
    inCollection(id: ID!): Boolean!

    # Whether the product is a gift card.
    isGiftCard: Boolean!

    # The ID of the corresponding resource in the REST Admin API.
    legacyResourceId: UnsignedInt64!

    # The media associated with the product. This can include images, 3D models, or videos.
    media(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
        sortKey: ProductMediaSortKeys = POSITION
    ): MediaConnection!

    # Total count of media belonging to a product.
    mediaCount: Int!

    # Returns a metafield by namespace and key that belongs to the resource.
    metafield(namespace: String!key: String!): Metafield

    # List of metafield definitions.
    metafieldDefinitions(
        namespace: String
        pinnedStatus: MetafieldDefinitionPinnedStatus = ANY
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
        sortKey: MetafieldDefinitionSortKeys = ID
        query: String
    ): MetafieldDefinitionConnection!

    # List of metafields that belong to the resource.
    metafields(
        namespace: String
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): MetafieldConnection!

    # The online store preview URL.
    onlineStorePreviewUrl: URL

    # The online store URL for the product.
    # A value of null indicates that the product is not published to the Online Store sales channel.
    onlineStoreUrl: URL

    # A list of product options. The limit is specified by Shop.resourceLimits.maxProductOptions.
    options(first: Int): [ProductOption!]!

    # The price range of the product with prices formatted as decimals.
    priceRangeV2: ProductPriceRangeV2!

    # Returns a private metafield by namespace and key that belongs to the resource.
    privateMetafield(namespace: String!key: String!): PrivateMetafield

    # List of private metafields that belong to the resource.
    privateMetafields(
        namespace: String
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): PrivateMetafieldConnection!

    # The product category specified by the merchant.
    productCategory: ProductCategory

    # The product type specified by the merchant.
    productType: String!

    # The number of publications a resource is published on.
    publicationCount(onlyPublished: Boolean = true): Int!

    # The date and time (ISO 8601 format) when the product was published to the Online Store.
    publishedAt: DateTime

    # Check to see whether the resource is published to the calling app's publication.
    publishedOnCurrentPublication: Boolean!

    # Check to see whether the resource is published to a given publication.
    publishedOnPublication(publicationId: ID!): Boolean!

    # Whether the product can only be purchased with a selling plan (subscription).
    # Products that are sold on subscription (requiresSellingPlan: true) can be updated only for online stores.
    # If you update a product to be subscription only, then the product is unpublished from all channels except the online store.
    requiresSellingPlan: Boolean!

    # The resource that is either published or staged to be published to the calling app's publication.
    # Requires the read_product_listings scope.
    resourcePublicationOnCurrentPublication: ResourcePublicationV2

    # The list of resources that are published to a publication.
    resourcePublications(
        onlyPublished: Boolean = true
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): ResourcePublicationConnection!

    # The list of resources that are either published or staged to be published to a publication.
    resourcePublicationsV2(
        onlyPublished: Boolean = true
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): ResourcePublicationV2Connection!

    # Count of selling plan groups associated with the product.
    sellingPlanGroupCount: Int!

    # A list of all selling plan groups defined in the current shop associated with the product either directly or through any of its variants.
    sellingPlanGroups(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): SellingPlanGroupConnection!

    # SEO information of the product.
    seo: SEO!

    # The product status. This controls visibility across all channels.
    status: ProductStatus!

    # A comma separated list of tags associated with the product. Updating tags overwrites
    # any existing tags that were previously added to the product. To add new tags without overwriting
    # existing tags, use the tagsAdd mutation.
    tags: [String!]!

    # The theme template used when viewing the product in a store.
    templateSuffix: String

    # The title of the product.
    title: String!

    # The quantity of inventory in stock.
    totalInventory: Int!

    # The number of variants that are associated with the product.
    totalVariants: Int!

    # Whether inventory tracking has been enabled for the product.
    tracksInventory: Boolean!

    # The translations associated with the resource.
    translations(locale: String!marketId: ID): [PublishedTranslation!]!

    # The list of publications that the resource is not published to.
    unpublishedPublications(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): PublicationConnection!

    # The date and time when the product was last modified.
    # A product's updatedAt value can change for different reasons. For example, if an order
    # is placed for a product that has inventory tracking set up, then the inventory adjustment
    # is counted as an update.
    updatedAt: DateTime!

    # A list of variants associated with the product.
    variants(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
        sortKey: ProductVariantSortKeys = POSITION
    ): ProductVariantConnection!

    # The name of the product's vendor.
    vendor: String!
}

# Represents a product variant.
type ProductVariant implements HasMetafieldDefinitions&HasMetafields&HasPublishedTranslations&LegacyInteroperability&Navigable&Node {
    # Whether the product variant is available for sale.
    availableForSale: Boolean!

    # The value of the barcode associated with the product.
    barcode: String

    # The compare-at price of the variant in the default shop currency.
    compareAtPrice: Money

    # The pricing that applies for a customer in a given context.
    contextualPricing(context: ContextualPricingContext!): ProductVariantContextualPricing!

    # The date and time when the variant was created.
    createdAt: DateTime!

    # A default cursor that returns the single next record, sorted ascending by ID.
    defaultCursor: String!

    # The delivery profile for the variant.
    deliveryProfile: DeliveryProfile

    # Display name of the variant, based on product's title + variant's title.
    displayName: String!

    # Whether changes to the fulfillment service for the product variant are allowed.
    fulfillmentServiceEditable: EditableProperty!

    # A globally-unique identifier.
    id: ID!

    # The featured image for the variant.
    image: Image

    # The inventory item, which is used to query for inventory information.
    inventoryItem: InventoryItem!

    # Whether customers are allowed to place an order for the product variant when it's out of stock.
    inventoryPolicy: ProductVariantInventoryPolicy!

    # The total sellable quantity of the variant.
    inventoryQuantity: Int

    # The ID of the corresponding resource in the REST Admin API.
    legacyResourceId: UnsignedInt64!

    # The media associated with the product variant.
    media(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): MediaConnection!

    # Returns a metafield by namespace and key that belongs to the resource.
    metafield(namespace: String!key: String!): Metafield

    # List of metafield definitions.
    metafieldDefinitions(
        namespace: String
        pinnedStatus: MetafieldDefinitionPinnedStatus = ANY
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
        sortKey: MetafieldDefinitionSortKeys = ID
        query: String
    ): MetafieldDefinitionConnection!

    # List of metafields that belong to the resource.
    metafields(
        namespace: String
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): MetafieldConnection!

    # The order of the product variant in the list of product variants. The first position in the list is 1.
    position: Int!

    # The price of the product variant in the default shop currency.
    price: Money!

    # Returns a private metafield by namespace and key that belongs to the resource.
    privateMetafield(namespace: String!key: String!): PrivateMetafield

    # List of private metafields that belong to the resource.
    privateMetafields(
        namespace: String
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): PrivateMetafieldConnection!

    # The product that this variant belongs to.
    product: Product!

    # List of product options applied to the variant.
    selectedOptions: [SelectedOption!]!

    # The total sellable quantity of the variant for online channels.
    # This doesn't represent the total available inventory or capture
    # limitations based on customer location.
    sellableOnlineQuantity: Int!

    # Count of selling plan groups associated with the product variant.
    sellingPlanGroupCount: Int!

    # A list of all selling plan groups defined in the current shop associated with the product variant.
    sellingPlanGroups(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): SellingPlanGroupConnection!

    # An identifier for the product variant in the shop. Required in order to connect to a fulfillment service.
    sku: String

    # The tax code for the product variant.
    taxCode: String

    # Whether a tax is charged when the product variant is sold.
    taxable: Boolean!

    # The title of the product variant.
    title: String!

    # The translations associated with the resource.
    translations(locale: String!marketId: ID): [PublishedTranslation!]!

    # The date and time (ISO 8601 format) when the product variant was last modified.
    updatedAt: DateTime!

    # The weight of the product variant in the unit system specified with weight_unit.
    weight: Float

    # The unit of measurement that applies to the product variant's weight.
    # If you don't specify a value for weight_unit, then the shop's default unit of measurement is applied. Valid values: g, kg, oz, lb.
    weightUnit: WeightUnit!
}

# The product property names. For example, "Size", "Color", and "Material".
# Variants are selected based on permutations of these options.
# The limit for each product property name is 255 characters.
type ProductOption implements HasPublishedTranslations&Node {
    # A globally-unique identifier.
    id: ID!

    # The product option’s name.
    name: String!

    # The product option's position.
    position: Int!

    # The translations associated with the resource.
    translations(locale: String!marketId: ID): [PublishedTranslation!]!

    # The corresponding value to the product option name.
    values: [String!]!
}

# The details of a specific product category within the Shopify product taxonomy.
type ProductCategory {
    # The product taxonomy node associated with the product category.
    productTaxonomyNode: ProductTaxonomyNode
}

# Represents a group of products that can be displayed in online stores and other sales channels in categories, which makes it easy for customers to find them. For example, an athletics store might create different collections for running attire, shoes, and accessories.
#
# Collections can be defined by conditions, such as whether they match certain product tags.
# These are called smart or automated collections.
#
# Collections can also be created for a custom group of products. These are called custom or manual collections.
type Collection implements HasMetafieldDefinitions&HasMetafields&HasPublishedTranslations&Node&Publishable {
    # The number of publications a resource is published to without feedback errors.
    availablePublicationCount: Int!

    # A single-line, text-only description of the collection, stripped of any HTML tags and formatting that were included in the description.
    description(truncateAt: Int): String!

    # The description of the collection, including any HTML tags and formatting.
    # This content is typically displayed to customers, such as on an online store, depending on the theme.
    descriptionHtml: HTML!

    # Information about the collection that's provided through resource feedback.
    feedback: ResourceFeedback

    # A unique string that identifies the collection. If a handle isn't specified when a collection is created, it's automatically generated from the collection's original title, and typically includes words from the title separated by hyphens. For example, a collection that was created with the title Summer Catalog 2022 might have the handle summer-catalog-2022.
    #
    # If the title is changed, the handle doesn't automatically change.
    #
    # The handle can be used in themes by the Liquid templating language to refer to the collection, but using the ID is preferred because it never changes.
    handle: String!

    # Whether the collection includes the specified product.
    hasProduct(id: ID!): Boolean!

    # A globally-unique identifier.
    id: ID!

    # The image associated with the collection.
    image: Image

    # The ID of the corresponding resource in the REST Admin API.
    legacyResourceId: UnsignedInt64!

    # Returns a metafield by namespace and key that belongs to the resource.
    metafield(namespace: String!key: String!): Metafield

    # List of metafield definitions.
    metafieldDefinitions(
        namespace: String
        pinnedStatus: MetafieldDefinitionPinnedStatus = ANY
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
        sortKey: MetafieldDefinitionSortKeys = ID
        query: String
    ): MetafieldDefinitionConnection!

    # List of metafields that belong to the resource.
    metafields(
        namespace: String
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): MetafieldConnection!

    # Returns a private metafield by namespace and key that belongs to the resource.
    privateMetafield(namespace: String!key: String!): PrivateMetafield

    # List of private metafields that belong to the resource.
    privateMetafields(
        namespace: String
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): PrivateMetafieldConnection!

    # The products that are included in the collection.
    products(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
        sortKey: ProductCollectionSortKeys = COLLECTION_DEFAULT
    ): ProductConnection!

    # The number of products in the collection.
    productsCount: Int!

    # The number of publications a resource is published on.
    publicationCount(onlyPublished: Boolean = true): Int!

    # Check to see whether the resource is published to the calling app's publication.
    publishedOnCurrentPublication: Boolean!

    # Check to see whether the resource is published to a given publication.
    publishedOnPublication(publicationId: ID!): Boolean!

    # The list of resources that are published to a publication.
    resourcePublications(
        onlyPublished: Boolean = true
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): ResourcePublicationConnection!

    # The list of resources that are either published or staged to be published to a publication.
    resourcePublicationsV2(
        onlyPublished: Boolean = true
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): ResourcePublicationV2Connection!

    # For a smart (automated) collection, specifies the rules that determine whether a product is included.
    ruleSet: CollectionRuleSet

    # If the default SEO fields for page title and description have been modified, contains the modified information.
    seo: SEO!

    # The order in which the products in the collection are displayed by default in the Shopify admin and in sales channels, such as an online store.
    sortOrder: CollectionSortOrder!

    # The suffix of the Liquid template being used to show the collection in an online store. For example, if the value is custom, then the collection is using the collection.custom.liquid template. If the value is null, then the collection is using the default collection.liquid template.
    templateSuffix: String

    # The name of the collection. It's displayed in the Shopify admin and is typically displayed in sales channels, such as an online store.
    title: String!

    # The translations associated with the resource.
    translations(locale: String!marketId: ID): [PublishedTranslation!]!

    # The list of publications that the resource is not published to.
    unpublishedPublications(
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): PublicationConnection!

    # The date and time (ISO 8601 format) when the collection was last modified.
    updatedAt: DateTime!
}

# Properties used by customers to select a product variant.
# Products can have multiple options, like different sizes or colors.
type SelectedOption {
    # The product option’s name.
    name: String!

    # The product option’s value.
    value: String!
}

# The price of a product variant in a specific country.
# Prices vary between countries.
type ProductVariantContextualPricing {
    # The final compare-at price after all adjustments are applied.
    compareAtPrice: MoneyV2

    # The final price after all adjustments are applied.
    price: MoneyV2!
}

# The context data that determines the pricing of a variant.
input ContextualPricingContext {
    # The country code used to fetch country-specific prices.
    country: CountryCode

    # The CompanyLocation ID used to fetch company location specific prices.
    companyLocationId: ID
}

# The set of rules that are used to determine which products are included in the collection.
type CollectionRuleSet {
    # Whether products must match any or all of the rules to be included in the collection.
    # If true, then products must match at least one of the rules to be included in the collection.
    # If false, then products must match all of the rules to be included in the collection.
    appliedDisjunctively: Boolean!

    # The rules used to assign products to the collection.
    rules: [CollectionRule!]!
}

# The set of rules that are used to determine which products are included in the collection.
type CollectionRule {
    # Whether products must match any or all of the rules to be included in the collection.
    # If true, then products must match at least one of the rules to be included in the collection.
    # If false, then products must match all of the rules to be included in the collection.
    appliedDisjunctively: Boolean!

    # The rules used to assign products to the collection.
    rules: [CollectionRule!]!
}

# The price of a product in a specific country.
# Prices vary between countries.
type ProductContextualPricing {
    # The pricing of the variant with the highest price in the given context.
    maxVariantPricing: ProductVariantContextualPricing

    # The pricing of the variant with the lowest price in the given context.
    minVariantPricing: ProductVariantContextualPricing

    # The price range of the product with prices formatted as decimals.
    priceRange: ProductPriceRangeV2!
}

# The price range of the product.
type ProductPriceRangeV2 {
    # The highest variant's price.
    maxVariantPrice: MoneyV2!

    # The lowest variant's price.
    minVariantPrice: MoneyV2!
}

# Represents a Shopify product taxonomy node.
type ProductTaxonomyNode implements Node {
    # The full name of the product taxonomy node.
    # For example, Animals & Pet Supplies > Pet Supplies > Dog Supplies > Dog Beds.
    fullName: String!

    # The ID of the product taxonomy node.
    id: ID!

    # Whether the node is a leaf node.
    isLeaf: Boolean!

    # Whether the node is a root node.
    isRoot: Boolean!

    # The name of the product taxonomy node. For example, Dog Beds.
    name: String!
}