com.squareup.square.api

Class DefaultInvoicesApi

java.lang.Object

com.squareup.square.api.BaseApi

com.squareup.square.api.DefaultInvoicesApi

All Implemented Interfaces:

InvoicesApi

public final class DefaultInvoicesApi
extends BaseApi
implements InvoicesApi

This class lists all the endpoints of the groups.

Field Summary

Fields inherited from class com.squareup.square.api.BaseApi

AUTHENTICATION_KEY, GLOBAL_ERROR_CASES

Constructor Summary

Constructors

Constructor and Description
DefaultInvoicesApi(io.apimatic.core.GlobalConfiguration globalConfig) Initializes the controller.

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.

Methods inherited from class com.squareup.square.api.BaseApi

getClientInstance, getGlobalConfiguration, getHttpCallback

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DefaultInvoicesApi

public DefaultInvoicesApi(io.apimatic.core.GlobalConfiguration globalConfig)

Initializes the controller.

Parameters:

globalConfig - Configurations added in client.

Method Detail

listInvoices

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

Specified by:

listInvoices in interface InvoicesApi

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

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

Specified by:

listInvoicesAsync in interface InvoicesApi

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

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

Specified by:

createInvoice in interface InvoicesApi

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

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

Specified by:

createInvoiceAsync in interface InvoicesApi

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

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

Specified by:

searchInvoices in interface InvoicesApi

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

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

Specified by:

searchInvoicesAsync in interface InvoicesApi

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

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

Specified by:

deleteInvoice in interface InvoicesApi

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

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

Specified by:

deleteInvoiceAsync in interface InvoicesApi

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

public GetInvoiceResponse getInvoice(String invoiceId)
                              throws ApiException,
                                     IOException

Retrieves an invoice by invoice ID.

Specified by:

getInvoice in interface InvoicesApi

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

public CompletableFuture<GetInvoiceResponse> getInvoiceAsync(String invoiceId)

Retrieves an invoice by invoice ID.

Specified by:

getInvoiceAsync in interface InvoicesApi

Parameters:

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

Returns:

Returns the GetInvoiceResponse response from the API call

updateInvoice

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

Specified by:

updateInvoice in interface InvoicesApi

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

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

Specified by:

updateInvoiceAsync in interface InvoicesApi

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

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

Specified by:

createInvoiceAttachment in interface InvoicesApi

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

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

Specified by:

createInvoiceAttachmentAsync in interface InvoicesApi

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

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

Specified by:

deleteInvoiceAttachment in interface InvoicesApi

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

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

Specified by:

deleteInvoiceAttachmentAsync in interface InvoicesApi

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

public 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`.

Specified by:

cancelInvoice in interface InvoicesApi

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

public 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`.

Specified by:

cancelInvoiceAsync in interface InvoicesApi

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

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

Specified by:

publishInvoice in interface InvoicesApi

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

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

Specified by:

publishInvoiceAsync in interface InvoicesApi

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