Learn about the Square App Marketplace requirements related to the Invoices API.
App Marketplace

Invoices API Requirements

The Invoices API can be used to create and manage invoices for Square sellers. The App Marketplace requirements described in this topic apply to partner applications that use the Invoices API.

The primary_recipient field of an invoice represents the customer who receives the invoice. Square communicates with the customer using contact information retrieved from the associated customer profile at the time the invoice is created.

Applications must include email_address when creating the associated customer profile and should include given_name, family_name, and company_name as appropriate. If the customer profile already exists, applications should update the profile with the missing information before creating the invoice.

Invoices can be configured for automatic payments using a card on file. If an automatic payment is unsuccessful, Square delivers the invoice by email and changes the automatic_payment_source field of the payment request to NONE.

Applications must update the automatic payment request if the associated card on file is updated or removed. This might require the buyer to reselect a card on file to use for the payment.

Invoices are not automatically updated or canceled if the customer profile assigned as the invoice recipient is deleted from the Customer Directory. If the invoice has remaining scheduled payments, Square continues to send the invoice. Any remaining automatic payments fail, but the customer can still enter the payment information on the Square-hosted invoice page.

Applications must account for the deletion of an invoice recipient, which might require the invoice to be canceled. Applications should monitor the customer.deleted webhook event to be notified when customer profiles are deleted.

The CreateInvoice endpoint requires the ID of an order that was created using the Orders API.

Applications must itemize all applicable taxes, discounts, surcharges, and fees individually for the order instead of aggregating the charges.

Applications should use catalog_object_id to itemize line items for the order instead of defining ad hoc line items when possible.

Applications should use customer_id to specify a customer for the order. Note that the customer who receives the invoice does not have to be the customer associated with the order.

After an invoice is published, Square manages the invoice lifecycle and status for most workflows. For example, Square sends an invoice and sets the status to PAID when the invoice is paid in full. However, some scenarios might require awareness or action by the seller or partner application.

Applications should monitor the following webhook events to track invoice status:

Note that the invoice status field is read-only and cannot be updated using the Invoices API.

After a payment is made on an invoice, the invoice can be partially or fully refunded. Refunded invoices have a REFUNDED or PARTIALLY_REFUNDED status.

Applications that support refunding invoices must handle the refund flow, which includes calling the Orders API and Refunds API. For more information, see Refund an invoice. In addition, applications must be able to handle scenarios in which an invoice has already been refunded, such as handling a 400 BAD_REQUEST error when attempting to refund a refunded invoice.

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