Invoices

const invoicesApi = client.invoicesApi;

Class Name

InvoicesApi

Methods

List Invoices
Create Invoice
Search Invoices
Delete Invoice
Get Invoice
Update Invoice
Create Invoice Attachment
Delete Invoice Attachment
Cancel Invoice
Publish Invoice

List Invoices

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.

async listInvoices(  locationId: string,
  cursor?: string,
  limit?: number,
requestOptions?: RequestOptions): Promise<ApiResponse<ListInvoicesResponse>>

Parameters

Parameter	Type	Tags	Description
`locationId`	`string`	Query, Required	The ID of the location for which to list invoices.
`cursor`	`string \| undefined`	Query, Optional	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.
`limit`	`number \| undefined`	Query, Optional	The maximum number of invoices to return (200 is the maximum `limit`). If not provided, the server uses a default limit of 100 invoices.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

ListInvoicesResponse

Example Usage

const locationId = 'location_id4';

try {
  const { result, ...httpResponse } = await invoicesApi.listInvoices(locationId);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Create Invoice

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

async createInvoice(  body: CreateInvoiceRequest,
requestOptions?: RequestOptions): Promise<ApiResponse<CreateInvoiceResponse>>

Parameters

Parameter	Type	Tags	Description
`body`	`CreateInvoiceRequest`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

CreateInvoiceResponse

Example Usage

const body: CreateInvoiceRequest = {
  invoice: {
    locationId: 'ES0RJRZYEC39A',
    orderId: 'CAISENgvlJ6jLWAzERDzjyHVybY',
    primaryRecipient: {
      customerId: 'JDKYHBWT1D4F8MFH63DBMEN8Y4',
    },
    paymentRequests: [
      {
        requestType: 'BALANCE',
        dueDate: '2030-01-24',
        tippingEnabled: true,
        automaticPaymentSource: 'NONE',
        reminders: [
          {
            relativeScheduledDays: -1,
            message: 'Your invoice is due tomorrow',
          }
        ],
      }
    ],
    deliveryMethod: 'EMAIL',
    invoiceNumber: 'inv-100',
    title: 'Event Planning Services',
    description: 'We appreciate your business!',
    scheduledAt: '2030-01-13T10:00:00Z',
    acceptedPaymentMethods: {
      card: true,
      squareGiftCard: false,
      bankAccount: false,
      buyNowPayLater: false,
      cashAppPay: false,
    },
    customFields: [
      {
        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',
      }
    ],
    saleOrServiceDate: '2030-01-24',
    storePaymentMethodEnabled: false,
  },
  idempotencyKey: 'ce3748f9-5fc1-4762-aa12-aae5e843f1f4',
};

try {
  const { result, ...httpResponse } = await invoicesApi.createInvoice(body);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Search Invoices

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.

async searchInvoices(  body: SearchInvoicesRequest,
requestOptions?: RequestOptions): Promise<ApiResponse<SearchInvoicesResponse>>

Parameters

Parameter	Type	Tags	Description
`body`	`SearchInvoicesRequest`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

SearchInvoicesResponse

Example Usage

const body: SearchInvoicesRequest = {
  query: {
    filter: {
      locationIds: [
        'ES0RJRZYEC39A'
      ],
      customerIds: [
        'JDKYHBWT1D4F8MFH63DBMEN8Y4'
      ],
    },
    sort: {
      field: 'INVOICE_SORT_DATE',
      order: 'DESC',
    },
  },
};

try {
  const { result, ...httpResponse } = await invoicesApi.searchInvoices(body);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Delete Invoice

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

async deleteInvoice(  invoiceId: string,
  version?: number,
requestOptions?: RequestOptions): Promise<ApiResponse<DeleteInvoiceResponse>>

Parameters

Parameter	Type	Tags	Description
`invoiceId`	`string`	Template, Required	The ID of the invoice to delete.
`version`	`number \| undefined`	Query, Optional	The version of the invoice to delete. If you do not know the version, you can call GetInvoice or ListInvoices.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

DeleteInvoiceResponse

Example Usage

const invoiceId = 'invoice_id0';

try {
  const { result, ...httpResponse } = await invoicesApi.deleteInvoice(invoiceId);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Get Invoice

Retrieves an invoice by invoice ID.

async getInvoice(  invoiceId: string,
requestOptions?: RequestOptions): Promise<ApiResponse<GetInvoiceResponse>>

Parameters

Parameter	Type	Tags	Description
`invoiceId`	`string`	Template, Required	The ID of the invoice to retrieve.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

GetInvoiceResponse

Example Usage

const invoiceId = 'invoice_id0';

try {
  const { result, ...httpResponse } = await invoicesApi.getInvoice(invoiceId);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Update Invoice

Updates an invoice. This endpoint supports sparse updates, so you only need to specify the fields you want to change along with the required version field. Some restrictions apply to updating invoices. For example, you cannot change the order_id or location_id field.

async updateInvoice(  invoiceId: string,
  body: UpdateInvoiceRequest,
requestOptions?: RequestOptions): Promise<ApiResponse<UpdateInvoiceResponse>>

Parameters

Parameter	Type	Tags	Description
`invoiceId`	`string`	Template, Required	The ID of the invoice to update.
`body`	`UpdateInvoiceRequest`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

UpdateInvoiceResponse

Example Usage

const invoiceId = 'invoice_id0';

const body: UpdateInvoiceRequest = {
  invoice: {
    version: 1,
    paymentRequests: [
      {
        uid: '2da7964f-f3d2-4f43-81e8-5aa220bf3355',
        tippingEnabled: false,
        reminders: [
          {},
          {},
          {}
        ],
      }
    ],
  },
  idempotencyKey: '4ee82288-0910-499e-ab4c-5d0071dad1be',
};

try {
  const { result, ...httpResponse } = await invoicesApi.updateInvoice(
  invoiceId,
  body
);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Create Invoice Attachment

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.

async createInvoiceAttachment(  invoiceId: string,
  request?: CreateInvoiceAttachmentRequest,
  imageFile?: FileWrapper,
requestOptions?: RequestOptions): Promise<ApiResponse<CreateInvoiceAttachmentResponse>>

Parameters

Parameter	Type	Tags	Description
`invoiceId`	`string`	Template, Required	The ID of the invoice to attach the file to.
`request`	`CreateInvoiceAttachmentRequest \| undefined`	Form (JSON-Encoded), Optional	Represents a CreateInvoiceAttachment request.
`imageFile`	`FileWrapper \| undefined`	Form, Optional	-
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

CreateInvoiceAttachmentResponse

Example Usage

const invoiceId = 'invoice_id0';

const request: CreateInvoiceAttachmentRequest = {
  idempotencyKey: 'ae5e84f9-4742-4fc1-ba12-a3ce3748f1c3',
  description: 'Service contract',
};

try {
  const { result, ...httpResponse } = await invoicesApi.createInvoiceAttachment(
  invoiceId,
  request
);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Delete Invoice Attachment

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.

async deleteInvoiceAttachment(  invoiceId: string,
  attachmentId: string,
requestOptions?: RequestOptions): Promise<ApiResponse<DeleteInvoiceAttachmentResponse>>

Parameters

Parameter	Type	Tags	Description
`invoiceId`	`string`	Template, Required	The ID of the invoice to delete the attachment from.
`attachmentId`	`string`	Template, Required	The ID of the attachment to delete.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

DeleteInvoiceAttachmentResponse

Example Usage

const invoiceId = 'invoice_id0';

const attachmentId = 'attachment_id6';

try {
  const { result, ...httpResponse } = await invoicesApi.deleteInvoiceAttachment(
  invoiceId,
  attachmentId
);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Cancel Invoice

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.

async cancelInvoice(  invoiceId: string,
  body: CancelInvoiceRequest,
requestOptions?: RequestOptions): Promise<ApiResponse<CancelInvoiceResponse>>

Parameters

Parameter	Type	Tags	Description
`invoiceId`	`string`	Template, Required	The ID of the invoice to cancel.
`body`	`CancelInvoiceRequest`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

CancelInvoiceResponse

Example Usage

const invoiceId = 'invoice_id0';

const body: CancelInvoiceRequest = {
  version: 0,
};

try {
  const { result, ...httpResponse } = await invoicesApi.cancelInvoice(
  invoiceId,
  body
);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Publish Invoice

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 charges a card on file for a portion of the invoice amount.

In addition to the required ORDERS_WRITE and INVOICES_WRITE permissions, CUSTOMERS_READ and PAYMENTS_WRITE are required when publishing invoices configured for card-on-file payments.

async publishInvoice(  invoiceId: string,
  body: PublishInvoiceRequest,
requestOptions?: RequestOptions): Promise<ApiResponse<PublishInvoiceResponse>>

Parameters

Parameter	Type	Tags	Description
`invoiceId`	`string`	Template, Required	The ID of the invoice to publish.
`body`	`PublishInvoiceRequest`	Body, Required	An object containing the fields to POST for the request. See the corresponding object definition for field details.
`requestOptions`	`RequestOptions \| undefined`	Optional	Pass additional request options.

Response Type

PublishInvoiceResponse

Example Usage

const invoiceId = 'invoice_id0';

const body: PublishInvoiceRequest = {
  version: 1,
  idempotencyKey: '32da42d0-1997-41b0-826b-f09464fc2c2e',
};

try {
  const { result, ...httpResponse } = await invoicesApi.publishInvoice(
  invoiceId,
  body
);
  // Get more response info...
  // const { statusCode, headers } = httpResponse;
} catch (error) {
  if (error instanceof ApiError) {
    const errors = error.result;
    // const { statusCode, headers } = error;
  }
}

Files

invoices.md

Latest commit

History

invoices.md

File metadata and controls

Invoices

Class Name

Methods

List Invoices

Parameters

Response Type

Example Usage

Create Invoice

Parameters

Response Type

Example Usage

Search Invoices

Parameters

Response Type

Example Usage

Delete Invoice

Parameters

Response Type

Example Usage

Get Invoice

Parameters

Response Type

Example Usage

Update Invoice

Parameters

Response Type

Example Usage

Create Invoice Attachment

Parameters

Response Type

Example Usage

Delete Invoice Attachment

Parameters

Response Type

Example Usage

Cancel Invoice

Parameters

Response Type

Example Usage

Publish Invoice

Parameters

Response Type

Example Usage