Product Attributes

When we designed the shop API, we kept the product simple. A product has a name, a description, a price, and a quantity in stock. We did not record details such as size or color, even though many kinds of products have them. This kept the design small while we worked on the API.

A developer who deploys their own copy of the shop API could change the code to record the details their merchant needs. On Shopend, every merchant uses the same backend, so that one backend must record the details of every merchant’s products. These details differ by kind of product. For example, a mug has a capacity and a glaze, and a shirt has a size, a color, and a fabric.

We cannot know these details in advance. A new merchant may sell something no merchant has sold on Shopend before. So each merchant defines the details of their own products. We call each detail an attribute. An attribute has a name and a value, such as glaze: speckled, fabric: cotton, or scent: cedar.

Within each shop, the functional requirements of the shop API still hold. We add these:

• When a merchant adds a product, the API must record any number of attributes the merchant defines, in addition to the product’s name, description, price, and quantity in stock.
• A merchant must be able to add, change, and remove a product’s attributes.
• A shopper must be able to read a product’s attributes.

Some details, such as size and color, affect price and stock. Suppose threadline sells a linen shirt in three sizes, small, medium, and large, and in two colors, white and blue. That makes six combinations. The merchant counts stock for each combination separately, because selling a blue medium shirt does not reduce the number of white large shirts. The merchant may also charge more for some combinations.

A shopper expects one product page for the linen shirt, with a menu for size and a menu for color. The shopper picks a size and a color, and puts that combination in the cart. Commerce platforms support this by grouping the combinations into one product. Each combination is a variant of the product, and each variant has its own price and stock.

With variants, price and stock belong to the variant instead of the product. A cart item would name a variant, not a product, and placing an order would reduce the stock of each variant. That changes the carts, the orders, and the GraphQL types we designed for them. We leave variants out of this version. On Shopend, each combination is a separate product with its own price and stock, such as a blue linen shirt in medium. Its size and color are recorded as attributes, size: medium and color: blue.