Orders API Requirements
Partner applications that use Square APIs to enable sellers to take payments must also use the Orders API. The App Marketplace requirements described in this topic apply to partner applications that use the Orders API.
On this page
The Orders API enables partner applications to capture itemized purchase details and link the details to payment information.
At a minimum, partners must explicitly create a Square order (using the Orders API), use ad hoc line items, and supply the order ID when making a payment using Square APIs. This enables sellers to reconcile order details in the Square Seller Dashboard and allows data to flow into third-party reporting and accounting partners.
Additionally, the following recommendations apply:
Instead of ad hoc items, partners should use Square catalog objects (with their Square catalog object ID) so that sellers can benefit from Square's inventory tracking features. After an order is paid, Square automatically adjusts the inventory.
Any taxes, fees, discounts, or other surcharges must be itemized on the Square order. Tip amounts can be added and adjusted using the Payments API.
A created order must be either paid (a successful payment attached to the order) or canceled (the order status set to CANCELED). Partner applications must ensure that there are no orphan orders.
If a partner (for example, a food delivery service) wants to leverage Square Order Manager (for example, see Order Manager in Square POS), the partner must configure an
OrderFulfillment and set it in the order. In the
OrderFulfillment, details such as fulfillment type (Pickup vs. Shipment) and Recipient Details (such as name, address, and phone number) must be provided.
In the current implementation, orders with
OrderFulfillment must be paid using the Square Payments API before they are surfaced in the Square POS systems.
Square requires all partners to properly manage
OrderFulfillment states. For example, when a shipment order is fulfilled and sent to the customer, the partner must mark the
OrderFulfillment as complete. If no fulfillment remains on the top-level
Order object, the top-level
Order must also be marked as complete.
Partner applications must either listen to order webhooks or poll for order updates and surface any relevant information in the partner platform or to the buyer.
Partner applications seeking to pull historical and current transaction data must use the Orders API (for example, the
SearchOrder endpoint). The
Order object tracks the order itemization, payment details, and refunds.
For example, accounting integrations leverage the
SearchOrder endpoint to pull all transaction data from a seller’s Square account.