The Invoices API enables you to create, configure, and publish invoices for orders. Invoices can be sent via email or SMS, and customers can pay online using Square-hosted payment pages.
Available Methods
The Invoices client provides the following methods:
CreateInvoice - Create a new invoiceSearchInvoices - Search for invoices with filtersListInvoices - List invoices for a locationGetInvoice - Retrieve a specific invoiceUpdateInvoice - Update an existing invoiceDeleteInvoice - Delete a draft invoicePublishInvoice - Publish an invoice for paymentCancelInvoice - Cancel a published invoiceCreateInvoiceAttachment - Add an attachment to an invoiceDeleteInvoiceAttachment - Remove an attachment from an invoice
Create Invoice
Creates a draft invoice for an order. You must publish the invoice to send it to customers for payment.
package main
import (
"context"
"fmt"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
request := &square.CreateInvoiceRequest{
Invoice: &square.Invoice{
LocationID: square.String("ES0RJRZYEC39A"),
OrderID: square.String("CAISENgvlJ6jLWAzERDzjyHVybY"),
PrimaryRecipient: &square.InvoiceRecipient{
CustomerID: square.String("JDKYHBWT1D4F8MFH63DBMEN8Y4"),
},
PaymentRequests: []*square.InvoicePaymentRequest{
{
RequestType: square.InvoiceRequestTypeBalance.Ptr(),
DueDate: square.String("2030-01-24"),
},
},
DeliveryMethod: square.InvoiceDeliveryMethodEmail.Ptr(),
InvoiceNumber: square.String("inv-100"),
Title: square.String("Event Planning Services"),
Description: square.String("We appreciate your business!"),
ScheduledAt: square.String("2030-01-13T10:00:00Z"),
AcceptedPaymentMethods: &square.InvoiceAcceptedPaymentMethods{
Card: square.Bool(true),
SquareGiftCard: square.Bool(false),
BankAccount: square.Bool(false),
BuyNowPayLater: square.Bool(false),
CashAppPay: square.Bool(false),
},
},
IdempotencyKey: square.String("ce3748f9-5fc1-4762-aa12-aae5e843f1f4"),
}
response, err := client.Invoices.CreateInvoice(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Invoice created: %s\n", *response.Invoice.ID)
}
Parameters
A unique string that identifies the CreateInvoice request. See Idempotency for more information. Response
The newly created invoice
Information about errors encountered during the request
List Invoices
Returns a list of invoices for a given location. The response is paginated.
package main
import (
"context"
"fmt"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
request := &square.ListInvoicesRequest{
LocationID: "ES0RJRZYEC39A",
Limit: square.Int(100),
}
response, err := client.Invoices.ListInvoices(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Retrieved %d invoices\n", len(response.Invoices))
}
Parameters
The ID of the location for which to list invoices
A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results.
The maximum number of invoices to return. Default: 100, Maximum: 200
Response
The pagination cursor to retrieve the next set of results
Information about errors encountered during the request
Search Invoices
Searches for invoices from a location specified in the request. The response is paginated.
package main
import (
"context"
"fmt"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
request := &square.SearchInvoicesRequest{
Query: &square.InvoiceQuery{
Filter: &square.InvoiceFilter{
LocationIDs: []string{"ES0RJRZYEC39A"},
CustomerIDs: []string{"JDKYHBWT1D4F8MFH63DBMEN8Y4"},
},
Sort: &square.InvoiceSort{
Field: square.InvoiceSortFieldInvoiceSort,
Order: square.SortOrderDesc.Ptr(),
},
},
Limit: square.Int(10),
}
response, err := client.Invoices.SearchInvoices(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Found %d invoices\n", len(response.Invoices))
}
Parameters
Query
*square.InvoiceQuery
required
Describes the query criteria for searching invoices
The maximum number of invoices to return. Default: 100, Maximum: 200
A pagination cursor returned by a previous call to this endpoint
Response
The list of invoices that match the query
The pagination cursor to retrieve the next set of results
Information about errors encountered during the request
Get Invoice
Retrieves an invoice by invoice ID.
package main
import (
"context"
"fmt"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
request := &square.GetInvoicesRequest{
InvoiceID: "inv_1_2bc1",
}
response, err := client.Invoices.GetInvoice(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Invoice: %s\n", *response.Invoice.ID)
}
Parameters
The ID of the invoice to retrieve
Response
Information about errors encountered during the request
Publish Invoice
Publishes the specified draft invoice. After an invoice is published, Square processes the invoice based on the delivery method and payment request settings.
package main
import (
"context"
"fmt"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
request := &square.PublishInvoiceRequest{
InvoiceID: "inv_1_2bc1",
Version: 1,
IdempotencyKey: square.String("32da42d0-1997-41b0-826b-f09464fc2c2e"),
}
response, err := client.Invoices.PublishInvoice(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Invoice published: %s\n", *response.Invoice.ID)
}
Parameters
The ID of the invoice to publish
The version of the invoice to publish. This must match the current version of the invoice.
A unique string that identifies the PublishInvoice request. See Idempotency for more information. Response
Information about errors encountered during the request
Cancel Invoice
Cancels an invoice. The seller cannot collect payments for the canceled invoice.
package main
import (
"context"
"fmt"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
request := &square.CancelInvoiceRequest{
InvoiceID: "inv_1_2bc1",
Version: 1,
}
response, err := client.Invoices.CancelInvoice(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Invoice canceled: %s\n", *response.Invoice.ID)
}
Parameters
The ID of the invoice to cancel
The version of the invoice to cancel. If you do not know the version, you can call GetInvoice or ListInvoices.
Response
Information about errors encountered during the request
Delete Invoice
Deletes the specified invoice. Only invoices in the DRAFT, SCHEDULED, or UNPAID state can be deleted.
package main
import (
"context"
"fmt"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
request := &square.DeleteInvoicesRequest{
InvoiceID: "inv_1_2bc1",
Version: square.Int(1),
}
response, err := client.Invoices.DeleteInvoice(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Println("Invoice deleted successfully")
}
Parameters
The ID of the invoice to delete
The version of the invoice to delete. If you do not know the version, you can call GetInvoice or ListInvoices.
Response
Information about errors encountered during the request
Create Invoice Attachment
Uploads a file and attaches it to an invoice. This endpoint accepts HTTP multipart/form-data file uploads.
package main
import (
"context"
"fmt"
"os"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
file, err := os.Open("receipt.pdf")
if err != nil {
fmt.Printf("Error opening file: %v\n", err)
return
}
defer file.Close()
request := &square.CreateInvoiceAttachmentRequest{
InvoiceID: "inv_1_2bc1",
ImageFile: file,
Request: &square.CreateInvoiceAttachmentRequestData{
IdempotencyKey: square.String("ae5e843f1f4-ce3748f9-5fc1-4762"),
Description: square.String("Service receipt"),
},
}
response, err := client.Invoices.CreateInvoiceAttachment(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Printf("Attachment created: %s\n", *response.Attachment.ID)
}
Parameters
The ID of the invoice to attach the file to
The file to upload as an attachment
Request
*square.CreateInvoiceAttachmentRequestData
Additional metadata for the attachment
Response
Attachment
*square.InvoiceAttachment
Metadata about the attachment that was added to the invoice
Information about errors encountered during the request
Delete Invoice Attachment
Removes an attachment from an invoice and permanently deletes the file.
package main
import (
"context"
"fmt"
"github.com/square/square-go-sdk/v3"
)
func main() {
client := square.NewClient(
square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)
request := &square.DeleteInvoiceAttachmentRequest{
InvoiceID: "inv_1_2bc1",
AttachmentID: "at_1_abc123",
}
response, err := client.Invoices.DeleteInvoiceAttachment(context.Background(), request)
if err != nil {
fmt.Printf("Error: %v\n", err)
return
}
fmt.Println("Attachment deleted successfully")
}
Parameters
The ID of the invoice to delete the attachment from
The ID of the attachment to delete
Response
Information about errors encountered during the request
