Sign in

v1

latestOpenAPI 3.0.0Apache 2.02026-07-142008071.1 MB
Invoices

CreateInvoice

Creates a draft invoice for an order created using the Orders API.

A draft invoice remains in your account and no action is taken. You must publish the invoice before Square can process it (send it to the customer's email address or charge the customer’s card on file).

post/v2/invoices

Request body

idempotency_keystring

A unique string that identifies the CreateInvoice 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.

Example request

{
  "request_body": {
    "idempotency_key": "ce3748f9-5fc1-4762-aa12-aae5e843f1f4",
    "invoice": {
      "accepted_payment_methods": {
        "bank_account": false,
        "card": true,
        "square_gift_card": false
      },
      "custom_fields": [
        {
          "label": "Event Reference Number",
          "placement": "ABOVE_LINE_ITEMS",
          "value": "Ref. #1234"
        },
        {
          "label": "Terms of Service",
          "placement": "BELOW_LINE_ITEMS",
          "value": "The terms of service are..."
        }
      ],
      "delivery_method": "EMAIL",
      "description": "We appreciate your business!",
      "invoice_number": "inv-100",
      "location_id": "ES0RJRZYEC39A",
      "order_id": "CAISENgvlJ6jLWAzERDzjyHVybY",
      "payment_requests": [
        {
          "automatic_payment_source": "NONE",
          "due_date": "2030-01-24",
          "reminders": [
            {
              "message": "Your invoice is due tomorrow",
              "relative_scheduled_days": -1
            }
          ],
          "request_type": "BALANCE",
          "tipping_enabled": true
        }
      ],
      "primary_recipient": {
        "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4"
      },
      "scheduled_at": "2030-01-13T10:00:00Z",
      "title": "Event Planning Services"
    }
  }
}

Response

Success

Example response

{
  "invoice": {
    "accepted_payment_methods": {
      "bank_account": false,
      "card": true,
      "square_gift_card": false
    },
    "created_at": "2020-06-18T17:45:13Z",
    "custom_fields": [
      {
        "label": "Event Reference Number",
        "placement": "ABOVE_LINE_ITEMS",
        "value": "Ref. #1234"
      },
      {
        "label": "Terms of Service",
        "placement": "BELOW_LINE_ITEMS",
        "value": "The terms of service are..."
      }
    ],
    "delivery_method": "EMAIL",
    "description": "We appreciate your business!",
    "id": "inv:0-ChCHu2mZEabLeeHahQnXDjZQECY",
    "invoice_number": "inv-100",
    "location_id": "ES0RJRZYEC39A",
    "order_id": "CAISENgvlJ6jLWAzERDzjyHVybY",
    "payment_requests": [
      {
        "automatic_payment_source": "NONE",
        "computed_amount_money": {
          "amount": 10000,
          "currency": "USD"
        },
        "due_date": "2030-01-24",
        "reminders": [
          {
            "message": "Your invoice is due tomorrow",
            "relative_scheduled_days": -1,
            "status": "PENDING",
            "uid": "beebd363-e47f-4075-8785-c235aaa7df11"
          }
        ],
        "request_type": "BALANCE",
        "tipping_enabled": true,
        "total_completed_amount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355"
      }
    ],
    "primary_recipient": {
      "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "email_address": "Amelia.Earhart@example.com",
      "family_name": "Earhart",
      "given_name": "Amelia",
      "phone_number": "1-212-555-4240"
    },
    "scheduled_at": "2030-01-13T10:00:00Z",
    "status": "DRAFT",
    "timezone": "America/Los_Angeles",
    "title": "Event Planning Services",
    "updated_at": "2020-06-18T17:45:13Z",
    "version": 0
  }
}