Product Add-on Field Types

WooGraphQL Pro exposes all 8 WooCommerce Product Add-on field types through a unified interface with type-specific fields.

All addon types implement this interface:

interface ProductAddonField {
  fieldName: String!
  name: String
  type: ProductAddonFieldEnum
  titleFormat: ProductAddonTitleFormatEnum
  description: String
  required: Boolean
  priceType: ProductAddonPriceAdjustEnum
  price: Float
}

Short text input with optional validation restrictions.

type AddonShortText implements ProductAddonField {
  fieldName: String!
  name: String
  type: ProductAddonFieldEnum
  titleFormat: ProductAddonTitleFormatEnum
  description: String
  required: Boolean
  priceType: ProductAddonPriceAdjustEnum
  price: Float

  # Type-specific fields
  restrictions: ProductAddonShortTextRestrictionEnum
  characterLimit: ProductAddonIntegerRange
}

query GetShortTextAddon($id: ID!) {
  product(id: $id, idType: DATABASE_ID) {
    addons {
      ... on AddonShortText {
        fieldName
        name
        required
        price
        priceType
        restrictions
        characterLimit {
          min
          max
        }
      }
    }
  }
}

Pass the text value directly as a string:

{
  "addons": [
    {
      "fieldName": "addon-123_test-text-0",
      "value": "Custom Engraving Text"
    }
  ]
}

Textarea for longer text input.

type AddonLongText implements ProductAddonField {
  fieldName: String!
  name: String
  type: ProductAddonFieldEnum
  titleFormat: ProductAddonTitleFormatEnum
  description: String
  required: Boolean
  priceType: ProductAddonPriceAdjustEnum
  price: Float

  # Type-specific fields
  characterLimit: ProductAddonIntegerRange
}

query GetLongTextAddon($id: ID!) {
  product(id: $id, idType: DATABASE_ID) {
    addons {
      ... on AddonLongText {
        fieldName
        name
        required
        price
        priceType
        characterLimit {
          min
          max
        }
      }
    }
  }
}

Pass the text value directly as a string:

{
  "addons": [
    {
      "fieldName": "addon-123_special-instructions-1",
      "value": "This is a longer message with multiple sentences. Please handle with care and include gift wrapping."
    }
  ]
}

Multiple checkbox options that can be selected together.

type AddonCheckbox implements ProductAddonField {
  fieldName: String!
  name: String
  type: ProductAddonFieldEnum
  titleFormat: ProductAddonTitleFormatEnum
  description: String
  required: Boolean
  priceType: ProductAddonPriceAdjustEnum
  price: Float

  # Type-specific fields
  options: [ProductAddonOption]
}

query GetCheckboxAddon($id: ID!) {
  product(id: $id, idType: DATABASE_ID) {
    addons {
      ... on AddonCheckbox {
        fieldName
        name
        required
        options {
          label
          price
          priceType
        }
      }
    }
  }
}

Pass an array of the selected option labels (exact match, no index suffix):

{
  "addons": [
    {
      "fieldName": "addon-123_extras-2",
      "value": ["Gift Wrap", "Express Shipping"]
    }
  ]
}

Each selected checkbox creates a separate entry in the cart item's addon data, with its own price applied.

Selection from multiple options via dropdown, radio buttons, or image selector.

type AddonMultipleChoice implements ProductAddonField {
  fieldName: String!
  name: String
  type: ProductAddonFieldEnum
  titleFormat: ProductAddonTitleFormatEnum
  description: String
  required: Boolean
  priceType: ProductAddonPriceAdjustEnum
  price: Float

  # Type-specific fields
  choiceType: ProductAddonDisplayAsEnum
  options: [ProductAddonOption]
}

query GetMultipleChoiceAddon($id: ID!) {
  product(id: $id, idType: DATABASE_ID) {
    addons {
      ... on AddonMultipleChoice {
        fieldName
        name
        required
        choiceType
        options {
          label
          price
          priceType
          image {
            sourceUrl
            altText
          }
        }
      }
    }
  }
}

Important: For multiple choice addons, the value must be the option label suffixed with -{index} where {index} is the 1-based position of the option.

Given options:

{
  "options": [
    { "label": "Small", "price": 0 },
    { "label": "Medium", "price": 5 },
    { "label": "Large", "price": 10 }
  ]
}

To select "Medium" (the 2nd option):

{
  "addons": [
    {
      "fieldName": "addon-123_size-3",
      "value": "Medium-2"
    }
  ]
}

To select "Large" (the 3rd option):

{
  "addons": [
    {
      "fieldName": "addon-123_size-3",
      "value": "Large-3"
    }
  ]
}

File upload field for customer attachments.

type AddonFileUpload implements ProductAddonField {
  fieldName: String!
  name: String
  type: ProductAddonFieldEnum
  titleFormat: ProductAddonTitleFormatEnum
  description: String
  required: Boolean
  priceType: ProductAddonPriceAdjustEnum
  price: Float
}

query GetFileUploadAddon($id: ID!) {
  product(id: $id, idType: DATABASE_ID) {
    addons {
      ... on AddonFileUpload {
        fieldName
        name
        required
        price
        priceType
      }
    }
  }
}

Pass the uploaded file path after server-side file handling:

{
  "addons": [
    {
      "fieldName": "addon-123_custom-image-4",
      "value": "/uploads/2024/01/customer-file.jpg"
    }
  ]
}

Note: File upload handling requires your frontend to upload the file first (via a separate endpoint) and then pass the resulting file path to the addon.

Quantity multiplier for purchases.

type AddonQuantity implements ProductAddonField {
  fieldName: String!
  name: String
  type: ProductAddonFieldEnum
  titleFormat: ProductAddonTitleFormatEnum
  description: String
  required: Boolean
  priceType: ProductAddonPriceAdjustEnum
  price: Float

  # Type-specific fields
  quantityLimit: ProductAddonIntegerRange
}

query GetQuantityAddon($id: ID!) {
  product(id: $id, idType: DATABASE_ID) {
    addons {
      ... on AddonQuantity {
        fieldName
        name
        required
        price
        priceType
        quantityLimit {
          min
          max
        }
      }
    }
  }
}

Pass the quantity as a string number:

{
  "addons": [
    {
      "fieldName": "addon-123_extra-pages-6",
      "value": "3"
    }
  ]
}

With priceType: QUANTITY_BASED, the addon price is multiplied by this quantity value.

Customer-specified price input within a range.

type AddonCustomerDefinedPrice implements ProductAddonField {
  fieldName: String!
  name: String
  type: ProductAddonFieldEnum
  titleFormat: ProductAddonTitleFormatEnum
  description: String
  required: Boolean
  priceType: ProductAddonPriceAdjustEnum
  price: Float

  # Type-specific fields
  priceRangeLimit: ProductAddonFloatRange
}

query GetCustomPriceAddon($id: ID!) {
  product(id: $id, idType: DATABASE_ID) {
    addons {
      ... on AddonCustomerDefinedPrice {
        fieldName
        name
        required
        priceRangeLimit {
          min
          max
        }
      }
    }
  }
}

Pass the customer's price as a string:

{
  "addons": [
    {
      "fieldName": "addon-123_donation-7",
      "value": "25.00"
    }
  ]
}

The price must fall within the priceRangeLimit if defined.

Section heading for organizing addons (display only, no input required).

type AddonHeading implements ProductAddonField {
  fieldName: String!
  name: String
  type: ProductAddonFieldEnum
  titleFormat: ProductAddonTitleFormatEnum
  description: String
  required: Boolean
  priceType: ProductAddonPriceAdjustEnum
  price: Float
}

query GetHeadingAddon($id: ID!) {
  product(id: $id, idType: DATABASE_ID) {
    addons {
      ... on AddonHeading {
        fieldName
        name
        description
      }
    }
  }
}

Heading addons are skipped during cart processing. You can omit them from mutation input, or pass the heading name:

{
  "addons": [
    {
      "fieldName": "addon-123_personalization-options-5",
      "value": "Personalization Options"
    }
  ]
}

Used by AddonMultipleChoice and AddonCheckbox:

type ProductAddonOption {
  label: String
  priceType: ProductAddonPriceAdjustEnum
  price: Float
  image: MediaItem
}

type ProductAddonIntegerRange {
  min: Int
  max: Int
}

type ProductAddonFloatRange {
  min: Float
  max: Float
}

Query all addon types with their specific fields:

query GetAllAddonTypes($id: ID!) {
  product(id: $id, idType: DATABASE_ID) {
    id
    name
    addons {
      fieldName
      name
      type
      titleFormat
      description
      required
      price
      priceType

      ... on AddonMultipleChoice {
        choiceType
        options {
          label
          price
          priceType
          image {
            sourceUrl
          }
        }
      }

      ... on AddonCheckbox {
        options {
          label
          price
          priceType
        }
      }

      ... on AddonShortText {
        restrictions
        characterLimit {
          min
          max
        }
      }

      ... on AddonLongText {
        characterLimit {
          min
          max
        }
      }

      ... on AddonCustomerDefinedPrice {
        priceRangeLimit {
          min
          max
        }
      }

      ... on AddonQuantity {
        quantityLimit {
          min
          max
        }
      }
    }
  }
}

Adding a product with all addon types:

mutation AddToCartWithAllAddons($input: AddToCartInput!) {
  addToCart(input: $input) {
    cartItem {
      key
      quantity
      total
      extraData {
        key
        value
      }
    }
  }
}

Variables:

{
  "input": {
    "productId": 123,
    "quantity": 1,
    "addons": [
      {
        "fieldName": "addon-123_engraving-0",
        "value": "Custom Text Here"
      },
      {
        "fieldName": "addon-123_message-1",
        "value": "This is a longer message for the gift card."
      },
      {
        "fieldName": "addon-123_extras-2",
        "value": ["Gift Wrap", "Insurance"]
      },
      {
        "fieldName": "addon-123_color-3",
        "value": "Blue-2"
      },
      {
        "fieldName": "addon-123_image-4",
        "value": "/uploads/customer-image.jpg"
      },
      {
        "fieldName": "addon-123_pages-6",
        "value": "3"
      },
      {
        "fieldName": "addon-123_tip-7",
        "value": "5.00"
      }
    ]
  }
}

• Cart Integration - Working with addons in the cart
• API Types Reference - Complete type definitions