Invoices API is Generally Available

After a few months in beta, we’re thrilled to announce that Invoices API is now generally available. Since the early days of Square, our vision has been to combine the collective force of our seller-first platform with the power of extensibility from our ever-growing ecosystem developers. Built on top of Square Invoices, the Invoices API enables developers to create and manage invoices within the Square Point of Sale, Square Dashboard, Square Invoices app, and any-third party platform. The API also offers centralized data management by synchronizing invoicing data across platforms, making it easily accessible to sellers in the Square dashboard. Generally, an invoice enables sellers to provide customers with a list of goods or services provided and request payment; the Invoices API helps simplify the experience by empowering developers to build integrations based on individual seller needs.

Plus, for continued feature parity between our first-party products and APIs, we’re also excited for the release of accepted_payment_methods, providing developers the capability to offer different payment options, including credit card or debit, Square gift card or ACH bank transfer, when invoicing buyers. Invoices can also be marked as paid by a seller with other payment methods such as cash or check in the Square Dashboard or Square Invoices mobile app.

See Invoices API in action

Invoices API provides several capabilities when it comes to managing invoices–from creating and sending invoices, to searching, updating and cancelling invoices. To create an invoice, you’ll need to first create an order to request payment.

curl https://connect.squareupsandbox.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": "An Item",
        "quantity": "1",
        "base_price_money": {
          "amount": 600,
          "currency": "USD"
        }
      }]
    }
  }'

Then, you’ll create a draft invoice for the order that you created. Use the ID of the order and the ID of the customer you created to then build your draft invoice.

curl https://connect.squareupsandbox.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_type": "BALANCE",
        "due_date": "2030-01-01"
      }],
      "delivery_method": "EMAIL",
      "accepted_payment_methods": { "card": true }
    }
  }'

Lastly, you’ll publish the invoice and send it to the buyer. Use the ID of the invoice and the invoice version to publish the draft invoice you created earlier.

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

What’s next for Invoices API

There’s a lot to be excited for when it comes to the Invoices API, and we aim to continually improve upon the API based on feedback we receive from our developers. Functionality we’re looking to add in the future include update cart, mark invoices as paid, duplicate invoice, as well as recurring invoices and reporting. To chat with us, drop by our Slack community or the Square Developer Forums.

Start building

The Invoices API is generally available to developers in the U.S., Canada, U.K., Australia, and Japan. Here’s the seller pricing by country:

• U.S. and Canada: 2.9% + 30 cents per invoice transaction
• U.K.: 2.5% per invoice transaction
• Australia: 2.2% per invoice transaction
• Japan: 3.25% per invoice transaction (3.95% with JCB)

Getting started is easy; check out the documentation and build your integration(s).

Start building with Invoices API