Question regarding "Item Personalization" line items in Shopify Admin API (v2023-07) order response

Technical Q&A
,
1

Hi everyone,

We are currently fetching order data using version 2023-07 of the Shopify Admin API via the /admin/api/2023-07/orders.json endpoint.

While reviewing our order logs, we noticed that “Item Personalization” items (presumably generated by a third-party product customizer/personalization app) are coming in as completely separate line items within the line_items array, rather than as properties of the main product.

Here is a simplified version of the response structure we are receiving (some fields have been omitted for brevity):

{
  "orders": [
    {
      "id": 18750466162733,
      "name": "#1027",
      "currency": "USD",
      "//": "... omitted for brevity ...",
      "line_items": [
        {
          "id": 50397155950637,
          "name": "[AMN] Juan stretch chef coat #AJ2016 White - Men M (100)",
          "//": "..."
        },
        {
          "id": 50397155983405,
          "name": "[AMN] Juan stretch chef coat #AJ2016 White - Men M (100)",
          "//": "..."
        },
        {
          "id": 50397156016173,
          "product_id": 6904571822125,
          "variant_id": 40157527179309,
          "name": "Item Personalization",
          "title": "Item Personalization",
          "price": "0.01",
          "quantity": 300,
          "current_quantity": 300,
          "sku": "",
          "vendor": "A MONT",
          "requires_shipping": false,
          "taxable": false,
          "properties": [
            {
              "name": "_pc_pricing_ref",
              "value": "127041699"
            }
          ]
        },
        {
          "id": 50397156048941,
          "name": "#AJ1867 Danjo Sushi Chef Coat - M (95)",
          "//": "..."
        },
        {
          "id": 50397156081709,
          "product_id": 6904571822125,
          "variant_id": 40157527179309,
          "name": "Item Personalization",
          "title": "Item Personalization",
          "price": "0.01",
          "quantity": 300,
          "current_quantity": 300,
          "sku": "",
          "vendor": "A MONT",
          "requires_shipping": false,
          "taxable": false,
          "properties": [
            {
              "name": "_pc_pricing_ref",
              "value": "112873737"
            }
          ]
        }
      ]
    }
  ]
}

Regarding this behavior, we have two questions:

Is it standard Shopify behavior for app-generated personalization options to be treated as independent line items like this, instead of being nested under the main product?

If anyone has experience or best practices for mapping these “Item Personalization” line items back to their parent (main) products using the reference keys in properties (such as _pc_pricing_ref), could you please share your insights or logic?

Any help or documentation pointers would be greatly appreciated.

Thank you!

2

It’s the choice of the app builder/developer. Perhaps the information they need to add is too long for the standard customAttributes, although I don’t see what exactly is customised. Probably the app is keeping track of line items with their customisation values like an image or custom upload.

By the way, you might want to bump up that deprecated API version

3

These are probably Nested cart lines which are not supported by your ancient API version.

Many add-on apps have switched to using those.

4

This usually depends on how the personalization app adds the customization. If it creates personalization as a separate add-on product/variant, Shopify will show it as a separate line item and will not automatically nest it under the main product.

The best approach is to check whether _pc_pricing_ref also exists on the parent product line item, or ask the app developer what that reference maps to. If there is no matching reference, mapping from Shopify data alone may not be fully reliable. For future orders, it would be cleaner to store personalization as line item properties on the main product instead of a separate line item.

5

Looking at the payload you shared, it seems the personalization isn’t attached to the original products as line item properties. Instead, it’s being added as separate “Item Personalization” line items, each with its own _pc_pricing_ref property.

That usually means the app handling personalization is storing the actual customization details elsewhere and using _pc_pricing_ref as a reference ID, rather than including all the personalization data directly in the order response.

If you’re trying to retrieve the customer’s personalization (text, engraving, etc.), you’ll likely need to check the documentation for the personalization app you’re using to see how that reference ID is resolved. The Admin API is only returning what was saved with the order, and in this payload, that’s just the reference ID rather than the full personalization details.

6

Based on what you’ve described, this behavior is often determined by how the personalization app creates the order rather than by the Admin API itself. The Orders API generally returns the line items exactly as they were stored on the order.

If the personalization app is creating the customization as a separate product or hidden line item, it will appear as its own entry in the line_items array. On the other hand, if the app stores the customization as line item properties, those values would typically appear under the properties field of the corresponding product line item.

It may be worth checking whether this behavior is consistent across all personalized orders or only those created by a specific app. You could also compare the order in the Shopify Admin with the API response to see how the line items are actually stored. If the order itself contains separate line items, the API is expected to return them that way.

If you know which personalization app is being used, its documentation or support team may also be able to clarify whether this is the intended order structure.

7

Hello,

Based on the previous replies, I reviewed the actual Shopify Orders API response.

The order contains a separate line item in addition to the actual product line items:

{
  "name": "Item Personalization",
  "title": "Item Personalization",
  "quantity": 300,
  "price": "0.01",
  "requires_shipping": false,
  "variant_title": null,
  "properties": [
    {
      "name": "_pc_pricing_ref",
      "value": "127041699"
    }
  ]
}

The actual product line item contains the customer’s personalization details in the properties field:

{
  "name": "[AMN] Juan stretch chef coat #AJ2016 White - Men M (100)",
  "title": "[AMN] Juan stretch chef coat #AJ2016 White",
  "variant_title": "Men M (100)",
  "quantity": 1,
  "requires_shipping": true,
  "properties": [
    {
      "name": "Logo Letters (The logo can be up to 3 lines )",
      "value": "S D C"
    },
    {
      "name": "Font Style",
      "value": "Notosans"
    },
    {
      "name": "Choose A Color",
      "value": "silver"
    },
    {
      "name": "Text Placement",
      "value": "Left Chest"
    },
    {
      "name": "_pc_pricing_ref",
      "value": "127041699"
    },
    {
      "name": "_pc_pricing_qty_split",
      "value": "40157527179309-300"
    }
  ]
}

Our system stores each Shopify line_items entry as an individual order item.

Could you please confirm whether the following handling would be safe and correct?

  1. Can a line item where both name and title are Item Personalization be treated as a helper line item used only for personalization pricing, rather than as an actual purchased product?
  2. Can this Item Personalization line item be excluded from our order-item import process?
  3. Should the customer’s actual personalization selections be collected from the properties field of the corresponding real product line item?
  4. Can the quantity: 300 value on the Item Personalization line item be understood as a pricing-related quantity rather than the actual ordered quantity?
  5. Is there a safer and more reliable way to identify this helper line item than checking whether name or title equals Item Personalization?

For example, can we identify it using a combination of the following fields?

  • requires_shipping: false
  • variant_title: null
  • Presence of the _pc_pricing_ref property
  • A specific product_id or variant_id
  1. Is this structure part of Shopify’s standard behavior, or is it specific to the Product Personalizer app being used by this store?
  2. Could the Item Personalization title, product_id, variant_id, or property names change due to app configuration changes or app version updates?

Our intended implementation is:

- Actual product line item
  → Store the product title, variant title, and quantity
  → If properties exist, store the customer’s personalization details as option information

- Item Personalization line item
  → Exclude it from order-item storage if it is only a helper item for personalization pricing

Also, could excluding the Item Personalization line item cause any issues when processing order totals, refunds, fulfillment, or other Shopify-related operations?

Thank you.