We’re building an integration for restaurants that receive orders from delivery platforms (DoorDash, Grubhub and similar). The customer has already paid the delivery platform. Our integration creates an order on the merchant’s Square account so a kitchen ticket prints at their station.
I’ve found the existing answer that orders with a fulfillment print immediately for ASAP orders, and that SCHEDULED orders print at pickup_at minus prep_time_duration — that’s very helpful and answers the core mechanism.
Three follow-up questions:
1. Our orders arrive already paid elsewhere. Does the order need to be paid — including recording a $0 EXTERNAL payment — before the fulfillment triggers printing? Or does an unpaid order with an ASAP fulfillment print on creation?
2. Is there any way for our integration to determine whether a merchant has automatic order-ticket printing enabled, so we can prompt them to turn it on during setup? And is there any signal we can read afterwards to know whether a ticket actually printed, or failed to?
3. Do orders created via the Orders API route through the merchant’s printer profiles the same way Square Online orders do, or is there a particular setting or order attribute they need for this to work?
Context for why question 2 matters: if a merchant hasn’t enabled automatic printing, from our side everything looks successful — the order was created without error — but no ticket reaches the kitchen. We’d like to catch that during setup rather than hearing about it from a restaurant during service.
Fulfillment alone won’t trigger a print; the order also needs a zero balance. A $0 EXTERNAL payment won’t do it, so record an EXTERNAL payment for the full order total since the customer already paid an external source. Once the balance hits zero, the order goes to Order Manager and the print flow.
No. Nothing in the API reads or writes printer profiles or the auto-print setting, and there’s no webhook or order field for ticket printed, failed, or out of paper.
Same profiles. Orders API orders aren’t treated as a separate channel from Square Online for printing, and no special source name or order attribute is needed. Just put the order on the location where the kitchen printer is set up, with a PICKUP fulfillment, and pay it.
Also note that DELIVERY fulfillments are limited to certified partners, so use PICKUP fulfillment types to denote deliveries.
Thanks again, jseok. That answer saved us a lot of guesswork.
One follow-up, now that we’ve tested in the sandbox. Your answer covered a $0 EXTERNAL payment against a priced order, and the sandbox agrees: CreatePayment rejects it with ORDER_TOTAL_MISMATCH.
Our question is about a different case: an order whose total is already $0 before any payment. We’d create the order with line items that reference the seller’s own catalog items (so they route to the right kitchen stations), plus a 100% order-level discount, so total_money is 0. It has a PICKUP fulfillment. We then call POST /v2/orders/{order_id}/pay with no payment_ids. In the sandbox this returns 200, net_amount_due_money is 0, and a second pay call is refused as already paid. No EXTERNAL payment is involved.
Does an order settled this way go to Order Manager, the kitchen printer and Square KDS (routed to stations by its catalog items), the same as an order paid in full with an EXTERNAL payment? Or does that flow require an actual payment record?
This matters because the customer has already paid the delivery platform, so we’d prefer not to record a payment on the seller’s books for money that never passed through their Square account.
A smaller related question: if a line is ad-hoc (a name and price, no catalog_object_id), how does Square KDS route it? To a default station, to every station, or not at all?
I do want to note that an EXTERNAL payment doesn’t credit any money to the seller’s Square account. It’s meant to be a bookkeeping record that money was collected elsewhere, and the proceeds never touch their Square balance or deposits. Square’s External Payments guide covers this, and its first example is a food order paid through a courier service, which is your case.
On your actual question: yes, PayOrder with an empty payment_ids array on a $0 order is documented and supported. The order should route to the correct Order Manager and KDS as expected.
As for your other question, the ad-hoc items will route to the KDS based on its individual settings - ad-hoc items are considered uncategorized, so if the KDS is configured to receive uncategorized items, it will display those items.
Good to know on EXTERNAL payments. For our case we’re going with the $0 route you confirmed: catalog-priced line items, a 100% order-level discount, PICKUP fulfillment, and PayOrder with an empty payment_ids array. It’s working as expected in sandbox.
And thanks for the KDS detail. We’ll link items to the seller’s catalog wherever we can, and tell sellers to enable uncategorized items on their KDS for anything that can’t be linked.