App Marketplace

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.

Order itemization Permalink Get a link to this section

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.

Prevent orders orphaning Permalink Get a link to this section

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.

Order fulfillments Permalink Get a link to this section

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.

Note

In the current implementation, orders with OrderFulfillment must be paid using the Square Payments API before they are surfaced in the Square POS systems.

Order and order fulfillment states Permalink Get a link to this section

Square requires all partners to properly manage Order and 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.

Order webhooks Permalink Get a link to this section

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.

Order reporting Permalink Get a link to this section

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.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.