Skip to main content

Set product categories on custom line items in draft orders and order edits

Starting with GraphQL Admin API version 2027-01, you can assign a category from Shopify's Standard Product Taxonomy to custom line items in draft orders and order edits. The category controls the item's tax treatment in the same way it does for products.

For stores using Managed Taxes, the product category is the only input that sets a custom line item's tax treatment.

What's new

You can now set and read product categories on custom line items in draft orders and order edits:

Draft orders

  • DraftOrderLineItemInput.productCategoryId sets the product category of a custom line item. You can use it with draftOrderCreate, draftOrderUpdate and draftOrderCalculate. It's ignored when variantId is provided.
  • DraftOrderLineItem.productCategory and CalculatedDraftOrderLineItem.productCategory return the category of a custom line item. They return null for product variant line items.

Order edits

  • orderEditAddCustomItem accepts a new productCategoryId argument.
  • CalculatedLineItem.productCategory returns the category of the calculated line item.

If productCategoryId doesn't match a category in the current taxonomy, the mutation returns a user error.

How the category affects tax

StoreTax treatment of a custom line item
Uses Managed TaxesSet by productCategoryId. The taxable input is ignored. A custom line item with no category is treated as Uncategorized and taxed at the standard rate.
All other storestaxable: false means the item isn't taxed. When the item is taxed, Shopify uses its category to calculate tax.

The taxable input on custom line items is deprecated in favour of productCategoryId. For details, see taxable on custom line items is deprecated.

Why this matters

A yes-or-no taxable flag can't express reduced rates or category-specific exemptions, and it doesn't record why an item was taxed or exempted. A product category lets tax calculation apply the right rules to a custom line item and records the reason for the tax treatment.

How to use it

  1. Look up a category ID with the taxonomy query:
query {
  taxonomy {
    categories(search: "t-shirts", first: 5) {
      nodes {
        id
        fullName
      }
    }
  }
}
  1. Pass the ID as productCategoryId on a custom line item in draftOrderCreate, draftOrderUpdate, draftOrderCalculate, or orderEditAddCustomItem.
  2. Read the saved category from productCategory on DraftOrderLineItem, CalculatedDraftOrderLineItem, or CalculatedLineItem.

Related docs

Was this page helpful?