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

You are viewing an old version of the API
Publish invoice BETA

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 charge a card on file for a portion of the invoice amount).


Permissions
ORDERS_WRITE
INVOICES_WRITE
Guide
Create and publish an invoice
Try in API Explorer
Name Description
invoice_id
string

Required

The id of the invoice to publish.

Name Description
version
integer

Required

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

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

Response Fields

Name Description
invoice
Invoice

The published invoice.

errors
Error [ ]

Information about errors encountered during the request.

Examples

You are viewing an old version of the API
POST /v2/invoices/{invoice_id}/publish
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
curl https://connect.squareup.com/v2/invoices/gt2zv1z6mnUm1V7KMxxf3w/publish \
  -X POST \
  -H 'Square-Version: 2020-09-23' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": 1,
    "idempotency_key": "32da42d0-1997-41b0-826b-f09464fc2c2e"
  }'
Response JSON
{
  "invoice": {
    "id": "gt2zv1z6mnUm1V7KMxxf3w",
    "version": 1,
    "location_id": "ES0RJRZYEC39A",
    "order_id": "CAISENgvlJ6jLWAzERDzjyHVybY",
    "payment_requests": [
      {
        "uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355",
        "request_method": "EMAIL",
        "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"
        }
      }
    ],
    "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": "Amelia.Earhart@example.com",
      "phone_number": "1-212-555-4240"
    }
  }
}

Error Descriptions

400 Bad request INVALID_CARD

The credit card cannot be validated based on the provided details.

>
402 Payment required CARD_DECLINED

402 Request failed - the card was declined.

>
402 Payment required
{
  "errors": [
    {
      "code": "CARD_DECLINED",
      "category": "PAYMENT_METHOD_ERROR"
    }
  ]
}

Share Feedback

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