Publish invoice
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.
Name | Description |
---|---|
invoice_
Required
|
The ID of the invoice to publish. |
Name | Description |
---|---|
version
Required
|
The version of the invoice to publish. This must match the current version of the invoice; otherwise, the request is rejected. |
idempotency_
|
A unique string that identifies the For more information, see Idempotency. |
Response Fields
Name | Description |
---|---|
invoice
|
The published invoice. |
errors
|
Information about errors encountered during the request. |
Examples
- cURL
- Ruby
- Python
- C#
- Java
- PHP
- Node.js
curl https://connect.squareup.com/v2/invoices/inv%3A0-ChCHu2mZEabLeeHahQnXDjZQECY/publish \
-X POST \
-H 'Square-Version: 2023-01-19' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"version": 1,
"idempotency_key": "32da42d0-1997-41b0-826b-f09464fc2c2e"
}'
{
"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": "Amelia.Earhart@example.com",
"phone_number": "1-212-555-4240"
},
"public_url": "https://squareup.com/pay-invoice/inv:0-ChCHu2mZEabLeeHahQnXDjZQECY",
"accepted_payment_methods": {
"card": true,
"square_gift_card": false,
"bank_account": false,
"buy_now_pay_later": 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
},
"errors": []
}
Error Descriptions
400 Bad request |
INVALID_ The credit card cannot be validated based on the provided details. |
> |
402 Payment required |
CARD_ The card was declined. |
> |
{
"errors": [
{
"code": "CARD_DECLINED",
"category": "PAYMENT_METHOD_ERROR"
}
]
}