Development
  • Guides
  • API Reference
  • API Explorer
  • SDKs
  • Sample apps
  • System status
Support
  • Developer forums
  • Developer blog
  • YouTube
  • X
More
  • Square Home
  • Square Developer
  • App Marketplace
  • Partner with Square
  • Solutions Partner Program
  • Pricing
  • Sales

© 2026 Square, Inc.

  • Developer terms of service
  • Developer Integration and Marketing Agreement
  • Privacy policy
  • Partnerships
  • Sign In
  • Sign In

    Invoices

  • List invoices

  • Create invoice

  • Search invoices

  • Delete invoice

  • Get invoice

  • Update invoice

  • Create invoice attachment

  • Delete invoice attachment

  • Cancel invoice

  • Publish invoice

  • Webhooks

  • invoice.canceled

  • invoice.created

  • invoice.deleted

  • invoice.payment_made

  • invoice.published

  • invoice.refunded

  • invoice.scheduled_charge_failed

  • invoice.updated

<- Invoices API

Invoices API

All versions ->

Create invoice

POST

 /v2/invoices

Creates a draft invoice for an order created using the Orders API.

A draft invoice remains in your account and no action is taken. You must publish the invoice before Square can process it (send it to the customer's email address or charge the customer’s card on file).

Permissions:INVOICES_WRITE, ORDERS_WRITE

Guide

Create invoices

Try in API Explorer
Link to section

Request body

Example code

Link to section

invoice

Required

The invoice to create.

Link to section

idempotency_key

string

A unique string that identifies the CreateInvoice request. If you do not provide idempotency_key (or provide an empty string as the value), the endpoint treats each request as independent.

For more information, see Idempotency.

Max Length
128
Link to section

Response fields

Link to section

invoice

The newly created invoice.

Link to section

errors

Information about errors encountered during the request.

Link to section

Examples

All versions ->

POST /v2/invoices
curl https://connect.squareup.com/v2/invoices \ -X POST \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "idempotency_key": "ce3748f9-5fc1-4762-aa12-aae5e843f1f4", "invoice": { "location_id": "ES0RJRZYEC39A", "order_id": "CAISENgvlJ6jLWAzERDzjyHVybY", "scheduled_at": "2030-01-13T10:00:00Z", "primary_recipient": { "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4" }, "delivery_method": "EMAIL", "payment_requests": [ { "request_type": "BALANCE", "due_date": "2030-01-24", "tipping_enabled": true, "automatic_payment_source": "NONE", "reminders": [ { "message": "Your invoice is due tomorrow", "relative_scheduled_days": -1 } ] } ], "invoice_number": "inv-100", "title": "Event Planning Services", "description": "We appreciate your business!", "accepted_payment_methods": { "card": true, "square_gift_card": false, "bank_account": false, "buy_now_pay_later": false, "cash_app_pay": false }, "custom_fields": [ { "label": "Event Reference Number", "value": "Ref. #1234", "placement": "ABOVE_LINE_ITEMS" }, { "label": "Terms of Service", "value": "The terms of service are...", "placement": "BELOW_LINE_ITEMS" } ], "sale_or_service_date": "2030-01-24", "store_payment_method_enabled": false } }'

Response JSON

{ "invoice": { "id": "inv:0-ChCHu2mZEabLeeHahQnXDjZQECY", "version": 0, "location_id": "ES0RJRZYEC39A", "order_id": "CAISENgvlJ6jLWAzERDzjyHVybY", "payment_requests": [ { "uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355", "request_type": "BALANCE", "due_date": "2030-01-24", "tipping_enabled": true, "reminders": [ { "uid": "beebd363-e47f-4075-8785-c235aaa7df11", "relative_scheduled_days": -1, "message": "Your invoice is due tomorrow", "status": "PENDING" } ], "computed_amount_money": { "amount": 10000, "currency": "USD" }, "total_completed_amount_money": { "amount": 0, "currency": "USD" }, "automatic_payment_source": "NONE" } ], "invoice_number": "inv-100", "title": "Event Planning Services", "description": "We appreciate your business!", "scheduled_at": "2030-01-13T10:00:00Z", "status": "DRAFT", "timezone": "America/Los_Angeles", "created_at": "2020-06-18T17:45:13Z", "updated_at": "2020-06-18T17:45:13Z", "primary_recipient": { "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", "given_name": "Amelia", "family_name": "Earhart", "email_address": "[email protected]", "phone_number": "1-212-555-4240" }, "accepted_payment_methods": { "card": true, "square_gift_card": false, "bank_account": false, "buy_now_pay_later": false, "cash_app_pay": false }, "custom_fields": [ { "label": "Event Reference Number", "value": "Ref. #1234", "placement": "ABOVE_LINE_ITEMS" }, { "label": "Terms of Service", "value": "The terms of service are...", "placement": "BELOW_LINE_ITEMS" } ], "delivery_method": "EMAIL", "sale_or_service_date": "2030-01-24", "store_payment_method_enabled": false } }

Error descriptions

400 Bad request

{ "errors": [ { "code": "INVALID_CARD", "category": "PAYMENT_METHOD_ERROR" } ] }