Introducing Invoices API Beta

For freelancers, contractors, caterers, and other businesses, maintaining a steady cash flow is more important than ever. One of the easiest ways to bill, record, track, and get paid for goods and services quickly is through an invoice. With invoices, sellers commit to offerings in advance and customers pay once the goods have been received or the services have been completed. Plus, invoicing offers payment flexibility, so sellers can offer discount incentives for early payments or extend the payment period if there's a delay in the goods or services. Most importantly, sellers can use invoicing to build a professional brand and put their best foot forward while growing their business.

We’re excited to release the new Square Invoices API to empower developers to build simple, professional, and secure invoicing solutions for sellers. Built on top of Square Invoices, the Invoices API enables developers to create, update, and send invoices from any custom or third-party platform, including vertical points of sale, order management systems, and booking and scheduling applications. Developers can also use the API to manage invoices within Square Point of Sale, Square Dashboard, and the Square Invoices app. Plus, the Invoices API offers all of the benefits of Square Invoices, including flexible online payment options, outstanding payment reminders, real-time reporting, email templates, and buyer-facing payment pages. The API also powers centralized data management by synchronizing invoicing data across platforms and making it easily accessible to sellers in the Square Dashboard. With this API integration, developers can unlock growth opportunities for sellers, empower sellers to build relationships with new customers on new platforms, and help drive a steady revenue stream by ensuring timely payments.

How Invoices API Works

Let’s say you’re building a mobile application for private tutoring to help freelance tutors connect with high school students. Students can use your application to book sessions with tutors and tutors can use it to invoice for their services. You recently onboarded a new math tutor and need to create a new service with an associated invoice.

First, call the CreateOrder endpoint to create an order and link it to a customer profile (in this case, the student is your customer).

curl https://connect.squareup.com/v2/locations/YOUR_LOCATION_ID/orders \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN' \
 -d '{
  "idempotency_key": "IDEMPOTENCY_KEY",
  "order": {
    "customer_id": "YOUR_CUSTOMER_ID",
    "location_id": "YOUR_LOCATION_ID",
    "line_items": [{
      "name": "Private Tutoring",
      "quantity": "1",
      "base_price_money": {
        "amount": 200,
        "currency": "USD"
      }
    }]
  }
}'

Once the order is created, call the CreateInvoice endpoint to create a draft invoice.

curl https://connect.squareup.com/v2/invoices \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN' \
 -d '{
  "idempotency_key": "IDEMPOTENCY_KEY",
  "invoice": {
    "order_id": "YOUR_ORDER_ID",
    "location_id": "YOUR_LOCATION_ID",
    "primary_recipient": {
      "customer_id": "YOUR_CUSTOMER_ID"
    },
    "payment_requests": [{
      "request_method": "EMAIL",
      "request_type": "BALANCE",
      "due_date": "2021-01-01"
    }]
  }
}'

Then, call the PublishInvoice endpoint to send the request to the customer to be paid.

curl https://connect.squareup.com/v2/invoices/YOUR_INVOICE_ID/publish \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN' \
 -d '{
  "version": 0,
  "idempotency_key": "IDEMPOTENCY_KEY"
}'

Let’s say a student cancelled their tutoring session. To cancel the invoice, call the CancelInvoice endpoint as shown below. When an invoice is cancelled, a notification is sent to the customer.

curl https://connect.squareup.com/v2/invoices/YOUR_INVOICE_ID/cancel \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN' \
 -d '{
  "version": 0,
  "idempotency_key": "IDEMPOTENCY_KEY"
}'

Get Started

The Invoices API is available in beta to developers in the U.S., Canada, UK, Australia, and Japan. Developers can access all endpoints and features of the API ungated in Sandbox and in production. Sellers pay a processing fee of 2.9% + 30¢ per invoice transaction.

Check out the Invoices API documentation to learn how to get started and access the API reference docs. We encourage developers to share their feedback on our community Slack channel or Square Developer Forums.

If you want to keep up to date with the rest of our content, be sure to follow this blog and our Twitter account, and sign up for our developer newsletter!