• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

Object Index

You are viewing an old version of the API
Invoice BETA

Stores information about an invoice.

You use the Invoices API to create and manage invoices. For more information, see Manage Invoices Using the Invoices API.

Properties

Name Description
id
string

Read only The Square-assigned ID of the invoice.

version
integer

The Square-assigned version number, which is incremented each time an update is committed to the invoice.

location_id
string

The ID of the location that this invoice is associated with. This field is required when creating an invoice.

Max Length 255 Min Length 1
order_id
string

The ID of the order for which the invoice is created.

This order must be in the OPEN state and must belong to the location_id specified for this invoice. This field is required when creating an invoice.

Max Length 255 Min Length 1
primary_recipient
InvoiceRecipient

The customer who gets the invoice. Square uses the contact information to deliver the invoice. This field is required to publish an invoice.

payment_requests
InvoicePaymentRequest [ ]

The payment schedule for the invoice, represented by one or more payment requests that define payment settings, such as amount due and due date. You can specify a maximum of 13 payment requests, with up to 12 INSTALLMENT request types. For more information, see Payment requests.

This field is required when creating an invoice. It must contain at least one payment request.

delivery_method
string

The delivery method that Square uses to send the invoice, reminders, and receipts to the customer. After the invoice is published, Square processes the invoice based on the delivery method and payment request settings, either immediately or at the scheduled_at date, if specified. For example, Square might send the invoice or receipt for an automatic payment. For invoices with automatic payments, this field must be set to EMAIL.

One of the following is required when creating an invoice:

  • (Recommended) This delivery_method field. To configure an automatic payment, the automatic_payment_source field of the payment request is also required.
  • The deprecated request_method field of the payment request. Note that invoice objects returned in responses do not include request_method.
invoice_number
string

A user-friendly invoice number. The value is unique within a location. If not provided when creating an invoice, Square assigns a value. It increments from 1 and padded with zeros making it 7 characters long for example, 0000001, 0000002.

Max Length 191 Min Length 1
title
string

The title of the invoice.

Max Length 255 Min Length 1
description
string

The description of the invoice. This is visible to the customer receiving the invoice.

Max Length 65536 Min Length 1
scheduled_at
string

The timestamp when the invoice is scheduled for processing, in RFC 3339 format. After the invoice is published, Square processes the invoice on the specified date, according to the delivery method and payment request settings.

If the field is not set, Square processes the invoice immediately after it is published.

Examples for January 25th, 2020 6:25:34pm Pacific Standard Time:

UTC: 2020-01-26T02:25:34Z

Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00

public_url
string

Read only The URL of the Square-hosted invoice page. After you publish the invoice using the PublishInvoice endpoint, Square hosts the invoice page and returns the page URL in the response.

next_payment_amount_money
Money

Read only The current amount due for the invoice. In addition to the amount due on the next payment request, this also includes any overdue payment amounts.

status
string

Read only The status of the invoice.

timezone
string

Read only The time zone of the date values (for example, due_date) specified in the invoice.

created_at
string

Read only The timestamp when the invoice was created, in RFC 3339 format.

Examples for January 25th, 2020 6:25:34pm Pacific Standard Time:

UTC: 2020-01-26T02:25:34Z

Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00

updated_at
string

Read only The timestamp when the invoice was last updated, in RFC 3339 format.

Examples for January 25th, 2020 6:25:34pm Pacific Standard Time:

UTC: 2020-01-26T02:25:34Z

Pacific Standard Time with UTC offset: 2020-01-25T18:25:34-08:00

custom_fields
InvoiceCustomField [ ]

Additional seller-defined fields to render on the invoice. These fields are visible to sellers and buyers on the Square-hosted invoice page and in emailed or PDF copies of invoices. For more information, see Custom fields.

Max: 2 custom fields

Share Feedback

Thanks for visiting the Square API documentation. What's on your mind?