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).
Name | Description |
---|---|
invoice
Required
|
The invoice to create. |
idempotency_
|
A unique string that identifies the For more information, see Idempotency. |
Response Fields
Name | Description |
---|---|
invoice
|
The newly created invoice. |
errors
|
Information about errors encountered during the request. |
Examples
Example:
POST
/v2/invoices
cURL
- cURL
- Ruby
- Python
- C#
- Java
- PHP
- Node.js
curl https://connect.squareup.com/v2/invoices \
-X POST \
-H 'Square-Version: 2023-01-19' \
-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,
"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"
}
],
"sale_or_service_date": "2030-01-24",
"store_payment_method_enabled": false
}
}'
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,
"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. |
> |
400
Bad request
{
"errors": [
{
"code": "INVALID_CARD",
"category": "PAYMENT_METHOD_ERROR"
}
]
}