> ## Documentation Index
> Fetch the complete documentation index at: https://storekit.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Custom Kitchen Ticket on a Star Cloud Printer
> Print a custom kitchen ticket with an allergen banner, big order code and station sections on a Star CloudPRNT printer driven by an order.created webhook.
storekit prints a fixed kitchen ticket. This recipe gives you a second ticket, laid out however you like, on a Star printer that your own app drives. storekit's printing and dashboard carry on exactly as before.
There is no custom ticket template editor in the storekit dashboard, and the layout of storekit's own tickets cannot be changed. This recipe works around that with a printer that storekit does not know about. Read [What This Does Not Do](#what-this-does-not-do) before you buy hardware.
## How It Works
1. A guest places an order. storekit sends `order.created` to your app.
2. Your app turns the order into a ticket in your layout and puts it in a print queue.
3. A Star CloudPRNT printer, configured to point at your app instead of storekit, polls the queue every few seconds, prints the ticket and confirms it.
Everything in step 2 and 3 runs in the app the AI builder makes for you. Star's CloudPRNT protocol is public and simple — the printer asks "anything to print?" over HTTP, your app answers — so builders handle it well when given the rules below.
## What You Need
* Webhooks enabled on your storekit plan (**Settings** → **Developers**).
* A Star Micronics CloudPRNT printer that is **not** connected to storekit: a TSP100IV, mC-Print2, mC-Print3 or SP742 with the CloudPRNT firmware. If you already have one of these connected under **Direct Printing**, you need a second one — a printer can only poll one server.
* The printer's web configuration page, reached by its IP address on your network (see the printer's manual for how to print its network settings).
* A [Replit](https://replit.com) account. This recipe needs a public URL that stays up 24 hours a day plus a small database, which Replit provides. Lovable or Bolt work if you attach a backend; see [Choosing a Builder](/docs/guides/build/prompting-guide#choosing-a-builder).
## Step 1: Build the App
Paste the whole of the block below into the builder in a single message. Edit the section marked **MY TICKET LAYOUT** first — that is your layout, and the example is only a starting point.
Either button opens the builder with the whole prompt below already filled in. Nothing starts until you press send, so read it through and edit the parts marked as yours first.
```text theme={null}
I want a small web service that prints a custom kitchen ticket for every order I receive on storekit, on a Star CloudPRNT receipt printer that I own. It runs unattended in a restaurant kitchen, so it has to be reliable and boring: it must never print an order twice, never lose an order if it restarts, and never make storekit wait.
Two things talk to this service: storekit (sending me orders by webhook) and my Star printer (polling for jobs). Nobody else uses it, apart from me checking an admin page occasionally.
Build it with a database so the queue and the history survive restarts and redeploys. It needs an always-on public HTTPS URL.
```
```text theme={null}
CONTEXT ABOUT STOREKIT
I run a hospitality business on storekit (storekit.com), an online ordering and payments platform for restaurants, cafés and bars. storekit can notify my own app about things that happen in my store by sending webhooks.
How storekit webhooks work:
- Each event is an HTTP POST with a JSON body to a URL I register in the storekit dashboard.
- The body always has the shape { "event": "", "data": { ... } }.
- Requests are signed with Svix. Every request carries the headers svix-id, svix-timestamp and svix-signature. Verify them with the official `svix` library for your language, using a secret I will provide in an environment variable called STOREKIT_WEBHOOK_SECRET. Reject anything that fails verification with HTTP 400.
- My endpoint must respond with a 2xx status within 15 seconds. Save the event to the database first, respond 200, then do the work from the saved copy.
- Once I have responded 200, storekit will not send that event again, so the work must not be lost: store each event with a status (pending, done, failed) and only mark it done after the work has actually succeeded. On startup and on a timer, pick up anything still pending or failed and retry it. Never do the work only in memory after responding.
- The same event can occasionally be delivered more than once. Use the svix-id header as the unique key for the saved event: a repeat of an event already saved is ignored, whatever its status.
- Any page or endpoint protected by a password must be served over HTTPS only; redirect or refuse plain HTTP.
- Money fields (total, tip, deliveryFee, discountTotal, item price, modifier price) are integers in minor units: 2500 means £25.00.
- orderType is one of Delivery, Pickup, InStore, Curbside, CateringDelivery, CateringPickup or Billpay.
- table and deliveryAddress can be null. notes can be null or empty.
Example order.created payload:
{
"event": "order.created",
"data": {
"id": "ord_abc123",
"code": "A1B2",
"asap": true,
"total": 2500,
"tip": 250,
"deliveryFee": 299,
"discountTotal": 0,
"orderType": "Pickup",
"createdAt": "2024-01-15T10:30:00Z",
"deliveryTime": "2024-01-15T11:00:00Z",
"notes": "Ring doorbell",
"customer": {
"firstName": "John",
"lastName": "Doe",
"email": "john@example.com",
"phone": "+44123456789",
"marketingConsent": true
},
"items": [
{
"name": "Margherita Pizza",
"price": 1200,
"quantity": 1,
"plu": null,
"posId": null,
"taxRate": null,
"modifiers": []
}
],
"venue": {
"id": 1234,
"name": "My Restaurant",
"slug": "my-restaurant",
"address": {
"street1": "123 Main St",
"street2": "",
"city": "London",
"postCode": "W1A 1AA",
"country": "UK",
"companyName": "My Restaurant Ltd",
"coordinates": { "latitude": 51.5074, "longitude": -0.1278 }
}
},
"table": {
"id": "tbl_123",
"name": "Table 5",
"covers": 4,
"posId": "pos_tbl_5",
"area": { "id": "area_1", "name": "Main Floor", "posId": null }
},
"deliveryAddress": {
"street1": "456 Oak Ave",
"street2": "Flat 2",
"city": "London",
"postCode": "E1 6AN",
"country": "UK",
"coordinates": { "latitude": 51.5155, "longitude": -0.0722 }
}
}
}
The full list of event types and payloads is at https://storekit.com/docs/developers/webhooks/webhook-events
```
```text theme={null}
THE PRINTER: STAR CLOUDPRNT PROTOCOL
My printer is a Star Micronics printer with CloudPRNT. I will type this service's URL into the printer's configuration page, and the printer will then poll it. Implement the server side of Star's CloudPRNT HTTP protocol at the path /cloudprnt/, where PRINTER_TOKEN is a long random secret from an environment variable. Tickets contain customer details, so any request to /cloudprnt whose token segment does not match must get 404 and nothing else. Below I write /cloudprnt for short; always include the token segment.
- The printer POSTs a small JSON status object to /cloudprnt every few seconds. Respond with JSON. When there is nothing queued respond { "jobReady": false }. When there is a job respond { "jobReady": true, "mediaTypes": ["text/plain"], "jobToken": "", "deleteMethod": "DELETE" } — only ever hand out the job at the front of the queue.
- The printer then GETs /cloudprnt?type=text/plain&token= (it may also send mac or uid query parameters; ignore them). Respond with the ticket body as plain text, Content-Type text/plain. GET must be repeatable: return the same job again if asked, do not remove it from the queue.
- After printing, the printer sends DELETE /cloudprnt?token=&code=. The code is a URL-encoded result: "200 OK" (or a code starting with 2) means it printed — mark the job printed and remove it from the queue. Any other code means the printer could not print it — mark the job "failed" with that code, remove it from the queue so the printer is not stuck on it, and leave it in the admin page so I can reprint it. DELETE must be idempotent: a repeat for a job already confirmed is fine, respond 200.
- Never automatically re-queue a job the printer has fetched but not confirmed: the printer may have printed it and only lost the confirmation, and re-queueing would print it twice. Keep it in a "printing" state under its original token. If it has been in that state for more than 2 minutes, show it as "unconfirmed" in the admin page with a Reprint button, and let me decide.
- Keep the whole poll cycle under a second; the printer polls constantly.
- Star publishes the protocol at https://star-m.jp/products/s_print/sdk/StarCloudPRNT/manual/en/protocol-reference/index.html — follow it where it differs from my summary.
Use plain text jobs. Take the line width from a COLUMNS environment variable: 48 for an 80 mm thermal printer (TSP100IV, mC-Print3), 42 for an SP742, or 32 for a 58 mm printer (mC-Print2), in the printer's default font. Every rule below that says 48 means COLUMNS. Use only ASCII characters. End every ticket with six blank lines so the paper feeds far enough to tear off.
WHAT TO BUILD
1. POST /webhooks/storekit — the storekit endpoint. Verify the Svix signature using the official svix library and the STOREKIT_WEBHOOK_SECRET environment variable, against the raw request body. Return 400 if verification fails. Return 200 immediately once the event is saved, before rendering or printing anything. Ignore any svix-id you have already saved. Handle the event type order.created; store and acknowledge any other event type but do nothing with it.
2. A renderer that turns an order.created payload into a ticket using MY TICKET LAYOUT below, and adds the ticket to the print queue.
3. The /cloudprnt endpoints described above, backed by the queue in the database.
4. GET /admin — a single page, protected by HTTP basic auth using ADMIN_PASSWORD, listing the last 50 tickets with order code, time, status (queued / printing / unconfirmed / printed / failed with the printer's code) and a Reprint button that queues the same ticket again. At the top, show when the printer last polled and a green/red indicator: red if it has not polled in the last 60 seconds. Also a Print test ticket button that queues a ticket with fake data so I can check the layout without a real order.
5. GET /health that returns 200 and { "ok": true } and nothing else; keep the queue length and last poll time on /admin only.
MY TICKET LAYOUT
Render every ticket exactly like this. Lines are COLUMNS characters wide (48 in the examples). Centre text where shown. Use rows of = and - characters as separators. Where I write UPPER CASE below I mean print it in upper case.
- Line 1: a full row of =
- Line 2: the order code (data.code) centred, printed on its own line and repeated on the next line so it stands out (my printer cannot do large fonts in plain text, so repetition is the emphasis).
- Line 3: the order type, centred, mapped exactly like this: Delivery -> "DELIVERY", CateringDelivery -> "CATERING DELIVERY", Pickup -> "PICKUP", CateringPickup -> "CATERING PICKUP", Curbside -> "CURBSIDE", InStore -> table.name in upper case (e.g. "TABLE 5") or "IN STORE" if table is null, Billpay -> "BILL PAYMENT", anything else -> the raw value in upper case. For Delivery and CateringDelivery, then print on following lines the delivery address (deliveryAddress.street1, street2 if not empty, postCode) and customer.phone.
- Line 4: "Ordered " from createdAt in the venue's local time. If asap is false, add "FOR " from deliveryTime on the same line, right-aligned. If asap is true, add "ASAP" instead.
- Line 5: a full row of -
- Then the items. For each item: quantity, space, item name in upper case, e.g. "2 MARGHERITA". Underneath, each modifier indented by five spaces with a leading "- " e.g. " - Extra basil". If an item has a notes field with text in it, print it indented under its modifiers prefixed with "** ". One blank line between items.
- Then a full row of -
- If data.notes or any item's notes contains the word "allergy" or "allergic" (any case), print three lines: a row of !, then "!! ALLERGY - SEE NOTES !!" centred, then a row of !. Then print data.notes in full when present, wrapped to 48 characters. If data.notes is present but nothing mentions allergies, print "Notes:" followed by the wrapped notes. If there are no order notes, print nothing else here.
- Then a full row of -
- Then the customer's first name and last initial only ("Jane D."), the item count ("3 items") and the total formatted from minor units with the currency code from a CURRENCY environment variable ("Total 25.00 GBP"). Do not guess a default: if CURRENCY or TIMEZONE is unset, refuse to start and log a clear message. No email, no full surname.
- Last line: a full row of =, then six blank lines.
DEFINITION OF DONE
- [ ] A signed order.created event queues exactly one ticket, and returns 200 in under one second.
- [ ] The same event sent twice queues one ticket, not two.
- [ ] A request with a bad signature returns 400 and queues nothing.
- [ ] /cloudprnt returns jobReady false when the queue is empty and hands out one job at a time when it is not. A wrong PRINTER_TOKEN gets 404.
- [ ] A DELETE with a non-success code marks the job failed, not printed, and it can be reprinted from /admin.
- [ ] A job fetched but never confirmed is shown as unconfirmed, and is not printed again unless I click Reprint.
- [ ] Restarting the service does not lose queued or historical tickets.
- [ ] /admin shows tickets, printer status and allows reprints and a test ticket.
- [ ] The example payload in the context renders with a PICKUP line, "1 MARGHERITA PIZZA", "Notes: Ring doorbell", "John D." and "Total 25.00 GBP", and no allergy banner.
- [ ] A payload whose notes read "Severe nut allergy" renders the allergy banner.
WHAT TO GIVE ME WHEN YOU ARE DONE
1. The public URL of the service, and the exact two URLs I will paste: the storekit webhook URL (…/webhooks/storekit) and the printer URL (…/cloudprnt/).
2. The environment variables I must set (STOREKIT_WEBHOOK_SECRET, ADMIN_PASSWORD, PRINTER_TOKEN, COLUMNS, CURRENCY, TIMEZONE for the venue's local time, and anything else you added) and where to set them on this platform.
3. How to confirm it is running always-on, not sleeping between requests.
4. A one-paragraph explanation of how to test it end to end before I connect the real printer.
```
The builder will ask questions or hand back a working app. Fix problems by pasting the exact error, following [When the Builder Gets It Wrong](/docs/guides/build/prompting-guide#when-the-builder-gets-it-wrong). Before moving on, open `/admin`, click the test ticket button, and read the rendered ticket text in the queue — you can adjust the layout with follow-up messages now, before a printer is involved.
## Step 2: Connect storekit
In the dashboard sidebar, go to **Settings** → **Developers** and click **Manage Webhooks** (it reads **Enable Webhooks** the first time). Webhooks are a subscription feature — if you see **Upgrade to enable webhooks**, [contact support](/docs/getting-started/contact-support) first.
In the embedded portal, add a new endpoint, paste the webhook URL your app builder gave you, and tick only the event types the recipe needs.
Open the endpoint you just created and copy its signing secret. In your app builder, save it as the environment variable `STOREKIT_WEBHOOK_SECRET` (builders call this "secrets" or "environment variables"). Redeploy if the builder asks you to.
Use the portal's test option on the endpoint to send a sample event. The delivery log shows the response code from your app. A `2xx` means your app accepted it; anything else, read the response body in the log — it is usually a missing secret.
Tick only `order.created` for this endpoint. The webhook URL is the one ending in `/webhooks/storekit`.
## Step 3: Point the Printer at Your App
Print the printer's network settings (the method varies by model — typically holding the feed button while powering on) and open the IP address shown in a browser on the same network.
On the printer's web page (Star's interface, not the storekit dashboard) find the CloudPRNT settings and enable them. Enter the printer URL your builder gave you (the one containing `/cloudprnt/` followed by a long token — keep that token private, it is what stops anyone else reading your tickets) as the server URL, set a polling interval of a few seconds, and save. The exact field names vary by model and firmware; Star's manual for your printer is the reference.
Reload `/admin`. The printer indicator turns green as soon as the first poll arrives. If it stays red, the printer cannot reach your URL — check that the URL is `https://`, that you saved the settings, and that the printer has internet access.
Click the test ticket button on `/admin`. The printer picks it up on its next poll.
Order something small on your own storefront. A ticket in your layout should print within a few seconds of the order confirmation.
## Ideas for Your Layout
Once the basic ticket prints, the layout is a follow-up message to the builder away:
* **Station sections**: group items by category into GRILL / COLD / DRINKS blocks, or queue a separate ticket per section.
* **Allergen matrix**: print a row of allergen abbreviations under each item from the item name or a lookup table you maintain in the admin page.
* **Course markers**: print a "---- MAINS ----" divider based on category.
* **Collection time countdown**: for pre-orders, print "READY IN 45 MIN" from the requested time.
* **Two copies**: queue the ticket twice — one for the pass, one for the driver.
## What This Does Not Do
* **It does not change storekit's ticket.** storekit prints to the printers under **Direct Printing** as before. If you want only your custom ticket, remove the printer from **Direct Printing** and point it at your app instead — but then storekit no longer knows the printer exists, so **Printers** status, `printer.status.offline` alerts and storekit's print log do not apply to it.
* **It is your service.** storekit support can confirm an `order.created` delivery reached your URL and what response it got; they cannot see or fix the app. If it stops printing, start at `/admin` and the delivery log in the webhooks portal.
* **Cancellations are not printed** unless you add them: `order.canceled` is a separate event, and a "CANCELLED" ticket is a natural next follow-up prompt.
* **Plain text only.** Logos, barcodes and large fonts need Star's binary formats, which the builder can add later if you ask for `application/vnd.star.starprnt` support.
## Related
The structure behind this prompt, and what to say when the builder gets it wrong.
storekit's own printing, including how to connect a Star CloudPRNT printer to storekit.
Every field available for your layout.
What the builder is doing when it checks the Svix headers.
## Related topics
- [6. Connect a cloud receipt printer](/docs/getting-started/launch/connect-printing.md)
- [Set up a Star Micronics cloud printer](/docs/guides/printing/printer-setup.md)
- [Troubleshoot Star printer connectivity and order printing](/docs/guides/printing/troubleshooting.md)
- [Build Your Own Tools on storekit](/docs/guides/build/overview.md)
- [Order Batching](/docs/guides/orders/advanced/order-batching.md)
Build with Lovable