A custom hat checkout on Shopify that can't undercharge

A variant already says the style and the color, so the line item doesn’t repeat them. Everything else production needs rides along as custom attributes on each line: the decoration method, a link to the customer’s original logo file as the print file, the logo width and a link to the mockup the customer approved.

A few of those rules came from thinking about the people on the floor. The mockup’s label says it’s a mockup, so nobody produces from it. The width is rounded down to the tenth of an inch, never up, so 2.45" can’t reach production as 2.5". An advisory that the artwork may be too fine for the chosen method goes on a key that starts with an underscore (_Detail Advisory), because Shopify shows those properties in the admin and hides them from the customer’s checkout and emails. And every line carries the whole set, since production works each line on its own and a note that appears under only one hat reads as being about that hat.

Staff click these links to fetch artwork, so the server checks that every URL on the order points at the app’s own UploadThing storage. Otherwise anyone posting to the endpoint could plant a link of their choosing in the merchant’s admin.

The checkout request carries a product handle, a variant ID and a quantity for each hat, plus the design. It has no price field. Whatever the page displayed, the server works out the charge again from Shopify, in this order:

1. Each handle has to be one of the styles the builder sells, and each variant ID has to look like a Shopify variant ID.
2. Quantities are checked against the order rules (more on those below). A failure here is a 400 with a reason.
3. Every variant is fetched in one Admin GraphQL nodes(ids:) call. Each one has to belong to the product its line names, which stops a client from sending a cheaper variant from some other product. A style the merchant has just set to draft is refused with a 409, even for a customer whose page loaded before the change.
4. The variant prices go through resolveCheckoutPricing, which picks the volume tier and builds the discount for each line.

That last step fails closed. A variant price under $1 or over $1,000 is treated as a catalog mistake, since a hat priced at $0.01 is almost certainly a typo in the admin. A discount that would bring a hat to zero or below, or a quantity with no matching tier, fails too. Any of those stops the checkout with a 409 and a message telling the customer the item is temporarily unavailable. The server logs a checkout.pricing_guard_tripped event with each line’s variant price and quantity, and sends Sentry a warning. The event has its own name so a Datadog monitor can watch for it alone. If it fires, a sale was blocked that would otherwise have been charged wrong.

The builder and the checkout route call the same function, calculateOrderPrice, to get the number. The builder shows it and the route charges it, so the two can’t drift apart.

The first version kept the tier prices in code: $17 a hat at 12, $16 at 24, $15 at 50. That meant a price change in the Shopify admin did nothing until a developer changed a file. In June we turned it around. The base price is now whatever the variant costs in Shopify, and the code only holds the volume discount: nothing off from 12 to 23 hats, $1 a hat from 24 to 47, $2 a hat from 48 up. Billest moved the top tier from 50 to 48 in August, which was a two-line change.

The discount goes on each line as a fixed amount per hat. We started with a percentage and it broke at checkout. Shopify accepts at most two decimal places in appliedDiscount.value, and $1 off a $17 hat is 5.88235…%, so every order in the 24+ tier failed with a decimal error. A FIXED_AMOUNT discount of $1 is exact. Shopify multiplies it by the line’s quantity and the totals come out to the cent.

Draft orders also skip a shop’s automatic discounts unless they’re asked to apply them. A customized order was missing Billest’s free shipping at 24 hats until we set acceptAutomaticDiscounts, and in November we added allowDiscountCodesInCheckout so customers can type a promo code on the invoice checkout. Both apply on top of the volume tier. The builder can’t see a code the customer hasn’t typed yet, so the price it shows is the price before codes. Shopify also doesn’t support free-shipping or buy X get Y codes on draft orders.

In September the builder started taking orders of several hats with one logo, in any mix of styles and colors, up to 20 lines. It all goes into one draft order. The volume tier comes from the order’s total, so 12 of one style and 12 of another are both priced as 24.

The minimum took a second pass. We first applied the 12-hat minimum to the whole order, which let a customer add 2 hats in a second style. Billest pointed out that every style change is a new machine setup, so in October the minimum moved to each style. Colors of one style share it: 7 black and 5 white of the same hat is fine, while 12 of one style and 2 of another is refused.

validateOrderQuantity is the rule, and the builder and the server both call it. The builder uses it to stay ahead of the customer. A hat in a new style starts at 12, another color of a style already in the order starts at whatever that style is short, and a style’s only hat can’t go below 12. When a style is short, the order list says which and by how much (“add 4 more hats of Ozark”). The server runs the same check, so a stale tab or a hand-built request gets a 400.

Lines for the same variant are merged into one, since the builder lets a customer pick the same color twice. That merge runs after the quantities are checked, so two lines of 6 for one hat can’t pass as a style that met its minimum. The decoration method is the order’s too. A method withdrawn on one style (DTF on a hat with a seam down the front panel) is withdrawn for the whole order, since every hat gets the same design.

To be clear, the app has no automated test suite. Pricing changes have been checked by hand and by script, and that’s a real gap for code that decides what a customer pays. When we moved checkout to multiple hats, we ran the old route and the new one against the same fake Shopify client. For 24 single-hat orders covering the tiers, notes, background removal and old request shapes, the draftOrderCreate input came out identical, and 14 invalid requests got the same status and message as before. Then we placed an order of 24 hats in three styles on Billest’s development store, and Shopify’s checkout showed $16 a hat on every line and a $384 subtotal. That was two weeks before the per-style minimum, and the same order (12, 10 and 2) would be refused today.

Every way the route can say no is logged. A refusal writes checkout.rejected with a reason code, and a created order writes the subtotal and each line’s price and discount, so a “you charged me wrong” email can be answered from the logs without opening the Shopify admin. The invoice URL is never logged, since anyone holding it can pay the order, and only the length of a customer’s note is logged, since a note can hold a phone number.

Admin API calls retry on Shopify’s throttling, which arrives as an HTTP 200 with a THROTTLED error that a status-code check misses. Creating a draft order isn’t idempotent, though. If the connection drops after Shopify has made the order, the builder can’t tell, so it doesn’t offer a free retry. It tells the customer to check their email for an invoice first.

The builder went live on billest.com the week of August 17, 2026. Three days later Billest told us they’d had 13 orders through it without marketing it at all.