You are viewing an old version of the API

All Versions

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

Path Parameters

Example code

Name	Description
`invoice_id string` Required	The id of the invoice to publish.

Request Body

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

POST /v2/invoices/{invoice_id}/publish

curl https://connect.squareup.com/v2/invoices/gt2zv1z6mnUm1V7KMxxf3w/publish \
  -X POST \
  -H 'Square-Version: 2021-01-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "version": 1,
    "idempotency_key": "32da42d0-1997-41b0-826b-f09464fc2c2e"
  }'

{
  "invoice": {
    "id": "gt2zv1z6mnUm1V7KMxxf3w",
    "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": "Amelia.Earhart@example.com",
      "phone_number": "1-212-555-4240"
    },
    "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"
  }
}

Error Descriptions

400 Bad request	INVALID_CARD The credit card cannot be validated based on the provided details.	>
402 Payment required	CARD_DECLINED The card was declined.	>

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