You are viewing an old version of the API

All Versions

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 invoices Try in API Explorer

Path Parameters

Example code

Name	Description
`invoice_id string` Required	The ID of the invoice to update.

Request Body

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

PUT /v2/invoices/{invoice_id}

curl https://connect.squareup.com/v2/invoices/inv%3A0-ChCHu2mZEabLeeHahQnXDjZQECY \
  -X PUT \
  -H 'Square-Version: 2023-01-19' \
  -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
        }
      ],
      "version": 1
    },
    "fields_to_clear": [
      "payments_requests[2da7964f-f3d2-4f43-81e8-5aa220bf3355].reminders"
    ]
  }'

{
  "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,
      "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
  }
}