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

You are viewing an old version of the API
Update invoice

PUT /v2/invoices/{invoice_id}

Updates an invoice by modifying fields, clearing fields, or both.

For most updates, you can use a sparse Invoice object to add fields or change values and use the fields_to_clear field to specify fields to clear. However, some restrictions apply. For example, you cannot change the order_id or location_id field and you must provide the complete custom_fields list to update a custom field. Published invoices have additional restrictions.


Permissions
ORDERS_WRITE
INVOICES_WRITE
Guide
Update an invoice
Try in API Explorer
Name Description
invoice_id
string

Required

The ID of the invoice to update.

Name Description
invoice
Invoice

Required

The invoice fields to update. The current invoice version must be specified in the version field. For more information, see Update an invoice.

idempotency_key
string

A unique string that identifies the UpdateInvoice 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
fields_to_clear
string [ ]

The list of fields to clear. For examples, see Update an invoice.

Response Fields

Name Description
invoice
Invoice

The updated invoice.

errors
Error [ ]

Information about errors encountered during the request.

Examples

You are viewing an old version of the API
PUT /v2/invoices/{invoice_id}
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js
curl https://connect.squareup.com/v2/invoices/inv%3A0-ChCHu2mZEabLeeHahQnXDjZQECY \
  -X PUT \
  -H 'Square-Version: 2021-11-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "4ee82288-0910-499e-ab4c-5d0071dad1be",
    "invoice": {
      "payment_requests": [
        {
          "uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355",
          "tipping_enabled": false
        }
      ]
    },
    "fields_to_clear": [
      "payments_requests[2da7964f-f3d2-4f43-81e8-5aa220bf3355].reminders"
    ]
  }'
Response JSON
{
  "invoice": {
    "id": "inv:0-ChCHu2mZEabLeeHahQnXDjZQECY",
    "version": 2,
    "location_id": "ES0RJRZYEC39A",
    "order_id": "CAISENgvlJ6jLWAzERDzjyHVybY",
    "payment_requests": [
      {
        "uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355",
        "request_type": "BALANCE",
        "due_date": "2030-01-24",
        "tipping_enabled": false,
        "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": "UNPAID",
    "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"
    },
    "next_payment_amount_money": {
      "amount": 10000,
      "currency": "USD"
    },
    "accepted_payment_methods": {
      "card": true,
      "square_gift_card": false,
      "bank_account": 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"
  }
}