Reference

📝 Description

Revokes an access token generated with the OAuth flow.

If an account has more than one OAuth access token for your application, this endpoint revokes all of them, regardless of which token you specify.

Important: The Authorization header for this endpoint must have the following format:

Authorization: Client APPLICATION_SECRET

Replace APPLICATION_SECRET with the application secret on the OAuth page for your application in the Developer Dashboard.

🔌 Usage

await client.oAuth.revokeToken({
    clientId: "CLIENT_ID",
    accessToken: "ACCESS_TOKEN"
});

⚙️ Parameters

request: Square.RevokeTokenRequest

requestOptions: OAuthClient.RequestOptions

📝 Description

Returns an OAuth access token and refresh token using the authorization_code or refresh_token grant type.

When grant_type is authorization_code:

• With the code flow, provide code, client_id, and client_secret.
• With the PKCE flow, provide code, client_id, and code_verifier.

When grant_type is refresh_token:

• With the code flow, provide refresh_token, client_id, and client_secret. The response returns the same refresh token provided in the request.
• With the PKCE flow, provide refresh_token and client_id. The response returns a new refresh token.

You can use the scopes parameter to limit the set of permissions authorized by the access token. You can use the short_lived parameter to create an access token that expires in 24 hours.

Important: OAuth tokens should be encrypted and stored on a secure server. Application clients should never interact directly with OAuth tokens.

🔌 Usage

await client.oAuth.obtainToken({
    clientId: "sq0idp-uaPHILoPzWZk3tlJqlML0g",
    clientSecret: "sq0csp-30a-4C_tVOnTh14Piza2BfTPBXyLafLPWSzY1qAjeBfM",
    code: "sq0cgb-l0SBqxs4uwxErTVyYOdemg",
    grantType: "authorization_code"
});

⚙️ Parameters

request: Square.ObtainTokenRequest

requestOptions: OAuthClient.RequestOptions

📝 Description

Returns information about an OAuth access token or an application’s personal access token.

Add the access token to the Authorization header of the request.

Important: The Authorization header you provide to this endpoint must have the following format:

Authorization: Bearer ACCESS_TOKEN

where ACCESS_TOKEN is a valid production authorization credential.

If the access token is expired or not a valid access token, the endpoint returns an UNAUTHORIZED error.

🔌 Usage

await client.oAuth.retrieveTokenStatus();

⚙️ Parameters

requestOptions: OAuthClient.RequestOptions

🔌 Usage

await client.oAuth.authorize();

⚙️ Parameters

requestOptions: OAuthClient.RequestOptions

📝 Description

Provides summary information for a merchant's online store orders.

🔌 Usage

await client.v1Transactions.v1ListOrders({
    locationId: "location_id",
    order: "DESC",
    limit: 1,
    batchToken: "batch_token"
});

⚙️ Parameters

request: Square.V1ListOrdersRequest

requestOptions: V1TransactionsClient.RequestOptions

📝 Description

Provides comprehensive information for a single online store order, including the order's history.

🔌 Usage

await client.v1Transactions.v1RetrieveOrder({
    locationId: "location_id",
    orderId: "order_id"
});

⚙️ Parameters

request: Square.V1RetrieveOrderRequest

requestOptions: V1TransactionsClient.RequestOptions

📝 Description

Updates the details of an online store order. Every update you perform on an order corresponds to one of three actions:

🔌 Usage

await client.v1Transactions.v1UpdateOrder({
    locationId: "location_id",
    orderId: "order_id",
    action: "COMPLETE"
});

⚙️ Parameters

request: Square.V1UpdateOrderRequest

requestOptions: V1TransactionsClient.RequestOptions

📝 Description

Activates a domain for use with Apple Pay on the Web and Square. A validation is performed on this domain by Apple to ensure that it is properly set up as an Apple Pay enabled domain.

This endpoint provides an easy way for platform developers to bulk activate Apple Pay on the Web with Square for merchants using their platform.

Note: You will need to host a valid domain verification file on your domain to support Apple Pay. The current version of this file is always available at https://app.squareup.com/digital-wallets/apple-pay/apple-developer-merchantid-domain-association, and should be hosted at .well_known/apple-developer-merchantid-domain-association on your domain. This file is subject to change; we strongly recommend checking for updates regularly and avoiding long-lived caches that might not keep in sync with the correct file version.

To learn more about the Web Payments SDK and how to add Apple Pay, see Take an Apple Pay Payment.

🔌 Usage

await client.applePay.registerDomain({
    domainName: "example.com"
});

⚙️ Parameters

request: Square.RegisterDomainRequest

requestOptions: ApplePayClient.RequestOptions

📝 Description

Returns a list of BankAccount objects linked to a Square account.

🔌 Usage

const pageableResponse = await client.bankAccounts.list({
    cursor: "cursor",
    limit: 1,
    locationId: "location_id",
    customerId: "customer_id"
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.bankAccounts.list({
    cursor: "cursor",
    limit: 1,
    locationId: "location_id",
    customerId: "customer_id"
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.ListBankAccountsRequest

requestOptions: BankAccountsClient.RequestOptions

📝 Description

Store a bank account on file for a square account

🔌 Usage

await client.bankAccounts.createBankAccount({
    idempotencyKey: "4e43559a-f0fd-47d3-9da2-7ea1f97d94be",
    sourceId: "bnon:CA4SEHsQwr0rx6DbWLD5BQaqMnoYAQ",
    customerId: "HM3B2D5JKGZ69359BTEHXM2V8M"
});

⚙️ Parameters

request: Square.CreateBankAccountRequest

requestOptions: BankAccountsClient.RequestOptions

📝 Description

Returns details of a BankAccount identified by V1 bank account ID.

🔌 Usage

await client.bankAccounts.getByV1Id({
    v1BankAccountId: "v1_bank_account_id"
});

⚙️ Parameters

request: Square.GetByV1IdBankAccountsRequest

requestOptions: BankAccountsClient.RequestOptions

📝 Description

Retrieve details of a BankAccount bank account linked to a Square account.

🔌 Usage

await client.bankAccounts.get({
    bankAccountId: "bank_account_id"
});

⚙️ Parameters

request: Square.GetBankAccountsRequest

requestOptions: BankAccountsClient.RequestOptions

📝 Description

Disable a bank account.

🔌 Usage

await client.bankAccounts.disableBankAccount({
    bankAccountId: "bank_account_id"
});

⚙️ Parameters

request: Square.DisableBankAccountRequest

requestOptions: BankAccountsClient.RequestOptions

📝 Description

Retrieve a collection of bookings.

To call this endpoint with buyer-level permissions, set APPOINTMENTS_READ for the OAuth scope. To call this endpoint with seller-level permissions, set APPOINTMENTS_ALL_READ and APPOINTMENTS_READ for the OAuth scope.

🔌 Usage

const pageableResponse = await client.bookings.list({
    limit: 1,
    cursor: "cursor",
    customerId: "customer_id",
    teamMemberId: "team_member_id",
    locationId: "location_id",
    startAtMin: "start_at_min",
    startAtMax: "start_at_max"
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.bookings.list({
    limit: 1,
    cursor: "cursor",
    customerId: "customer_id",
    teamMemberId: "team_member_id",
    locationId: "location_id",
    startAtMin: "start_at_min",
    startAtMax: "start_at_max"
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.ListBookingsRequest

requestOptions: BookingsClient.RequestOptions

📝 Description

Creates a booking.

The required input must include the following:

• Booking.location_id
• Booking.start_at
• Booking.AppointmentSegment.team_member_id
• Booking.AppointmentSegment.service_variation_id
• Booking.AppointmentSegment.service_variation_version

To call this endpoint with buyer-level permissions, set APPOINTMENTS_WRITE for the OAuth scope. To call this endpoint with seller-level permissions, set APPOINTMENTS_ALL_WRITE and APPOINTMENTS_WRITE for the OAuth scope.

For calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to Appointments Plus or Appointments Premium.

🔌 Usage

await client.bookings.create({
    booking: {}
});

⚙️ Parameters

request: Square.CreateBookingRequest

requestOptions: BookingsClient.RequestOptions

📝 Description

Searches for availabilities for booking.

To call this endpoint with buyer-level permissions, set APPOINTMENTS_READ for the OAuth scope. To call this endpoint with seller-level permissions, set APPOINTMENTS_ALL_READ and APPOINTMENTS_READ for the OAuth scope.

🔌 Usage

await client.bookings.searchAvailability({
    query: {
        filter: {
            startAtRange: {}
        }
    }
});

⚙️ Parameters

request: Square.SearchAvailabilityRequest

requestOptions: BookingsClient.RequestOptions

📝 Description

Bulk-Retrieves a list of bookings by booking IDs.

To call this endpoint with buyer-level permissions, set APPOINTMENTS_READ for the OAuth scope. To call this endpoint with seller-level permissions, set APPOINTMENTS_ALL_READ and APPOINTMENTS_READ for the OAuth scope.

🔌 Usage

await client.bookings.bulkRetrieveBookings({
    bookingIds: ["booking_ids"]
});

⚙️ Parameters

request: Square.BulkRetrieveBookingsRequest

requestOptions: BookingsClient.RequestOptions

📝 Description

Retrieves a seller's booking profile.

🔌 Usage

await client.bookings.getBusinessProfile();

⚙️ Parameters

requestOptions: BookingsClient.RequestOptions

📝 Description

Retrieves a seller's location booking profile.

🔌 Usage

await client.bookings.retrieveLocationBookingProfile({
    locationId: "location_id"
});

⚙️ Parameters

request: Square.RetrieveLocationBookingProfileRequest

requestOptions: BookingsClient.RequestOptions

📝 Description

Retrieves one or more team members' booking profiles.

🔌 Usage

await client.bookings.bulkRetrieveTeamMemberBookingProfiles({
    teamMemberIds: ["team_member_ids"]
});

⚙️ Parameters

request: Square.BulkRetrieveTeamMemberBookingProfilesRequest

requestOptions: BookingsClient.RequestOptions

📝 Description

Retrieves a booking.

To call this endpoint with buyer-level permissions, set APPOINTMENTS_READ for the OAuth scope. To call this endpoint with seller-level permissions, set APPOINTMENTS_ALL_READ and APPOINTMENTS_READ for the OAuth scope.

🔌 Usage

await client.bookings.get({
    bookingId: "booking_id"
});

⚙️ Parameters

request: Square.GetBookingsRequest

requestOptions: BookingsClient.RequestOptions

📝 Description

Updates a booking.

To call this endpoint with buyer-level permissions, set APPOINTMENTS_WRITE for the OAuth scope. To call this endpoint with seller-level permissions, set APPOINTMENTS_ALL_WRITE and APPOINTMENTS_WRITE for the OAuth scope.

For calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to Appointments Plus or Appointments Premium.

🔌 Usage

await client.bookings.update({
    bookingId: "booking_id",
    booking: {}
});

⚙️ Parameters

request: Square.UpdateBookingRequest

requestOptions: BookingsClient.RequestOptions

📝 Description

Cancels an existing booking.

To call this endpoint with buyer-level permissions, set APPOINTMENTS_WRITE for the OAuth scope. To call this endpoint with seller-level permissions, set APPOINTMENTS_ALL_WRITE and APPOINTMENTS_WRITE for the OAuth scope.

For calls to this endpoint with seller-level permissions to succeed, the seller must have subscribed to Appointments Plus or Appointments Premium.

🔌 Usage

await client.bookings.cancel({
    bookingId: "booking_id"
});

⚙️ Parameters

request: Square.CancelBookingRequest

requestOptions: BookingsClient.RequestOptions

📝 Description

Retrieves a list of cards owned by the account making the request. A max of 25 cards will be returned.

🔌 Usage

const pageableResponse = await client.cards.list({
    cursor: "cursor",
    customerId: "customer_id",
    includeDisabled: true,
    referenceId: "reference_id",
    sortOrder: "DESC"
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.cards.list({
    cursor: "cursor",
    customerId: "customer_id",
    includeDisabled: true,
    referenceId: "reference_id",
    sortOrder: "DESC"
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.ListCardsRequest

requestOptions: CardsClient.RequestOptions

📝 Description

Adds a card on file to an existing merchant.

🔌 Usage

await client.cards.create({
    idempotencyKey: "4935a656-a929-4792-b97c-8848be85c27c",
    sourceId: "cnon:uIbfJXhXETSP197M3GB",
    card: {
        cardholderName: "Amelia Earhart",
        billingAddress: {
            addressLine1: "500 Electric Ave",
            addressLine2: "Suite 600",
            locality: "New York",
            administrativeDistrictLevel1: "NY",
            postalCode: "10003",
            country: "US"
        },
        customerId: "VDKXEEKPJN48QDG3BGGFAK05P8",
        referenceId: "user-id-1"
    }
});

⚙️ Parameters

request: Square.CreateCardRequest

requestOptions: CardsClient.RequestOptions

📝 Description

Retrieves details for a specific Card.

🔌 Usage

await client.cards.get({
    cardId: "card_id"
});

⚙️ Parameters

request: Square.GetCardsRequest

requestOptions: CardsClient.RequestOptions

📝 Description

Disables the card, preventing any further updates or charges. Disabling an already disabled card is allowed but has no effect.

🔌 Usage

await client.cards.disable({
    cardId: "card_id"
});

⚙️ Parameters

request: Square.DisableCardsRequest

requestOptions: CardsClient.RequestOptions

📝 Description

Deletes a set of CatalogItems based on the provided list of target IDs and returns a set of successfully deleted IDs in the response. Deletion is a cascading event such that all children of the targeted object are also deleted. For example, deleting a CatalogItem will also delete all of its CatalogItemVariation children.

BatchDeleteCatalogObjects succeeds even if only a portion of the targeted IDs can be deleted. The response will only include IDs that were actually deleted.

To ensure consistency, only one delete request is processed at a time per seller account. While one (batch or non-batch) delete request is being processed, other (batched and non-batched) delete requests are rejected with the 429 error code.

🔌 Usage

await client.catalog.batchDelete({
    objectIds: ["W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK"]
});

⚙️ Parameters

request: Square.BatchDeleteCatalogObjectsRequest

requestOptions: CatalogClient.RequestOptions

📝 Description

Returns a set of objects based on the provided ID. Each CatalogItem returned in the set includes all of its child information including: all of its CatalogItemVariation objects, references to its CatalogModifierList objects, and the ids of any CatalogTax objects that apply to it.

🔌 Usage

await client.catalog.batchGet({
    objectIds: ["W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK"],
    includeRelatedObjects: true
});

⚙️ Parameters

request: Square.BatchGetCatalogObjectsRequest

requestOptions: CatalogClient.RequestOptions

📝 Description

Creates or updates up to 10,000 target objects based on the provided list of objects. The target objects are grouped into batches and each batch is inserted/updated in an all-or-nothing manner. If an object within a batch is malformed in some way, or violates a database constraint, the entire batch containing that item will be disregarded. However, other batches in the same request may still succeed. Each batch may contain up to 1,000 objects, and batches will be processed in order as long as the total object count for the request (items, variations, modifier lists, discounts, and taxes) is no more than 10,000.

To ensure consistency, only one update request is processed at a time per seller account. While one (batch or non-batch) update request is being processed, other (batched and non-batched) update requests are rejected with the 429 error code.

🔌 Usage

await client.catalog.batchUpsert({
    idempotencyKey: "789ff020-f723-43a9-b4b5-43b5dc1fa3dc",
    batches: [{
            objects: [{
                    type: "ITEM",
                    id: "id"
                }, {
                    type: "ITEM",
                    id: "id"
                }, {
                    type: "ITEM",
                    id: "id"
                }, {
                    type: "TAX",
                    id: "id"
                }]
        }]
});

⚙️ Parameters

request: Square.BatchUpsertCatalogObjectsRequest

requestOptions: CatalogClient.RequestOptions

📝 Description

Retrieves information about the Square Catalog API, such as batch size limits that can be used by the BatchUpsertCatalogObjects endpoint.

🔌 Usage

await client.catalog.info();

⚙️ Parameters

requestOptions: CatalogClient.RequestOptions

📝 Description

Returns a list of all CatalogObjects of the specified types in the catalog.

The types parameter is specified as a comma-separated list of the CatalogObjectType values, for example, "ITEM, ITEM_VARIATION, MODIFIER, MODIFIER_LIST, CATEGORY, DISCOUNT, TAX, IMAGE".

Important: ListCatalog does not return deleted catalog items. To retrieve deleted catalog items, use SearchCatalogObjects and set the include_deleted_objects attribute value to true.

🔌 Usage

const pageableResponse = await client.catalog.list({
    cursor: "cursor",
    types: "types",
    catalogVersion: BigInt("1000000")
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.catalog.list({
    cursor: "cursor",
    types: "types",
    catalogVersion: BigInt("1000000")
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.ListCatalogRequest

requestOptions: CatalogClient.RequestOptions

📝 Description

Searches for CatalogObject of any type by matching supported search attribute values, excluding custom attribute values on items or item variations, against one or more of the specified query filters.

This (SearchCatalogObjects) endpoint differs from the SearchCatalogItems endpoint in the following aspects:

• SearchCatalogItems can only search for items or item variations, whereas SearchCatalogObjects can search for any type of catalog objects.
• SearchCatalogItems supports the custom attribute query filters to return items or item variations that contain custom attribute values, where SearchCatalogObjects does not.
• SearchCatalogItems does not support the include_deleted_objects filter to search for deleted items or item variations, whereas SearchCatalogObjects does.
• The both endpoints have different call conventions, including the query filter formats.

🔌 Usage

await client.catalog.search({
    objectTypes: ["ITEM"],
    query: {
        prefixQuery: {
            attributeName: "name",
            attributePrefix: "tea"
        }
    },
    limit: 100
});

⚙️ Parameters

request: Square.SearchCatalogObjectsRequest

requestOptions: CatalogClient.RequestOptions

📝 Description

Searches for catalog items or item variations by matching supported search attribute values, including custom attribute values, against one or more of the specified query filters.

This (SearchCatalogItems) endpoint differs from the SearchCatalogObjects endpoint in the following aspects:

• SearchCatalogItems can only search for items or item variations, whereas SearchCatalogObjects can search for any type of catalog objects.
• SearchCatalogItems supports the custom attribute query filters to return items or item variations that contain custom attribute values, where SearchCatalogObjects does not.
• SearchCatalogItems does not support the include_deleted_objects filter to search for deleted items or item variations, whereas SearchCatalogObjects does.
• The both endpoints use different call conventions, including the query filter formats.

🔌 Usage

await client.catalog.searchItems({
    textFilter: "red",
    categoryIds: ["WINE_CATEGORY_ID"],
    stockLevels: ["OUT", "LOW"],
    enabledLocationIds: ["ATL_LOCATION_ID"],
    limit: 100,
    sortOrder: "ASC",
    productTypes: ["REGULAR"],
    customAttributeFilters: [{
            customAttributeDefinitionId: "VEGAN_DEFINITION_ID",
            boolFilter: true
        }, {
            customAttributeDefinitionId: "BRAND_DEFINITION_ID",
            stringFilter: "Dark Horse"
        }, {
            key: "VINTAGE",
            numberFilter: {
                min: "min",
                max: "max"
            }
        }, {
            customAttributeDefinitionId: "VARIETAL_DEFINITION_ID"
        }]
});

⚙️ Parameters

request: Square.SearchCatalogItemsRequest

requestOptions: CatalogClient.RequestOptions

📝 Description

Updates the CatalogModifierList objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.

🔌 Usage

await client.catalog.updateItemModifierLists({
    itemIds: ["H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6"],
    modifierListsToEnable: ["H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6"],
    modifierListsToDisable: ["7WRC16CJZDVLSNDQ35PP6YAD"]
});

⚙️ Parameters

request: Square.UpdateItemModifierListsRequest

requestOptions: CatalogClient.RequestOptions

📝 Description

Updates the CatalogTax objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.

🔌 Usage

await client.catalog.updateItemTaxes({
    itemIds: ["H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6"],
    taxesToEnable: ["4WRCNHCJZDVLSNDQ35PP6YAD"],
    taxesToDisable: ["AQCEGCEBBQONINDOHRGZISEX"]
});

⚙️ Parameters

request: Square.UpdateItemTaxesRequest

requestOptions: CatalogClient.RequestOptions

📝 Description

🔌 Usage

const pageableResponse = await client.channels.list({
    referenceType: "UNKNOWN_TYPE",
    referenceId: "reference_id",
    status: "ACTIVE",
    cursor: "cursor",
    limit: 1
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.channels.list({
    referenceType: "UNKNOWN_TYPE",
    referenceId: "reference_id",
    status: "ACTIVE",
    cursor: "cursor",
    limit: 1
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.ListChannelsRequest

requestOptions: ChannelsClient.RequestOptions

📝 Description

🔌 Usage

await client.channels.bulkRetrieve({
    channelIds: ["CH_9C03D0B59", "CH_6X139B5MN", "NOT_EXISTING"]
});

⚙️ Parameters

request: Square.BulkRetrieveChannelsRequest

requestOptions: ChannelsClient.RequestOptions

📝 Description

🔌 Usage

await client.channels.get({
    channelId: "channel_id"
});

⚙️ Parameters

request: Square.GetChannelsRequest

requestOptions: ChannelsClient.RequestOptions

📝 Description

Lists customer profiles associated with a Square account.

Under normal operating conditions, newly created or updated customer profiles become available for the listing operation in well under 30 seconds. Occasionally, propagation of the new or updated profiles can take closer to one minute or longer, especially during network incidents and outages.

🔌 Usage

const pageableResponse = await client.customers.list({
    cursor: "cursor",
    limit: 1,
    sortField: "DEFAULT",
    sortOrder: "DESC",
    count: true
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.customers.list({
    cursor: "cursor",
    limit: 1,
    sortField: "DEFAULT",
    sortOrder: "DESC",
    count: true
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.ListCustomersRequest

requestOptions: CustomersClient.RequestOptions

📝 Description

Creates a new customer for a business.

You must provide at least one of the following values in your request to this endpoint:

• given_name
• family_name
• company_name
• email_address
• phone_number

🔌 Usage

await client.customers.create({
    givenName: "Amelia",
    familyName: "Earhart",
    emailAddress: "Amelia.Earhart@example.com",
    address: {
        addressLine1: "500 Electric Ave",
        addressLine2: "Suite 600",
        locality: "New York",
        administrativeDistrictLevel1: "NY",
        postalCode: "10003",
        country: "US"
    },
    phoneNumber: "+1-212-555-4240",
    referenceId: "YOUR_REFERENCE_ID",
    note: "a customer"
});

⚙️ Parameters

request: Square.CreateCustomerRequest

requestOptions: CustomersClient.RequestOptions

📝 Description

Creates multiple customer profiles for a business.

This endpoint takes a map of individual create requests and returns a map of responses.

You must provide at least one of the following values in each create request:

• given_name
• family_name
• company_name
• email_address
• phone_number

🔌 Usage

await client.customers.batchCreate({
    customers: {
        "8bb76c4f-e35d-4c5b-90de-1194cd9179f0": {
            givenName: "Amelia",
            familyName: "Earhart",
            emailAddress: "Amelia.Earhart@example.com",
            address: {
                addressLine1: "500 Electric Ave",
                addressLine2: "Suite 600",
                locality: "New York",
                administrativeDistrictLevel1: "NY",
                postalCode: "10003",
                country: "US"
            },
            phoneNumber: "+1-212-555-4240",
            referenceId: "YOUR_REFERENCE_ID",
            note: "a customer"
        },
        "d1689f23-b25d-4932-b2f0-aed00f5e2029": {
            givenName: "Marie",
            familyName: "Curie",
            emailAddress: "Marie.Curie@example.com",
            address: {
                addressLine1: "500 Electric Ave",
                addressLine2: "Suite 601",
                locality: "New York",
                administrativeDistrictLevel1: "NY",
                postalCode: "10003",
                country: "US"
            },
            phoneNumber: "+1-212-444-4240",
            referenceId: "YOUR_REFERENCE_ID",
            note: "another customer"
        }
    }
});

⚙️ Parameters

request: Square.BulkCreateCustomersRequest

requestOptions: CustomersClient.RequestOptions

📝 Description

Deletes multiple customer profiles.

The endpoint takes a list of customer IDs and returns a map of responses.

🔌 Usage

await client.customers.bulkDeleteCustomers({
    customerIds: ["8DDA5NZVBZFGAX0V3HPF81HHE0", "N18CPRVXR5214XPBBA6BZQWF3C", "2GYD7WNXF7BJZW1PMGNXZ3Y8M8"]
});

⚙️ Parameters

request: Square.BulkDeleteCustomersRequest

requestOptions: CustomersClient.RequestOptions

📝 Description

Retrieves multiple customer profiles.

This endpoint takes a list of customer IDs and returns a map of responses.

🔌 Usage

await client.customers.bulkRetrieveCustomers({
    customerIds: ["8DDA5NZVBZFGAX0V3HPF81HHE0", "N18CPRVXR5214XPBBA6BZQWF3C", "2GYD7WNXF7BJZW1PMGNXZ3Y8M8"]
});

⚙️ Parameters

request: Square.BulkRetrieveCustomersRequest

requestOptions: CustomersClient.RequestOptions

📝 Description

Updates multiple customer profiles.

This endpoint takes a map of individual update requests and returns a map of responses.

🔌 Usage

await client.customers.bulkUpdateCustomers({
    customers: {
        "8DDA5NZVBZFGAX0V3HPF81HHE0": {
            emailAddress: "New.Amelia.Earhart@example.com",
            note: "updated customer note",
            version: BigInt("2")
        },
        "N18CPRVXR5214XPBBA6BZQWF3C": {
            givenName: "Marie",
            familyName: "Curie",
            version: BigInt("0")
        }
    }
});

⚙️ Parameters

request: Square.BulkUpdateCustomersRequest

requestOptions: CustomersClient.RequestOptions

📝 Description

Searches the customer profiles associated with a Square account using one or more supported query filters.

Calling SearchCustomers without any explicit query filter returns all customer profiles ordered alphabetically based on given_name and family_name.

Under normal operating conditions, newly created or updated customer profiles become available for the search operation in well under 30 seconds. Occasionally, propagation of the new or updated profiles can take closer to one minute or longer, especially during network incidents and outages.

🔌 Usage

await client.customers.search({
    limit: BigInt("2"),
    query: {
        filter: {
            creationSource: {
                values: ["THIRD_PARTY"],
                rule: "INCLUDE"
            },
            createdAt: {
                startAt: "2018-01-01T00:00:00-00:00",
                endAt: "2018-02-01T00:00:00-00:00"
            },
            emailAddress: {
                fuzzy: "example.com"
            },
            groupIds: {
                all: ["545AXB44B4XXWMVQ4W8SBT3HHF"]
            }
        },
        sort: {
            field: "CREATED_AT",
            order: "ASC"
        }
    }
});

⚙️ Parameters

request: Square.SearchCustomersRequest

requestOptions: CustomersClient.RequestOptions

📝 Description

Returns details for a single customer.

🔌 Usage

await client.customers.get({
    customerId: "customer_id"
});

⚙️ Parameters

request: Square.GetCustomersRequest

requestOptions: CustomersClient.RequestOptions

📝 Description

Updates a customer profile. This endpoint supports sparse updates, so only new or changed fields are required in the request. To add or update a field, specify the new value. To remove a field, specify null.

To update a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.

🔌 Usage

await client.customers.update({
    customerId: "customer_id",
    emailAddress: "New.Amelia.Earhart@example.com",
    note: "updated customer note",
    version: BigInt("2")
});

⚙️ Parameters

request: Square.UpdateCustomerRequest

requestOptions: CustomersClient.RequestOptions

📝 Description

Deletes a customer profile from a business.

To delete a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile.

🔌 Usage

await client.customers.delete({
    customerId: "customer_id",
    version: BigInt("1000000")
});

⚙️ Parameters

request: Square.DeleteCustomersRequest

requestOptions: CustomersClient.RequestOptions

📝 Description

List devices associated with the merchant. Currently, only Terminal API devices are supported.

🔌 Usage

const pageableResponse = await client.devices.list({
    cursor: "cursor",
    sortOrder: "DESC",
    limit: 1,
    locationId: "location_id"
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.devices.list({
    cursor: "cursor",
    sortOrder: "DESC",
    limit: 1,
    locationId: "location_id"
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.ListDevicesRequest

requestOptions: DevicesClient.RequestOptions

📝 Description

Retrieves Device with the associated device_id.

🔌 Usage

await client.devices.get({
    deviceId: "device_id"
});

⚙️ Parameters

request: Square.GetDevicesRequest

requestOptions: DevicesClient.RequestOptions

📝 Description

Returns a list of disputes associated with a particular account.

🔌 Usage

const pageableResponse = await client.disputes.list({
    cursor: "cursor",
    states: "INQUIRY_EVIDENCE_REQUIRED",
    locationId: "location_id"
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.disputes.list({
    cursor: "cursor",
    states: "INQUIRY_EVIDENCE_REQUIRED",
    locationId: "location_id"
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.ListDisputesRequest

requestOptions: DisputesClient.RequestOptions

📝 Description

Returns details about a specific dispute.

🔌 Usage

await client.disputes.get({
    disputeId: "dispute_id"
});

⚙️ Parameters

request: Square.GetDisputesRequest

requestOptions: DisputesClient.RequestOptions

📝 Description

Accepts the loss on a dispute. Square returns the disputed amount to the cardholder and updates the dispute state to ACCEPTED.

Square debits the disputed amount from the seller’s Square account. If the Square account does not have sufficient funds, Square debits the associated bank account.

🔌 Usage

await client.disputes.accept({
    disputeId: "dispute_id"
});

⚙️ Parameters

request: Square.AcceptDisputesRequest

requestOptions: DisputesClient.RequestOptions

📝 Description

Uploads a file to use as evidence in a dispute challenge. The endpoint accepts HTTP multipart/form-data file uploads in HEIC, HEIF, JPEG, PDF, PNG, and TIFF formats.

🔌 Usage

await client.disputes.createEvidenceFile({
    disputeId: "dispute_id"
});

⚙️ Parameters

request: Square.CreateEvidenceFileDisputesRequest

requestOptions: DisputesClient.RequestOptions

📝 Description

Uploads text to use as evidence for a dispute challenge.

🔌 Usage

await client.disputes.createEvidenceText({
    disputeId: "dispute_id",
    idempotencyKey: "ed3ee3933d946f1514d505d173c82648",
    evidenceType: "TRACKING_NUMBER",
    evidenceText: "1Z8888888888888888"
});

⚙️ Parameters

request: Square.CreateDisputeEvidenceTextRequest

requestOptions: DisputesClient.RequestOptions

📝 Description

Submits evidence to the cardholder's bank.

The evidence submitted by this endpoint includes evidence uploaded using the CreateDisputeEvidenceFile and CreateDisputeEvidenceText endpoints and evidence automatically provided by Square, when available. Evidence cannot be removed from a dispute after submission.

🔌 Usage

await client.disputes.submitEvidence({
    disputeId: "dispute_id"
});

⚙️ Parameters

request: Square.SubmitEvidenceDisputesRequest

requestOptions: DisputesClient.RequestOptions

📝 Description

🔌 Usage

const pageableResponse = await client.employees.list({
    locationId: "location_id",
    status: "ACTIVE",
    limit: 1,
    cursor: "cursor"
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.employees.list({
    locationId: "location_id",
    status: "ACTIVE",
    limit: 1,
    cursor: "cursor"
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.ListEmployeesRequest

requestOptions: EmployeesClient.RequestOptions

📝 Description

🔌 Usage

await client.employees.get({
    id: "id"
});

⚙️ Parameters

request: Square.GetEmployeesRequest

requestOptions: EmployeesClient.RequestOptions

📝 Description

Search for Square API events that occur within a 28-day timeframe.

🔌 Usage

await client.events.searchEvents();

⚙️ Parameters

request: Square.SearchEventsRequest

requestOptions: EventsClient.RequestOptions

📝 Description

Disables events to prevent them from being searchable. All events are disabled by default. You must enable events to make them searchable. Disabling events for a specific time period prevents them from being searchable, even if you re-enable them later.

🔌 Usage

await client.events.disableEvents();

⚙️ Parameters

requestOptions: EventsClient.RequestOptions

📝 Description

Enables events to make them searchable. Only events that occur while in the enabled state are searchable.

🔌 Usage

await client.events.enableEvents();

⚙️ Parameters

requestOptions: EventsClient.RequestOptions

📝 Description

Lists all event types that you can subscribe to as webhooks or query using the Events API.

🔌 Usage

await client.events.listEventTypes({
    apiVersion: "api_version"
});

⚙️ Parameters

request: Square.ListEventTypesRequest

requestOptions: EventsClient.RequestOptions

📝 Description

Lists all gift cards. You can specify optional filters to retrieve a subset of the gift cards. Results are sorted by created_at in ascending order.

🔌 Usage

const pageableResponse = await client.giftCards.list({
    type: "type",
    state: "state",
    limit: 1,
    cursor: "cursor",
    customerId: "customer_id"
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.giftCards.list({
    type: "type",
    state: "state",
    limit: 1,
    cursor: "cursor",
    customerId: "customer_id"
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.ListGiftCardsRequest

requestOptions: GiftCardsClient.RequestOptions

📝 Description

Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card has a PENDING state. To activate a gift card so that it can be redeemed for purchases, call CreateGiftCardActivity and create an ACTIVATE activity with the initial balance. Alternatively, you can use RefundPayment to refund a payment to the new gift card.

🔌 Usage

await client.giftCards.create({
    idempotencyKey: "NC9Tm69EjbjtConu",
    locationId: "81FN9BNFZTKS4",
    giftCard: {
        type: "DIGITAL"
    }
});

⚙️ Parameters

request: Square.CreateGiftCardRequest

requestOptions: GiftCardsClient.RequestOptions

📝 Description

Retrieves a gift card using the gift card account number (GAN).

🔌 Usage

await client.giftCards.getFromGan({
    gan: "7783320001001635"
});

⚙️ Parameters

request: Square.GetGiftCardFromGanRequest

requestOptions: GiftCardsClient.RequestOptions

📝 Description

Retrieves a gift card using a secure payment token that represents the gift card.

🔌 Usage

await client.giftCards.getFromNonce({
    nonce: "cnon:7783322135245171"
});

⚙️ Parameters

request: Square.GetGiftCardFromNonceRequest

requestOptions: GiftCardsClient.RequestOptions

📝 Description

Links a customer to a gift card, which is also referred to as adding a card on file.

🔌 Usage

await client.giftCards.linkCustomer({
    giftCardId: "gift_card_id",
    customerId: "GKY0FZ3V717AH8Q2D821PNT2ZW"
});

⚙️ Parameters

request: Square.LinkCustomerToGiftCardRequest

requestOptions: GiftCardsClient.RequestOptions

📝 Description

Unlinks a customer from a gift card, which is also referred to as removing a card on file.

🔌 Usage

await client.giftCards.unlinkCustomer({
    giftCardId: "gift_card_id",
    customerId: "GKY0FZ3V717AH8Q2D821PNT2ZW"
});

⚙️ Parameters

request: Square.UnlinkCustomerFromGiftCardRequest

requestOptions: GiftCardsClient.RequestOptions

📝 Description

Retrieves a gift card using the gift card ID.

🔌 Usage

await client.giftCards.get({
    id: "id"
});

⚙️ Parameters

request: Square.GetGiftCardsRequest

requestOptions: GiftCardsClient.RequestOptions

📝 Description

Deprecated version of RetrieveInventoryAdjustment after the endpoint URL is updated to conform to the standard convention.

🔌 Usage

await client.inventory.deprecatedGetAdjustment({
    adjustmentId: "adjustment_id"
});

⚙️ Parameters

request: Square.DeprecatedGetAdjustmentInventoryRequest

requestOptions: InventoryClient.RequestOptions

📝 Description

Returns the InventoryAdjustment object with the provided adjustment_id.

🔌 Usage

await client.inventory.getAdjustment({
    adjustmentId: "adjustment_id"
});

⚙️ Parameters

request: Square.GetAdjustmentInventoryRequest

requestOptions: InventoryClient.RequestOptions

📝 Description

Deprecated version of BatchChangeInventory after the endpoint URL is updated to conform to the standard convention.

🔌 Usage

await client.inventory.deprecatedBatchChange({
    idempotencyKey: "8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe",
    changes: [{
            type: "PHYSICAL_COUNT",
            physicalCount: {
                referenceId: "1536bfbf-efed-48bf-b17d-a197141b2a92",
                catalogObjectId: "W62UWFY35CWMYGVWK6TWJDNI",
                state: "IN_STOCK",
                locationId: "C6W5YS5QM06F5",
                quantity: "53",
                teamMemberId: "LRK57NSQ5X7PUD05",
                occurredAt: "2016-11-16T22:25:24.878Z"
            }
        }],
    ignoreUnchangedCounts: true
});

⚙️ Parameters

request: Square.BatchChangeInventoryRequest

requestOptions: InventoryClient.RequestOptions

📝 Description

Deprecated version of BatchRetrieveInventoryChanges after the endpoint URL is updated to conform to the standard convention.

🔌 Usage

await client.inventory.deprecatedBatchGetChanges({
    catalogObjectIds: ["W62UWFY35CWMYGVWK6TWJDNI"],
    locationIds: ["C6W5YS5QM06F5"],
    types: ["PHYSICAL_COUNT"],
    states: ["IN_STOCK"],
    updatedAfter: "2016-11-01T00:00:00.000Z",
    updatedBefore: "2016-12-01T00:00:00.000Z"
});

⚙️ Parameters

request: Square.BatchRetrieveInventoryChangesRequest

requestOptions: InventoryClient.RequestOptions

📝 Description

Deprecated version of BatchRetrieveInventoryCounts after the endpoint URL is updated to conform to the standard convention.

🔌 Usage

await client.inventory.deprecatedBatchGetCounts({
    catalogObjectIds: ["W62UWFY35CWMYGVWK6TWJDNI"],
    locationIds: ["59TNP9SA8VGDA"],
    updatedAfter: "2016-11-16T00:00:00.000Z"
});

⚙️ Parameters

request: Square.BatchGetInventoryCountsRequest

requestOptions: InventoryClient.RequestOptions

📝 Description

Applies adjustments and counts to the provided item quantities.

On success: returns the current calculated counts for all objects referenced in the request. On failure: returns a list of related errors.

🔌 Usage

await client.inventory.batchCreateChanges({
    idempotencyKey: "8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe",
    changes: [{
            type: "PHYSICAL_COUNT",
            physicalCount: {
                referenceId: "1536bfbf-efed-48bf-b17d-a197141b2a92",
                catalogObjectId: "W62UWFY35CWMYGVWK6TWJDNI",
                state: "IN_STOCK",
                locationId: "C6W5YS5QM06F5",
                quantity: "53",
                teamMemberId: "LRK57NSQ5X7PUD05",
                occurredAt: "2016-11-16T22:25:24.878Z"
            }
        }],
    ignoreUnchangedCounts: true
});

⚙️ Parameters

request: Square.BatchChangeInventoryRequest

requestOptions: InventoryClient.RequestOptions

📝 Description

Returns historical physical counts and adjustments based on the provided filter criteria.

Results are paginated and sorted in ascending order according their occurred_at timestamp (oldest first).

BatchRetrieveInventoryChanges is a catch-all query endpoint for queries that cannot be handled by other, simpler endpoints.

🔌 Usage

const pageableResponse = await client.inventory.batchGetChanges({
    catalogObjectIds: ["W62UWFY35CWMYGVWK6TWJDNI"],
    locationIds: ["C6W5YS5QM06F5"],
    types: ["PHYSICAL_COUNT"],
    states: ["IN_STOCK"],
    updatedAfter: "2016-11-01T00:00:00.000Z",
    updatedBefore: "2016-12-01T00:00:00.000Z"
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.inventory.batchGetChanges({
    catalogObjectIds: ["W62UWFY35CWMYGVWK6TWJDNI"],
    locationIds: ["C6W5YS5QM06F5"],
    types: ["PHYSICAL_COUNT"],
    states: ["IN_STOCK"],
    updatedAfter: "2016-11-01T00:00:00.000Z",
    updatedBefore: "2016-12-01T00:00:00.000Z"
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.BatchRetrieveInventoryChangesRequest

requestOptions: InventoryClient.RequestOptions

📝 Description

Returns current counts for the provided CatalogObjects at the requested Locations.

Results are paginated and sorted in descending order according to their calculated_at timestamp (newest first).

When updated_after is specified, only counts that have changed since that time (based on the server timestamp for the most recent change) are returned. This allows clients to perform a "sync" operation, for example in response to receiving a Webhook notification.

🔌 Usage

const pageableResponse = await client.inventory.batchGetCounts({
    catalogObjectIds: ["W62UWFY35CWMYGVWK6TWJDNI"],
    locationIds: ["59TNP9SA8VGDA"],
    updatedAfter: "2016-11-16T00:00:00.000Z"
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.inventory.batchGetCounts({
    catalogObjectIds: ["W62UWFY35CWMYGVWK6TWJDNI"],
    locationIds: ["59TNP9SA8VGDA"],
    updatedAfter: "2016-11-16T00:00:00.000Z"
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.BatchGetInventoryCountsRequest

requestOptions: InventoryClient.RequestOptions

📝 Description

Deprecated version of RetrieveInventoryPhysicalCount after the endpoint URL is updated to conform to the standard convention.

🔌 Usage

await client.inventory.deprecatedGetPhysicalCount({
    physicalCountId: "physical_count_id"
});

⚙️ Parameters

request: Square.DeprecatedGetPhysicalCountInventoryRequest

requestOptions: InventoryClient.RequestOptions

📝 Description

Returns the InventoryPhysicalCount object with the provided physical_count_id.

🔌 Usage

await client.inventory.getPhysicalCount({
    physicalCountId: "physical_count_id"
});

⚙️ Parameters

request: Square.GetPhysicalCountInventoryRequest

requestOptions: InventoryClient.RequestOptions

📝 Description

Returns the InventoryTransfer object with the provided transfer_id.

🔌 Usage

await client.inventory.getTransfer({
    transferId: "transfer_id"
});

⚙️ Parameters

request: Square.GetTransferInventoryRequest

requestOptions: InventoryClient.RequestOptions

📝 Description

Retrieves the current calculated stock count for a given CatalogObject at a given set of Locations. Responses are paginated and unsorted. For more sophisticated queries, use a batch endpoint.

🔌 Usage

const pageableResponse = await client.inventory.get({
    catalogObjectId: "catalog_object_id",
    locationIds: "location_ids",
    cursor: "cursor"
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.inventory.get({
    catalogObjectId: "catalog_object_id",
    locationIds: "location_ids",
    cursor: "cursor"
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.GetInventoryRequest

requestOptions: InventoryClient.RequestOptions

📝 Description

Returns a set of physical counts and inventory adjustments for the provided CatalogObject at the requested Locations.

You can achieve the same result by calling BatchRetrieveInventoryChanges and having the catalog_object_ids list contain a single element of the CatalogObject ID.

Results are paginated and sorted in descending order according to their occurred_at timestamp (newest first).

There are no limits on how far back the caller can page. This endpoint can be used to display recent changes for a specific item. For more sophisticated queries, use a batch endpoint.

🔌 Usage

const pageableResponse = await client.inventory.changes({
    catalogObjectId: "catalog_object_id",
    locationIds: "location_ids",
    cursor: "cursor"
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.inventory.changes({
    catalogObjectId: "catalog_object_id",
    locationIds: "location_ids",
    cursor: "cursor"
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.ChangesInventoryRequest

requestOptions: InventoryClient.RequestOptions

📝 Description

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.

🔌 Usage

const pageableResponse = await client.invoices.list({
    locationId: "location_id",
    cursor: "cursor",
    limit: 1
});
for await (const item of pageableResponse) {
    console.log(item);
}

// Or you can manually iterate page-by-page
let page = await client.invoices.list({
    locationId: "location_id",
    cursor: "cursor",
    limit: 1
});
while (page.hasNextPage()) {
    page = page.getNextPage();
}

// You can also access the underlying response
const response = page.response;

⚙️ Parameters

request: Square.ListInvoicesRequest

requestOptions: InvoicesClient.RequestOptions

📝 Description

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

🔌 Usage

await client.invoices.create({
    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"
});

⚙️ Parameters

request: Square.CreateInvoiceRequest

requestOptions: InvoicesClient.RequestOptions

📝 Description

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.

🔌 Usage

await client.invoices.search({
    query: {
        filter: {
            locationIds: ["ES0RJRZYEC39A"],
            customerIds: ["JDKYHBWT1D4F8MFH63DBMEN8Y4"]
        },
        sort: {
            field: "INVOICE_SORT_DATE",
            order: "DESC"
        }
    },
    limit: 100
});

⚙️ Parameters

request: Square.SearchInvoicesRequest

requestOptions: InvoicesClient.RequestOptions

📝 Description

Retrieves an invoice by invoice ID.

🔌 Usage

await client.invoices.get({
    invoiceId: "invoice_id"
});

⚙️ Parameters

request: Square.GetInvoicesRequest

requestOptions: InvoicesClient.RequestOptions

📝 Description

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.

🔌 Usage

await client.invoices.update({
    invoiceId: "invoice_id",
    invoice: {
        version: 1,
        paymentRequests: [{
                uid: "2da7964f-f3d2-4f43-81e8-5aa220bf3355",
                tippingEnabled: false
            }]
    },
    idempotencyKey: "4ee82288-0910-499e-ab4c-5d0071dad1be"
});

⚙️ Parameters

request: Square.UpdateInvoiceRequest

requestOptions: InvoicesClient.RequestOptions

📝 Description

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

🔌 Usage

await client.invoices.delete({
    invoiceId: "invoice_id",
    version: 1
});

⚙️ Parameters

request: Square.DeleteInvoicesRequest

requestOptions: InvoicesClient.RequestOptions

📝 Description

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.

NOTE: When testing in the Sandbox environment, the total file size is limited to 1 KB.

🔌 Usage

await client.invoices.createInvoiceAttachment({
    invoiceId: "invoice_id"
});

⚙️ Parameters

request: Square.CreateInvoiceAttachmentRequest

requestOptions: InvoicesClient.RequestOptions

📝 Description

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.

🔌 Usage

await client.invoices.deleteInvoiceAttachment({
    invoiceId: "invoice_id",
    attachmentId: "attachment_id"
});

⚙️ Parameters

request: Square.DeleteInvoiceAttachmentRequest

requestOptions: InvoicesClient.RequestOptions

📝 Description

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.

🔌 Usage

await client.invoices.cancel({
    invoiceId: "invoice_id",
    version: 0
});

⚙️ Parameters

request: Square.CancelInvoiceRequest

requestOptions: InvoicesClient.RequestOptions

📝 Description

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.

🔌 Usage

await client.invoices.publish({
    invoiceId: "invoice_id",
    version: 1,
    idempotencyKey: "32da42d0-1997-41b0-826b-f09464fc2c2e"
});

⚙️ Parameters

request: Square.PublishInvoiceRequest

requestOptions: InvoicesClient.RequestOptions

📝 Description

Creates a scheduled shift by providing draft shift details such as job ID, team member assignment, and start and end times.

The following draft_shift_details fields are required:

• location_id
• job_id
• start_at
• end_at

🔌 Usage

await client.labor.createScheduledShift({
    idempotencyKey: "HIDSNG5KS478L",
    scheduledShift: {
        draftShiftDetails: {
            teamMemberId: "ormj0jJJZ5OZIzxrZYJI",
            locationId: "PAA1RJZZKXBFG",
            jobId: "FzbJAtt9qEWncK1BWgVCxQ6M",
            startAt: "2019-01-25T03:11:00-05:00",
            endAt: "2019-01-25T13:11:00-05:00",
            notes: "Dont forget to prep the vegetables",
            isDeleted: false
        }
    }
});

⚙️ Parameters

request: Square.CreateScheduledShiftRequest

requestOptions: LaborClient.RequestOptions

📝 Description

Publishes 1 - 100 scheduled shifts. This endpoint takes a map of individual publish requests and returns a map of responses. When a scheduled shift is published, Square keeps the draft_shift_details field as is and copies it to the published_shift_details field.

The minimum start_at and maximum end_at timestamps of all shifts in a BulkPublishScheduledShifts request must fall within a two-week period.

🔌 Usage

await client.labor.bulkPublishScheduledShifts({
    scheduledShifts: {
        "key": {}
    },
    scheduledShiftNotificationAudience: "AFFECTED"
});

⚙️ Parameters

request: Square.BulkPublishScheduledShiftsRequest

requestOptions: LaborClient.RequestOptions

📝 Description

Returns a paginated list of scheduled shifts, with optional filter and sort settings. By default, results are sorted by start_at in ascending order.

🔌 Usage

await client.labor.searchScheduledShifts({
    query: {
        filter: {
            assignmentStatus: "ASSIGNED"
        },
        sort: {
            field: "CREATED_AT",
            order: "ASC"
        }
    },
    limit: 2,
    cursor: "xoxp-1234-5678-90123"
});

⚙️ Parameters

request: Square.SearchScheduledShiftsRequest

requestOptions: LaborClient.RequestOptions

📝 Description

Retrieves a scheduled shift by ID.

🔌 Usage

await client.labor.retrieveScheduledShift({
    id: "id"
});

⚙️ Parameters

request: Square.RetrieveScheduledShiftRequest

requestOptions: LaborClient.RequestOptions

📝 Description

Updates the draft shift details for a scheduled shift. This endpoint supports sparse updates, so only new, changed, or removed fields are required in the request. You must publish the shift to make updates public.

You can make the following updates to draft_shift_details:

• Change the location_id, job_id, start_at, and end_at fields.
• Add, change, or clear the team_member_id and notes fields. To clear these fields, set the value to null.
• Change the is_deleted field. To delete a scheduled shift, set is_deleted to true and then publish the shift.

🔌 Usage

await client.labor.updateScheduledShift({
    id: "id",
    scheduledShift: {
        draftShiftDetails: {
            teamMemberId: "ormj0jJJZ5OZIzxrZYJI",
            locationId: "PAA1RJZZKXBFG",
            jobId: "FzbJAtt9qEWncK1BWgVCxQ6M",
            startAt: "2019-03-25T03:11:00-05:00",
            endAt: "2019-03-25T13:18:00-05:00",
            notes: "Dont forget to prep the vegetables",
            isDeleted: false
        },
        version: 1
    }
});

⚙️ Parameters

request: Square.UpdateScheduledShiftRequest

requestOptions: LaborClient.RequestOptions

📝 Description

Publishes a scheduled shift. When a scheduled shift is published, Square keeps the draft_shift_details field as is and copies it to the published_shift_details field.

🔌 Usage

await client.labor.publishScheduledShift({
    id: "id",
    idempotencyKey: "HIDSNG5KS478L",
    version: 2,
    scheduledShiftNotificationAudience: "ALL"
});

⚙️ Parameters

request: Square.PublishScheduledShiftRequest

requestOptions: LaborClient.RequestOptions

📝 Description

Creates a new Timecard.

A Timecard represents a complete workday for a single team member. You must provide the following values in your request to this endpoint:

• location_id
• team_member_id
• start_at

An attempt to create a new Timecard can result in a BAD_REQUEST error when:

• The status of the new Timecard is OPEN and the team member has another timecard with an OPEN status.
• The start_at date is in the future.
• The start_at or end_at date overlaps another timecard for the same team member.
• The Break instances are set in the request and a break start_at is before the Timecard.start_at, a break end_at is after the Timecard.end_at, or both.

🔌 Usage

await client.labor.createTimecard({
    idempotencyKey: "HIDSNG5KS478L",
    timecard: {
        locationId: "PAA1RJZZKXBFG",
        startAt: "2019-01-25T03:11:00-05:00",
        endAt: "2019-01-25T13:11:00-05:00",
        wage: {
            title: "Barista",
            hourlyRate: {
                amount: BigInt("1100"),
                currency: "USD"
            },
            tipEligible: true
        },
        breaks: [{
                startAt: "2019-01-25T06:11:00-05:00",
                endAt: "2019-01-25T06:16:00-05:00",
                breakTypeId: "REGS1EQR1TPZ5",
                name: "Tea Break",
                expectedDuration: "PT5M",
                isPaid: true
            }],
        teamMemberId: "ormj0jJJZ5OZIzxrZYJI",
        declaredCashTipMoney: {
            amount: BigInt("500"),
            currency: "USD"
        }
    }
});

⚙️ Parameters

request: Square.CreateTimecardRequest

requestOptions: LaborClient.RequestOptions

📝 Description

Returns a paginated list of Timecard records for a business. The list to be returned can be filtered by:

• Location IDs
• Team member IDs
• Timecard status (OPEN or CLOSED)
• Timecard start
• Timecard end
• Workday details

The list can be sorted by:

• START_AT
• END_AT
• CREATED_AT
• UPDATED_AT

🔌 Usage

await client.labor.searchTimecards({
    query: {
        filter: {
            workday: {
                dateRange: {
                    startDate: "2019-01-20",
                    endDate: "2019-02-03"
                },
                matchTimecardsBy: "START_AT",
                defaultTimezone: "America/Los_Angeles"
            }
        }
    },
    limit: 100
});

⚙️ Parameters

request: Square.SearchTimecardsRequest

requestOptions: LaborClient.RequestOptions

📝 Description

Returns a single Timecard specified by id.

🔌 Usage

await client.labor.retrieveTimecard({
    id: "id"
});

⚙️ Parameters

request: Square.RetrieveTimecardRequest

requestOptions: LaborClient.RequestOptions

📝 Description

Updates an existing Timecard.

When adding a Break to a Timecard, any earlier Break instances in the Timecard have the end_at property set to a valid RFC-3339 datetime string.

When closing a Timecard, all Break instances in the Timecard must be complete with end_at set on each Break.

🔌 Usage

await client.labor.updateTimecard({
    id: "id",
    timecard: {
        locationId: "PAA1RJZZKXBFG",
        startAt: "2019-01-25T03:11:00-05:00",
        endAt: "2019-01-25T13:11:00-05:00",
        wage: {
            title: "Bartender",
            hourlyRate: {
                amount: BigInt("1500"),
                currency: "USD"
            },
            tipEligible: true
        },
        breaks: [{
                id: "X7GAQYVVRRG6P",
                startAt: "2019-01-25T06:11:00-05:00",
                endAt: "2019-01-25T06:16:00-05:00",
                breakTypeId: "REGS1EQR1TPZ5",
                name: "Tea Break",
                expectedDuration: "PT5M",
                isPaid: true
            }],
        status: "CLOSED",
        version: 1,
        teamMemberId: "ormj0jJJZ5OZIzxrZYJI",
        declaredCashTipMoney: {
            amount: BigInt("500"),
            currency: "USD"
        }
    }
});

⚙️ Parameters

request: Square.UpdateTimecardRequest

requestOptions: LaborClient.RequestOptions

📝 Description

Deletes a Timecard.

🔌 Usage

await client.labor.deleteTimecard({
    id: "id"
});

⚙️ Parameters

request: Square.DeleteTimecardRequest

requestOptions: LaborClient.RequestOptions

📝 Description

Provides details about all of the seller's locations, including those with an inactive status. Locations are listed alphabetically by name.

🔌 Usage

await client.locations.list();

⚙️ Parameters

requestOptions: LocationsClient.RequestOptions

📝 Description

Creates a location. Creating new locations allows for separate configuration of receipt layouts, item prices, and sales reports. Developers can use locations to separate sales activity through applications that integrate with Square from sales activity elsewhere in a seller's account. Locations created programmatically with the Locations API last forever and are visible to the seller for their own management. Therefore, ensure that each location has a sensible and unique name.

🔌 Usage

await client.locations.create({
    location: {
        name: "Midtown",
        address: {
            addressLine1: "1234 Peachtree St. NE",
            locality: "Atlanta",
            administrativeDistrictLevel1: "GA",
            postalCode: "30309"
        },
        description: "Midtown Atlanta store"
    }
});

⚙️ Parameters

request: Square.CreateLocationRequest

requestOptions: LocationsClient.RequestOptions

📝 Description

Retrieves details of a single location. Specify "main" as the location ID to retrieve details of the main location.

🔌 Usage

await client.locations.get({
    locationId: "location_id"
});

⚙️ Parameters

request: Square.GetLocationsRequest

requestOptions: LocationsClient.RequestOptions

📝 Description

Updates a location.

🔌 Usage

await client.locations.update({
    locationId: "location_id",
    location: {
        businessHours: {
            periods: [{
                    dayOfWeek: "FRI",
                    startLocalTime: "07:00",
                    endLocalTime: "18:00"
                }, {
                    dayOfWeek: "SAT",
                    startLocalTime: "07:00",
                    endLocalTime: "18:00"
                }, {
                    dayOfWeek: "SUN",
                    startLocalTime: "09:00",
                    endLocalTime: "15:00"
                }]
        },
        description: "Midtown Atlanta store - Open weekends"
    }
});

⚙️ Parameters

request: Square.UpdateLocationRequest

requestOptions: LocationsClient.RequestOptions

📝 Description

Links a checkoutId to a checkout_page_url that customers are directed to in order to provide their payment information using a payment processing workflow hosted on connect.squareup.com.

NOTE: The Checkout API has been updated with new features. For more information, see Checkout API highlights.

🔌 Usage

await client.locations.checkouts({
    locationId: "location_id",
    idempotencyKey: "86ae1696-b1e3-4328-af6d-f1e04d947ad6",
    order: {
        order: {
            locationId: "location_id",
            referenceId: "reference_id",
            customerId: "customer_id",
            lineItems: [{
                    name: "Printed T Shirt",
                    quantity: "2",
                    appliedTaxes: [{
                            taxUid: "38ze1696-z1e3-5628-af6d-f1e04d947fg3"
                        }],
                    appliedDiscounts: [{
                            discountUid: "56ae1696-z1e3-9328-af6d-f1e04d947gd4"
                        }],
                    basePriceMoney: {
                        amount: BigInt("1500"),
                        currency: "USD"
                    }
                }, {
                    name: "Slim Jeans",
                    quantity: "1",
                    basePriceMoney: {
                        amount: BigInt("2500"),
                        currency: "USD"
                    }
                }, {
                    name: "Woven Sweater",
                    quantity: "3",
                    basePriceMoney: {
                        amount: BigInt("3500"),
                        currency: "USD"
                    }
                }],
            taxes: [{
                    uid: "38ze1696-z1e3-5628-af6d-f1e04d947fg3",
                    type: "INCLUSIVE",
                    percentage: "7.75",
                    scope: "LINE_ITEM"
                }],
            discounts: [{
                    uid: "56ae1696-z1e3-9328-af6d-f1e04d947gd4",
                    type: "FIXED_AMOUNT",
                    amountMoney: {
                        amount: BigInt("100"),
                        currency: "USD"
                    },
                    scope: "LINE_ITEM"
                }]
        },
        idempotencyKey: "12ae1696-z1e3-4328-af6d-f1e04d947gd4"
    },
    askForShippingAddress: true,
    merchantSupportEmail: "merchant+support@website.com",
    prePopulateBuyerEmail: "example@email.com",
    prePopulateShippingAddress: {
        addressLine1: "1455 Market St.",
        addressLine2: "Suite 600",
        locality: "San Francisco",
        administrativeDistrictLevel1: "CA",
        postalCode: "94103",
        country: "US",
        firstName: "Jane",
        lastName: "Doe"
    },
    redirectUrl: "https://merchant.website.com/order-confirm",
    additionalRecipients: [{
            locationId: "057P5VYJ4A5X1",
            description: "Application fees",
            amountMoney: {
                amount: BigInt("60"),
                currency: "USD"
            }
        }]
});