Skip to content

Guide 41 · Ecommerce · GA4 + Tag Manager

The items array rules: what each item needs, the 200-item limit, and the 27 custom parameters

Checked 11 November 2026 · Verification: reference file checked in Python (figures recomputed from the worked example) · Steps traced to Google's developer docs and Analytics Help, opened 11 November 2026 · 5-minute read

Every ecommerce event carries its products in one items array. The rules are short — item_id or item_name, quantity defaults to 1, 200 items at most — and breaking them empties the reports silently.

Expected signal

After step 4, DebugView shows the purchase event with an items array of two items, each with item_id and item_name, and value 72.05. After about 24 hours, the Ecommerce purchases report shows both items by name, with no (not set) rows.

Download the reference: the items-array-rules reference (JSON) (960 bytes, MD5 1d61110ec74290b8e131c2a07804a884). It holds the event parameters, the worked example, and the recomputed figures.

What you need

  • The Google tag on the site. The event is sent through the Google tag; the install guide covers it.
  • Access to the website source code, or a Tag Manager container. The items array is built where the event is sent.
  • One worked order. Google's two-item order: three Stan and Friends Tees at 10.01 (30.03) and two grey tees at 21.01 (42.02), a total of 72.05.

The trace

  1. Give every item an item_id or an item_name — preferably both. Each item in the items array only requires item_id or item_name, and Google recommends providing both. The worked order sends both for each item: SKU_12345 with Stan and Friends Tee, and SKU_12346 with Google Grey Women's Tee. An item with only a name can be reported on, but it cannot be joined to a product feed by ID.
  2. Send quantity, or it defaults to 1. Quantity is optional, and when it is not set Analytics treats it as 1. The worked order sends quantity 3 for the tees and quantity 2 for the grey tees, so the value is 10.01 × 3 = 30.03 plus 21.01 × 2 = 42.02, which is 30.03 + 42.02 = 72.05. An order of three tees sent without a quantity is recorded as one tee.
  3. Keep the array to 200 items. The items array can include up to 200 elements. An order with more than 200 lines — a wholesale order, a bulk buy — must be split or trimmed before it is sent; the 201st item and beyond are not recorded. Two items, as in the worked order, is the usual case.
  4. Use the prescribed parameters first, custom parameters second. The items array accepts the prescribed parameters — item_id, item_name, affiliation, coupon, discount, index, item_brand, item_category through item_category5, item_list_id, item_list_name, item_variant, location_id, price, quantity — and up to 27 custom parameters in addition. A custom parameter, such as color, needs an item-scoped custom dimension before it can be reported on; sending it alone is not enough.
  5. Check it in DebugView. Turn on debug mode, trigger the event, and open DebugView (Admin, then Data display, then DebugView). Expand the event and check the items array: two items, each with item_id, item_name, price, and quantity, and the value 72.05. An item missing its ID or name shows up here before it breaks a report.

Dead ends

DEAD END — THE ITEM WITH NEITHER ID NOR NAME. An item object with a price and a quantity but no item_id and no item_name is unusable in reports: there is nothing to group it by. The Ecommerce purchases report shows it as (not set), and no fix after the fact can attach a name to it. The ID or the name must be in the push.

DEAD END — THE 201ST ITEM. The array limit is 200 elements. An order past that limit loses its tail silently: no error, no warning, just missing items in the report. Orders that large are rare on a retail site, but a wholesale cart can hit the limit without anyone noticing.

DEAD END — QUANTITY AS TEXT. A quantity sent as the string "3" instead of the number 3 breaks the multiplication that value depends on. Numbers in the items array — price, quantity, discount — must be numbers, not quoted strings.

End state

Every ecommerce event carries an items array of at most 200 items, each with item_id and item_name, a numeric price and quantity, and at most 27 custom parameters besides the prescribed ones. The worked order has two items: three tees at 30.03 and two grey tees at 42.02, for a value of 72.05. DebugView shows the array the same minute, and after about 24 hours the Ecommerce purchases report lists both items by name.

Sources

Checked 11 November 2026. The rules above are the ones in Google's ecommerce developer guide and the recommended events reference, both opened 11 November 2026. No step was run inside a live Analytics property, because that needs a Google sign-in and this site does not sign in as anyone. The figures were recomputed in Python: 10.01 × 3 = 30.03, 21.01 × 2 = 42.02, and 30.03 + 42.02 = 72.05. The reference file was checked the same way.