com.squareup.square.api

Interface InvoicesApi

All Known Implementing Classes:

DefaultInvoicesApi

public interface InvoicesApi

This interface lists all the endpoints of the group. This can be overridden for the mock calls.

Method Summary

Modifier and Type	Method and Description
CancelInvoiceResponse	cancelInvoice(String invoiceId, CancelInvoiceRequest body) Cancels an invoice.
CompletableFuture<CancelInvoiceResponse>	cancelInvoiceAsync(String invoiceId, CancelInvoiceRequest body) Cancels an invoice.
CreateInvoiceResponse	createInvoice(CreateInvoiceRequest body) Creates a draft [invoice]($m/Invoice) for an order created using the Orders API.
CompletableFuture<CreateInvoiceResponse>	createInvoiceAsync(CreateInvoiceRequest body) Creates a draft [invoice]($m/Invoice) for an order created using the Orders API.
CreateInvoiceAttachmentResponse	createInvoiceAttachment(String invoiceId, CreateInvoiceAttachmentRequest request, FileWrapper imageFile) Uploads a file and attaches it to an invoice.
CompletableFuture<CreateInvoiceAttachmentResponse>	createInvoiceAttachmentAsync(String invoiceId, CreateInvoiceAttachmentRequest request, FileWrapper imageFile) Uploads a file and attaches it to an invoice.
DeleteInvoiceResponse	deleteInvoice(String invoiceId, Integer version) Deletes the specified invoice.
CompletableFuture<DeleteInvoiceResponse>	deleteInvoiceAsync(String invoiceId, Integer version) Deletes the specified invoice.
DeleteInvoiceAttachmentResponse	deleteInvoiceAttachment(String invoiceId, String attachmentId) Removes an attachment from an invoice and permanently deletes the file.
CompletableFuture<DeleteInvoiceAttachmentResponse>	deleteInvoiceAttachmentAsync(String invoiceId, String attachmentId) Removes an attachment from an invoice and permanently deletes the file.
GetInvoiceResponse	getInvoice(String invoiceId) Retrieves an invoice by invoice ID.
CompletableFuture<GetInvoiceResponse>	getInvoiceAsync(String invoiceId) Retrieves an invoice by invoice ID.
ListInvoicesResponse	listInvoices(String locationId, String cursor, Integer limit) Returns a list of invoices for a given location.
CompletableFuture<ListInvoicesResponse>	listInvoicesAsync(String locationId, String cursor, Integer limit) Returns a list of invoices for a given location.
PublishInvoiceResponse	publishInvoice(String invoiceId, PublishInvoiceRequest body) Publishes the specified draft invoice.
CompletableFuture<PublishInvoiceResponse>	publishInvoiceAsync(String invoiceId, PublishInvoiceRequest body) Publishes the specified draft invoice.
SearchInvoicesResponse	searchInvoices(SearchInvoicesRequest body) Searches for invoices from a location specified in the filter.
CompletableFuture<SearchInvoicesResponse>	searchInvoicesAsync(SearchInvoicesRequest body) Searches for invoices from a location specified in the filter.
UpdateInvoiceResponse	updateInvoice(String invoiceId, UpdateInvoiceRequest body) Updates an invoice by modifying fields, clearing fields, or both.
CompletableFuture<UpdateInvoiceResponse>	updateInvoiceAsync(String invoiceId, UpdateInvoiceRequest body) Updates an invoice by modifying fields, clearing fields, or both.

Method Detail

listInvoices

ListInvoicesResponse listInvoices(String locationId,
                                  String cursor,
                                  Integer limit)
                           throws ApiException,
                                  IOException

Returns a list of invoices for a given location. The response is paginated. If truncated, the response includes a `cursor` that you use in a subsequent request to retrieve the next set of invoices.

Parameters:

locationId - Required parameter: The ID of the location for which to list invoices.

cursor - Optional parameter: A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).

limit - Optional parameter: The maximum number of invoices to return (200 is the maximum `limit`). If not provided, the server uses a default limit of 100 invoices.

Returns:

Returns the ListInvoicesResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

listInvoicesAsync

CompletableFuture<ListInvoicesResponse> listInvoicesAsync(String locationId,
                                                          String cursor,
                                                          Integer limit)

Returns a list of invoices for a given location. The response is paginated. If truncated, the response includes a `cursor` that you use in a subsequent request to retrieve the next set of invoices.

Parameters:

locationId - Required parameter: The ID of the location for which to list invoices.

cursor - Optional parameter: A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see [Pagination](https://developer.squareup.com/docs/build-basics/common-api-patterns/pagination).

limit - Optional parameter: The maximum number of invoices to return (200 is the maximum `limit`). If not provided, the server uses a default limit of 100 invoices.

Returns:

Returns the ListInvoicesResponse response from the API call

createInvoice

CreateInvoiceResponse createInvoice(CreateInvoiceRequest body)
                             throws ApiException,
                                    IOException

Creates a draft [invoice]($m/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).

Parameters:

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the CreateInvoiceResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

createInvoiceAsync

CompletableFuture<CreateInvoiceResponse> createInvoiceAsync(CreateInvoiceRequest body)

Creates a draft [invoice]($m/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).

Parameters:

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the CreateInvoiceResponse response from the API call

searchInvoices

SearchInvoicesResponse searchInvoices(SearchInvoicesRequest body)
                               throws ApiException,
                                      IOException

Searches for invoices from a location specified in the filter. You can optionally specify customers in the filter for whom to retrieve invoices. In the current implementation, you can only specify one location and optionally one customer. The response is paginated. If truncated, the response includes a `cursor` that you use in a subsequent request to retrieve the next set of invoices.

Parameters:

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the SearchInvoicesResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

searchInvoicesAsync

CompletableFuture<SearchInvoicesResponse> searchInvoicesAsync(SearchInvoicesRequest body)

Searches for invoices from a location specified in the filter. You can optionally specify customers in the filter for whom to retrieve invoices. In the current implementation, you can only specify one location and optionally one customer. The response is paginated. If truncated, the response includes a `cursor` that you use in a subsequent request to retrieve the next set of invoices.

Parameters:

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the SearchInvoicesResponse response from the API call

deleteInvoice

DeleteInvoiceResponse deleteInvoice(String invoiceId,
                                    Integer version)
                             throws ApiException,
                                    IOException

Deletes the specified invoice. When an invoice is deleted, the associated order status changes to CANCELED. You can only delete a draft invoice (you cannot delete a published invoice, including one that is scheduled for processing).

Parameters:

invoiceId - Required parameter: The ID of the invoice to delete.

version - Optional parameter: The version of the [invoice](entity:Invoice) to delete. If you do not know the version, you can call [GetInvoice](api-endpoint:Invoices-GetInvoice) or [ListInvoices](api-endpoint:Invoices-ListInvoices).

Returns:

Returns the DeleteInvoiceResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

deleteInvoiceAsync

CompletableFuture<DeleteInvoiceResponse> deleteInvoiceAsync(String invoiceId,
                                                            Integer version)

Deletes the specified invoice. When an invoice is deleted, the associated order status changes to CANCELED. You can only delete a draft invoice (you cannot delete a published invoice, including one that is scheduled for processing).

Parameters:

invoiceId - Required parameter: The ID of the invoice to delete.

version - Optional parameter: The version of the [invoice](entity:Invoice) to delete. If you do not know the version, you can call [GetInvoice](api-endpoint:Invoices-GetInvoice) or [ListInvoices](api-endpoint:Invoices-ListInvoices).

Returns:

Returns the DeleteInvoiceResponse response from the API call

getInvoice

GetInvoiceResponse getInvoice(String invoiceId)
                       throws ApiException,
                              IOException

Retrieves an invoice by invoice ID.

Parameters:

invoiceId - Required parameter: The ID of the invoice to retrieve.

Returns:

Returns the GetInvoiceResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

getInvoiceAsync

CompletableFuture<GetInvoiceResponse> getInvoiceAsync(String invoiceId)

Retrieves an invoice by invoice ID.

Parameters:

invoiceId - Required parameter: The ID of the invoice to retrieve.

Returns:

Returns the GetInvoiceResponse response from the API call

updateInvoice

UpdateInvoiceResponse updateInvoice(String invoiceId,
                                    UpdateInvoiceRequest body)
                             throws ApiException,
                                    IOException

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.

Parameters:

invoiceId - Required parameter: The ID of the invoice to update.

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the UpdateInvoiceResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

updateInvoiceAsync

CompletableFuture<UpdateInvoiceResponse> updateInvoiceAsync(String invoiceId,
                                                            UpdateInvoiceRequest body)

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.

Parameters:

invoiceId - Required parameter: The ID of the invoice to update.

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the UpdateInvoiceResponse response from the API call

createInvoiceAttachment

CreateInvoiceAttachmentResponse createInvoiceAttachment(String invoiceId,
                                                        CreateInvoiceAttachmentRequest request,
                                                        FileWrapper imageFile)
                                                 throws ApiException,
                                                        IOException

Uploads a file and attaches it to an invoice. This endpoint accepts HTTP multipart/form-data file uploads with a JSON `request` part and a `file` part. The `file` part must be a `readable stream` that contains a file in a supported format: GIF, JPEG, PNG, TIFF, BMP, or PDF. Invoices can have up to 10 attachments with a total file size of 25 MB. Attachments can be added only to invoices in the `DRAFT`, `SCHEDULED`, `UNPAID`, or `PARTIALLY_PAID` state.

Parameters:

invoiceId - Required parameter: The ID of the [invoice](entity:Invoice) to attach the file to.

request - Optional parameter: Represents a [CreateInvoiceAttachment]($e/Invoices/CreateInvoiceAttachment) request.

imageFile - Optional parameter: Example:

Returns:

Returns the CreateInvoiceAttachmentResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

createInvoiceAttachmentAsync

CompletableFuture<CreateInvoiceAttachmentResponse> createInvoiceAttachmentAsync(String invoiceId,
                                                                                CreateInvoiceAttachmentRequest request,
                                                                                FileWrapper imageFile)

Uploads a file and attaches it to an invoice. This endpoint accepts HTTP multipart/form-data file uploads with a JSON `request` part and a `file` part. The `file` part must be a `readable stream` that contains a file in a supported format: GIF, JPEG, PNG, TIFF, BMP, or PDF. Invoices can have up to 10 attachments with a total file size of 25 MB. Attachments can be added only to invoices in the `DRAFT`, `SCHEDULED`, `UNPAID`, or `PARTIALLY_PAID` state.

Parameters:

invoiceId - Required parameter: The ID of the [invoice](entity:Invoice) to attach the file to.

request - Optional parameter: Represents a [CreateInvoiceAttachment]($e/Invoices/CreateInvoiceAttachment) request.

imageFile - Optional parameter: Example:

Returns:

Returns the CreateInvoiceAttachmentResponse response from the API call

deleteInvoiceAttachment

DeleteInvoiceAttachmentResponse deleteInvoiceAttachment(String invoiceId,
                                                        String attachmentId)
                                                 throws ApiException,
                                                        IOException

Removes an attachment from an invoice and permanently deletes the file. Attachments can be removed only from invoices in the `DRAFT`, `SCHEDULED`, `UNPAID`, or `PARTIALLY_PAID` state.

Parameters:

invoiceId - Required parameter: The ID of the [invoice](entity:Invoice) to delete the attachment from.

attachmentId - Required parameter: The ID of the [attachment](entity:InvoiceAttachment) to delete.

Returns:

Returns the DeleteInvoiceAttachmentResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

deleteInvoiceAttachmentAsync

CompletableFuture<DeleteInvoiceAttachmentResponse> deleteInvoiceAttachmentAsync(String invoiceId,
                                                                                String attachmentId)

Removes an attachment from an invoice and permanently deletes the file. Attachments can be removed only from invoices in the `DRAFT`, `SCHEDULED`, `UNPAID`, or `PARTIALLY_PAID` state.

Parameters:

invoiceId - Required parameter: The ID of the [invoice](entity:Invoice) to delete the attachment from.

attachmentId - Required parameter: The ID of the [attachment](entity:InvoiceAttachment) to delete.

Returns:

Returns the DeleteInvoiceAttachmentResponse response from the API call

cancelInvoice

CancelInvoiceResponse cancelInvoice(String invoiceId,
                                    CancelInvoiceRequest body)
                             throws ApiException,
                                    IOException

Cancels an invoice. The seller cannot collect payments for the canceled invoice. You cannot cancel an invoice in the `DRAFT` state or in a terminal state: `PAID`, `REFUNDED`, `CANCELED`, or `FAILED`.

Parameters:

invoiceId - Required parameter: The ID of the [invoice](entity:Invoice) to cancel.

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the CancelInvoiceResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

cancelInvoiceAsync

CompletableFuture<CancelInvoiceResponse> cancelInvoiceAsync(String invoiceId,
                                                            CancelInvoiceRequest body)

Cancels an invoice. The seller cannot collect payments for the canceled invoice. You cannot cancel an invoice in the `DRAFT` state or in a terminal state: `PAID`, `REFUNDED`, `CANCELED`, or `FAILED`.

Parameters:

invoiceId - Required parameter: The ID of the [invoice](entity:Invoice) to cancel.

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the CancelInvoiceResponse response from the API call

publishInvoice

PublishInvoiceResponse publishInvoice(String invoiceId,
                                      PublishInvoiceRequest body)
                               throws ApiException,
                                      IOException

Publishes the specified draft invoice. After an invoice is published, Square follows up based on the invoice configuration. For example, Square sends the invoice to the customer's email address, charges the customer's card on file, or does nothing. Square also makes the invoice available on a Square-hosted invoice page. The invoice `status` also changes from `DRAFT` to a status based on the invoice configuration. For example, the status changes to `UNPAID` if Square emails the invoice or `PARTIALLY_PAID` if Square charge a card on file for a portion of the invoice amount.

Parameters:

invoiceId - Required parameter: The ID of the invoice to publish.

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the PublishInvoiceResponse response from the API call

Throws:

ApiException - Represents error response from the server.

IOException - Signals that an I/O exception of some sort has occurred.

publishInvoiceAsync

CompletableFuture<PublishInvoiceResponse> publishInvoiceAsync(String invoiceId,
                                                              PublishInvoiceRequest body)

Publishes the specified draft invoice. After an invoice is published, Square follows up based on the invoice configuration. For example, Square sends the invoice to the customer's email address, charges the customer's card on file, or does nothing. Square also makes the invoice available on a Square-hosted invoice page. The invoice `status` also changes from `DRAFT` to a status based on the invoice configuration. For example, the status changes to `UNPAID` if Square emails the invoice or `PARTIALLY_PAID` if Square charge a card on file for a portion of the invoice amount.

Parameters:

invoiceId - Required parameter: The ID of the invoice to publish.

body - Required parameter: An object containing the fields to POST for the request. See the corresponding object definition for field details.

Returns:

Returns the PublishInvoiceResponse response from the API call