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 ->

Publish invoice

POST

 /v2/invoices/{invoice_id}/publish

Publishes the specified draft invoice.

After an invoice is published, Square follows up based on the invoice configuration. For example, Square sends the invoice to the customer's email address, charges the customer's card on file, or does nothing. Square also makes the invoice available on a Square-hosted invoice page.

The invoice status also changes from DRAFT to a status based on the invoice configuration. For example, the status changes to UNPAID if Square emails the invoice or PARTIALLY_PAID if Square charges a card on file for a portion of the invoice amount.

In addition to the required ORDERS_WRITE and INVOICES_WRITE permissions, CUSTOMERS_READ and PAYMENTS_WRITE are required when publishing invoices configured for card-on-file payments.

Permissions:INVOICES_WRITE, ORDERS_WRITE

Guide

Publish invoices

Try in API Explorer
Link to section

Path parameters

Example code

Link to section

invoice_id

string

Required

The ID of the invoice to publish.

Link to section

Request body

Link to section

version

integer(32-bit)

Required

The version of the invoice to publish. This must match the current version of the invoice; otherwise, the request is rejected.

Link to section

idempotency_key

string

A unique string that identifies the PublishInvoice 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 published invoice.

Link to section

errors

Information about errors encountered during the request.

Link to section

Examples

All versions ->

POST /v2/invoices/{invoice_id}/publish
curl https://connect.squareup.com/v2/invoices/inv%3A0-ChCHu2mZEabLeeHahQnXDjZQECY/publish \ -X POST \ -H 'Square-Version: 2026-11-18' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "version": 1, "idempotency_key": "32da42d0-1997-41b0-826b-f09464fc2c2e" }'

Response JSON

{ "invoice": { "id": "inv:0-ChCHu2mZEabLeeHahQnXDjZQECY", "version": 1, "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": "SCHEDULED", "timezone": "America/Los_Angeles", "created_at": "2020-06-18T17:45:13Z", "updated_at": "2020-06-18T18:23:11Z", "primary_recipient": { "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4", "given_name": "Amelia", "family_name": "Earhart", "email_address": "[email protected]", "phone_number": "1-212-555-4240" }, "public_url": "https://squareup.com/pay-invoice/invtmp:5e22a2c2-47c1-46d6-b061-808764dfe2b9", "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" } ] }