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

You are viewing an old version of the API
Create invoice

POST /v2/invoices

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).

Permissions
ORDERS_WRITE
INVOICES_WRITE
Guide
Create and publish an invoice Try in API Explorer

Request Body

Example code
Name Description
invoice
Invoice
Required

The invoice to create.
idempotency_key
string

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.

Max Length 128

Response Fields
Name Description
invoice
Invoice

The newly created invoice.
errors
Error [ ]

Information about errors encountered during the request.

Examples

Example:
You are viewing an old version of the API
POST /v2/invoices
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/invoices \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "ce3748f9-5fc1-4762-aa12-aae5e843f1f4",
    "invoice": {
      "location_id": "ES0RJRZYEC39A",
      "order_id": "CAISENgvlJ6jLWAzERDzjyHVybY",
      "scheduled_at": "2030-01-13T10:00:00Z",
      "primary_recipient": {
        "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4"
      },
      "delivery_method": "EMAIL",
      "payment_requests": [
        {
          "request_type": "BALANCE",
          "due_date": "2030-01-24",
          "tipping_enabled": true,
          "automatic_payment_source": "NONE",
          "reminders": [
            {
              "message": "Your invoice is due tomorrow",
              "relative_scheduled_days": -1
            }
          ]
        }
      ],
      "invoice_number": "inv-100",
      "title": "Event Planning Services",
      "description": "We appreciate your business!",
      "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"
        }
      ],
      "sale_or_service_date": "2030-01-24"
    }
  }'
Response JSON 
{
  "invoice": {
    "id": "inv:0-ChCHu2mZEabLeeHahQnXDjZQECY",
    "version": 0,
    "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": "DRAFT",
    "timezone": "America/Los_Angeles",
    "created_at": "2020-06-18T17:45:13Z",
    "updated_at": "2020-06-18T17:45:13Z",
    "primary_recipient": {
      "customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4",
      "given_name": "Amelia",
      "family_name": "Earhart",
      "email_address": "Amelia.Earhart@aviators.com",
      "phone_number": "1-212-555-4240"
    },
    "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"
  }
}

Error Descriptions
400 Bad request INVALID_CARD

The credit card cannot be validated based on the provided details.

 >
400 Bad request 
{
  "errors": [
    {
      "code": "INVALID_CARD",
      "category": "PAYMENT_METHOD_ERROR"
    }
  ]
}