What's in a Name? Square Items ☕ vs Shopify Products 📦

In an API, a name is more than just a label. It is part of the interface. It tells developers what they are looking at, what role it plays, and how they should expect it to behave. Developer experience is largely shaped by the names and terms used in APIs, and clarity is more important than brevity at the point of use.

That is why naming choices often last long after the initial discussion. Once a word becomes part of an API, developers form a mental model around it. They write code based on it, explain it to teammates, and link it to their own product concepts. Research on API usability supports this idea: APIs are designed for programmers, and their usability impacts developer productivity, adoption, and code quality.

Square famously refers to sellable items as Items, while much of the commerce industry calls them Products. At first glance, both terms refer to similar concepts: the things being sold. However, the names carry different assumptions.

I favor Product.

Here's why.

Before I continue: I'm working on Flint Pay, a headless commerce payment API, and I regularly write about the product and technical decisions around building it. Follow me if that interests you.

Why Did Square Pick "Item"?

I worked at Square for four years. The original reason behind choosing "Item" may be lost to time, but I would love to hear it if anyone knows. My guess is that Square used the term to create a general commerce layer that fits in-person POS, ecommerce, restaurants, retail, services, and other areas.

That makes sense. "Item" is flexible enough to describe a coffee, a haircut, a shirt, a menu entry, or a custom charge. Square's own documentation describes the Catalog API as covering products or services, including items, variations, categories, discounts, taxes, modifiers, and more. Square also says an item library entry for a product or service is called a catalog item.

So, "Item" is not a bad name, just a broad one. It reflects Square's wide point-of-sale perspective. Square was not modeling ecommerce catalogs; it was capturing the messy reality of local commerce.

In contrast, Shopify and Stripe lean into Product, reflecting their ecommerce-first focus. Shopify's docs center products in merchant catalog management, and Stripe says products define what a business offers, while prices specify how much and how often to charge.

That difference matters because a name subtly shapes the model built around it based on our own biases and understanding of what a word means.

The Tradeoff

"Product" suggests more intent; it implies something is offered for sale. "Item" offers more flexibility and can apply to various industries and workflows.

However, flexibility has its costs. Google's API naming guidance advises using familiar terms, keeping names consistent for the same concept, and avoiding overly general names that can become ambiguous as the API expands.

That is the central tradeoff: "Item" is more flexible at first, while "Product" is clearer as the API grows. For a generic commerce API, I would prefer starting with the term that best captures the domain concept.

"Item" Is Overloaded

Many things are referred to as items in everyday conversation, and not all relate to the thing being sold. This becomes especially confusing in commerce because line item does not mean "an Item."

A line item refers to a transactional row: a purchased item along with details like quantity, price, discounts, taxes, fulfillment status, or subscription context. Stripe invoice line items carry invoice-scoped pricing, quantity, tax, discount, and invoice context. Shopify defines a Line Item as a single product or service purchased in an order, including details like variant, quantity, pricing, discounts, and fulfillment status.

That represents a different concept from the catalog object itself. The confusion arises quickly:

{
  "items": [
    { "id": "itm_123", "name": "Premium Hoodie" },
    { "id": "itm_456", "name": "Premium Hoodie" }
  ]
}

Are these catalog items or order line items? Is id the ID of the sellable item, or the ID of a specific row in a cart, checkout, invoice, or order?

Now consider an order object:

{
  "order": {
    "id": "ord_123",
    "items": [
      { "id": "itm_456", "item_id": "itm_123", "quantity": 2 }
    ]
  }
}

What does id refer to here? What about item_id? You can document this to clarify, but the name itself complicates understanding.

Now look at a model that separates the concepts:

{
  "order": {
    "id": "ord_123",
    "line_items": [
      { "id": "li_456", "product_id": "prod_123", "quantity": 2 }
    ]
  }
}

This is less clever and more straightforward.

A Product is the sellable definition.

A Line Item is the transactional occurrence.

This distinction appears naturally in orders, invoices, checkouts, carts, quotes, and subscriptions, and it reflects how major commerce APIs typically model the world. Stripe's product model works across Checkout, invoices, quotes, subscriptions, and custom integrations, while invoice line items remain tied to their respective invoices.

A product is what is being offered. A line item is what is being purchased in a specific context. These terms should not compete for the same name.

Language Naturally Falls Back to "Product"

When speaking with Square sellers, I often heard people say "Square products" instead of "Square items"; almost as much as we got confused for Squarespace. This mistake occurs often enough that it signals something important. If users naturally choose a different word than the one in your API, it may be creating friction.

This aligns with a common UX principle: systems should use the user's language, employing familiar words and concepts rather than terms specific to the system. Nielsen Norman Group's guideline about "matching the system with the real world" typically arises in product interfaces, but it is equally relevant for developer interfaces. Developers are users too.

This doesn't mean "Product" is always the correct choice. However, if the domain already has a familiar, more precise term for the concept, the API needs a strong reason to use something different.

"Product" Better Captures Sellable Intent

"Item" can refer to a row, an object, a physical unit, a menu entry, an inventory record, a task, or something on a list. "Product" is more specific; it denotes a sellable offering. It doesn't have to describe a physical good.

That is the meaning I want in a commerce API. A product can be a hoodie, a haircut, a subscription tier, a donation, a membership, a digital download, an event ticket, a usage-based entitlement, or a professional service. It is not about being physical; it is about being the item offered for sale.

The API Should Teach the Model

Good naming minimizes the need for explanation. A commerce API includes many related terms: product, price, variant, SKU, inventory unit, cart, checkout, order, invoice, subscription, fulfillment, refund, return, adjustment, discount, tax, fee, and line item. The more terms you introduce, the more burdensome an overloaded term becomes.

If everything is an item, developers will constantly ask what kind of item they are dealing with:

item
order_line_item
invoice_item
subscription_item
cart_item
catalog_item
inventory_item

Some of these may be valid concepts. But together, they create a vocabulary where the most crucial term is overloaded.

With Product, the model is clearer:

product
product_variant
price
order_line_item
invoice_line_item
subscription_item
inventory_unit

Not every naming issue disappears. But the main distinction is easier to maintain: a Product is the definition; a Line Item is the occurrence. That is the model I want developers to grasp by reading the API, not through memorization.

What's in a Name?

For Flint Pay, I chose to rename Items to Products. The goal is a clearer API surface: catalog objects are products, transactional rows are line items, and developers do not have to wonder which type of "item" they are working with.

Square's choice of "Item" fits its needs: flexible, broad, and aligned with a point-of-sale view. But Flint Pay does not aim to accommodate every possible interpretation of the word "item." It seeks to clarify the commerce model.

Names shape the mental model of an API. In this case, Product provides a clearer understanding.

AI Disclaimer

I write and source all my articles text and ideas myself. However, if you know me, I'm very verbose and I brain dump too much, which doesn't create good articles. I use AI to condense my writing while still keeping everything else intact. The article images are also sometimes AI generated.