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

client.oAuth().revokeToken(
    RevokeTokenRequest
        .builder()
        .clientId("CLIENT_ID")
        .accessToken("ACCESS_TOKEN")
        .build()
);

⚙️ Parameters

clientId: Optional<String>

The Square-issued ID for your application, which is available on the OAuth page in the Developer Dashboard.

accessToken: Optional<String>

The access token of the merchant whose token you want to revoke. Do not provide a value for merchant_id if you provide this parameter.

merchantId: Optional<String>

The ID of the merchant whose token you want to revoke. Do not provide a value for access_token if you provide this parameter.

revokeOnlyAccessToken: Optional<Boolean>

If true, terminate the given single access token, but do not terminate the entire authorization. Default: false

📝 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

client.oAuth().obtainToken(
    ObtainTokenRequest
        .builder()
        .clientId("sq0idp-uaPHILoPzWZk3tlJqlML0g")
        .grantType("authorization_code")
        .clientSecret("sq0csp-30a-4C_tVOnTh14Piza2BfTPBXyLafLPWSzY1qAjeBfM")
        .code("sq0cgb-l0SBqxs4uwxErTVyYOdemg")
        .build()
);

⚙️ Parameters

clientId: String

The Square-issued ID of your application, which is available as the Application ID on the OAuth page in the Developer Console.

Required for the code flow and PKCE flow for any grant type.

clientSecret: Optional<String>

The secret key for your application, which is available as the Application secret on the OAuth page in the Developer Console.

Required for the code flow for any grant type. Don't confuse your client secret with your personal access token.

code: Optional<String>

The authorization code to exchange for an OAuth access token. This is the code value that Square sent to your redirect URL in the authorization response.

Required for the code flow and PKCE flow if grant_type is authorization_code.

redirectUri: Optional<String>

The redirect URL for your application, which you registered as the Redirect URL on the OAuth page in the Developer Console.

Required for the code flow and PKCE flow if grant_type is authorization_code and you provided the redirect_uri parameter in your authorization URL.

grantType: String

The method used to obtain an OAuth access token. The request must include the credential that corresponds to the specified grant type. Valid values are:

• authorization_code - Requires the code field.
• refresh_token - Requires the refresh_token field.
• migration_token - LEGACY for access tokens obtained using a Square API version prior to 2019-03-13. Requires the migration_token field.

refreshToken: Optional<String>

A valid refresh token used to generate a new OAuth access token. This is a refresh token that was returned in a previous ObtainToken response.

Required for the code flow and PKCE flow if grant_type is refresh_token.

migrationToken: Optional<String>

LEGACY A valid access token (obtained using a Square API version prior to 2019-03-13) used to generate a new OAuth access token.

Required if grant_type is migration_token. For more information, see Migrate to Using Refresh Tokens.

scopes: Optional<List<String>>

The list of permissions that are explicitly requested for the access token. For example, ["MERCHANT_PROFILE_READ","PAYMENTS_READ","BANK_ACCOUNTS_READ"].

The returned access token is limited to the permissions that are the intersection of these requested permissions and those authorized by the provided refresh_token.

Optional for the code flow and PKCE flow if grant_type is refresh_token.

shortLived: Optional<Boolean>

Indicates whether the returned access token should expire in 24 hours.

Optional for the code flow and PKCE flow for any grant type. The default value is false.

codeVerifier: Optional<String>

The secret your application generated for the authorization request used to obtain the authorization code. This is the source of the code_challenge hash you provided in your authorization URL.

Required for the PKCE flow if grant_type is authorization_code.

useJwt: Optional<Boolean>

Indicates whether to use a JWT (JSON Web Token) as the OAuth access token. When set to true, the OAuth flow returns a JWT to your application, used in the same way as a regular token. The default value is false.

📝 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

client.oAuth().retrieveTokenStatus();

🔌 Usage

client.oAuth().authorize();

📝 Description

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

🔌 Usage

client.v1Transactions().v1ListOrders(
    V1ListOrdersRequest
        .builder()
        .locationId("location_id")
        .order(SortOrder.DESC)
        .limit(1)
        .batchToken("batch_token")
        .build()
);

⚙️ Parameters

locationId: String — The ID of the location to list online store orders for.

order: Optional<SortOrder> — The order in which payments are listed in the response.

limit: Optional<Integer> — The maximum number of payments to return in a single response. This value cannot exceed 200.

batchToken: Optional<String>

A pagination cursor to retrieve the next set of results for your original query to the endpoint.

📝 Description

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

🔌 Usage

client.v1Transactions().v1RetrieveOrder(
    V1RetrieveOrderRequest
        .builder()
        .locationId("location_id")
        .orderId("order_id")
        .build()
);

⚙️ Parameters

locationId: String — The ID of the order's associated location.

orderId: String — The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint

📝 Description

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

🔌 Usage

client.v1Transactions().v1UpdateOrder(
    V1UpdateOrderRequest
        .builder()
        .locationId("location_id")
        .orderId("order_id")
        .action(V1UpdateOrderRequestAction.COMPLETE)
        .build()
);

⚙️ Parameters

locationId: String — The ID of the order's associated location.

orderId: String — The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint

action: V1UpdateOrderRequestAction

The action to perform on the order (COMPLETE, CANCEL, or REFUND). See V1UpdateOrderRequestAction for possible values

shippedTrackingNumber: Optional<String> — The tracking number of the shipment associated with the order. Only valid if action is COMPLETE.

completedNote: Optional<String> — A merchant-specified note about the completion of the order. Only valid if action is COMPLETE.

refundedNote: Optional<String> — A merchant-specified note about the refunding of the order. Only valid if action is REFUND.

canceledNote: Optional<String> — A merchant-specified note about the canceling of the order. Only valid if action is CANCEL.

📝 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

client.applePay().registerDomain(
    RegisterDomainRequest
        .builder()
        .domainName("example.com")
        .build()
);

⚙️ Parameters

domainName: String — A domain name as described in RFC-1034 that will be registered with ApplePay.

📝 Description

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

🔌 Usage

client.bankAccounts().list(
    ListBankAccountsRequest
        .builder()
        .cursor("cursor")
        .limit(1)
        .locationId("location_id")
        .customerId("customer_id")
        .build()
);

⚙️ Parameters

cursor: Optional<String>

The pagination cursor returned by a previous call to this endpoint. Use it in the next ListBankAccounts request to retrieve the next set of results.

See the Pagination guide for more information.

limit: Optional<Integer>

Upper limit on the number of bank accounts to return in the response. Currently, 1000 is the largest supported limit. You can specify a limit of up to 1000 bank accounts. This is also the default limit.

locationId: Optional<String>

Location ID. You can specify this optional filter to retrieve only the linked bank accounts belonging to a specific location.

customerId: Optional<String>

Customer ID. You can specify this optional filter to retrieve only the linked bank accounts belonging to a specific customer.

📝 Description

Store a bank account on file for a square account

🔌 Usage

client.bankAccounts().createBankAccount(
    CreateBankAccountRequest
        .builder()
        .idempotencyKey("4e43559a-f0fd-47d3-9da2-7ea1f97d94be")
        .sourceId("bnon:CA4SEHsQwr0rx6DbWLD5BQaqMnoYAQ")
        .customerId("HM3B2D5JKGZ69359BTEHXM2V8M")
        .build()
);

⚙️ Parameters

idempotencyKey: String

Unique ID. For more information, see the Idempotency.

sourceId: String

The ID of the source that represents the bank account information to be stored. This field accepts the payment token created by WebSDK

customerId: Optional<String> — The ID of the customer associated with the bank account to be stored.

📝 Description

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

🔌 Usage

client.bankAccounts().getByV1Id(
    GetByV1IdBankAccountsRequest
        .builder()
        .v1BankAccountId("v1_bank_account_id")
        .build()
);

⚙️ Parameters

v1BankAccountId: String

Connect V1 ID of the desired BankAccount. For more information, see Retrieve a bank account by using an ID issued by V1 Bank Accounts API.

📝 Description

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

🔌 Usage

client.bankAccounts().get(
    GetBankAccountsRequest
        .builder()
        .bankAccountId("bank_account_id")
        .build()
);

⚙️ Parameters

bankAccountId: String — Square-issued ID of the desired BankAccount.

📝 Description

Disable a bank account.

🔌 Usage

client.bankAccounts().disableBankAccount(
    DisableBankAccountRequest
        .builder()
        .bankAccountId("bank_account_id")
        .build()
);

⚙️ Parameters

bankAccountId: String — The ID of the bank account to disable.

📝 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

client.bookings().list(
    ListBookingsRequest
        .builder()
        .limit(1)
        .cursor("cursor")
        .customerId("customer_id")
        .teamMemberId("team_member_id")
        .locationId("location_id")
        .startAtMin("start_at_min")
        .startAtMax("start_at_max")
        .build()
);

⚙️ Parameters

limit: Optional<Integer> — The maximum number of results per page to return in a paged response.

cursor: Optional<String> — The pagination cursor from the preceding response to return the next page of the results. Do not set this when retrieving the first page of the results.

customerId: Optional<String> — The customer for whom to retrieve bookings. If this is not set, bookings for all customers are retrieved.

teamMemberId: Optional<String> — The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved.

locationId: Optional<String> — The location for which to retrieve bookings. If this is not set, all locations' bookings are retrieved.

startAtMin: Optional<String> — The RFC 3339 timestamp specifying the earliest of the start time. If this is not set, the current time is used.

startAtMax: Optional<String> — The RFC 3339 timestamp specifying the latest of the start time. If this is not set, the time of 31 days after start_at_min is used.

📝 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

client.bookings().create(
    CreateBookingRequest
        .builder()
        .booking(
            Booking
                .builder()
                .build()
        )
        .build()
);

⚙️ Parameters

idempotencyKey: Optional<String> — A unique key to make this request an idempotent operation.

booking: Booking — The details of the booking to be created.

📝 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

client.bookings().searchAvailability(
    SearchAvailabilityRequest
        .builder()
        .query(
            SearchAvailabilityQuery
                .builder()
                .filter(
                    SearchAvailabilityFilter
                        .builder()
                        .startAtRange(
                            TimeRange
                                .builder()
                                .build()
                        )
                        .build()
                )
                .build()
        )
        .build()
);

⚙️ Parameters

query: SearchAvailabilityQuery — Query conditions used to filter buyer-accessible booking availabilities.

📝 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

client.bookings().bulkRetrieveBookings(
    BulkRetrieveBookingsRequest
        .builder()
        .bookingIds(
            Arrays.asList("booking_ids")
        )
        .build()
);

⚙️ Parameters

bookingIds: List<String> — A non-empty list of Booking IDs specifying bookings to retrieve.

📝 Description

Retrieves a seller's booking profile.

🔌 Usage

client.bookings().getBusinessProfile();

📝 Description

Retrieves a seller's location booking profile.

🔌 Usage

client.bookings().retrieveLocationBookingProfile(
    RetrieveLocationBookingProfileRequest
        .builder()
        .locationId("location_id")
        .build()
);

⚙️ Parameters

locationId: String — The ID of the location to retrieve the booking profile.

📝 Description

Retrieves one or more team members' booking profiles.

🔌 Usage

client.bookings().bulkRetrieveTeamMemberBookingProfiles(
    BulkRetrieveTeamMemberBookingProfilesRequest
        .builder()
        .teamMemberIds(
            Arrays.asList("team_member_ids")
        )
        .build()
);

⚙️ Parameters

teamMemberIds: List<String> — A non-empty list of IDs of team members whose booking profiles you want to retrieve.

📝 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

client.bookings().get(
    GetBookingsRequest
        .builder()
        .bookingId("booking_id")
        .build()
);

⚙️ Parameters

bookingId: String — The ID of the Booking object representing the to-be-retrieved booking.

📝 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

client.bookings().update(
    UpdateBookingRequest
        .builder()
        .bookingId("booking_id")
        .booking(
            Booking
                .builder()
                .build()
        )
        .build()
);

⚙️ Parameters

bookingId: String — The ID of the Booking object representing the to-be-updated booking.

idempotencyKey: Optional<String> — A unique key to make this request an idempotent operation.

booking: Booking — The booking to be updated. Individual attributes explicitly specified here override the corresponding values of the existing booking.

📝 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

client.bookings().cancel(
    CancelBookingRequest
        .builder()
        .bookingId("booking_id")
        .build()
);

⚙️ Parameters

bookingId: String — The ID of the Booking object representing the to-be-cancelled booking.

idempotencyKey: Optional<String> — A unique key to make this request an idempotent operation.

bookingVersion: Optional<Integer> — The revision number for the booking used for optimistic concurrency.

📝 Description

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

🔌 Usage

client.cards().list(
    ListCardsRequest
        .builder()
        .cursor("cursor")
        .customerId("customer_id")
        .includeDisabled(true)
        .referenceId("reference_id")
        .sortOrder(SortOrder.DESC)
        .build()
);

⚙️ Parameters

cursor: Optional<String>

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query.

See Pagination for more information.

customerId: Optional<String>

Limit results to cards associated with the customer supplied. By default, all cards owned by the merchant are returned.

includeDisabled: Optional<Boolean>

Includes disabled cards. By default, all enabled cards owned by the merchant are returned.

referenceId: Optional<String> — Limit results to cards associated with the reference_id supplied.

sortOrder: Optional<SortOrder>

Sorts the returned list by when the card was created with the specified order. This field defaults to ASC.

📝 Description

Adds a card on file to an existing merchant.

🔌 Usage

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

⚙️ Parameters

idempotencyKey: String

A unique string that identifies this CreateCard request. Keys can be any valid string and must be unique for every request.

Max: 45 characters

See Idempotency keys for more information.

sourceId: String — The ID of the source which represents the card information to be stored. This can be a card nonce or a payment id.

verificationToken: Optional<String>

An identifying token generated by Payments.verifyBuyer(). Verification tokens encapsulate customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity.

See the SCA Overview.

card: Card — Payment details associated with the card to be stored.

📝 Description

Retrieves details for a specific Card.

🔌 Usage

client.cards().get(
    GetCardsRequest
        .builder()
        .cardId("card_id")
        .build()
);

⚙️ Parameters

cardId: String — Unique ID for the desired Card.

📝 Description

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

🔌 Usage

client.cards().disable(
    DisableCardsRequest
        .builder()
        .cardId("card_id")
        .build()
);

⚙️ Parameters

cardId: String — Unique ID for the desired Card.

📝 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

client.catalog().batchDelete(
    BatchDeleteCatalogObjectsRequest
        .builder()
        .objectIds(
            Arrays.asList("W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK")
        )
        .build()
);

⚙️ Parameters

objectIds: List<String>

The IDs of the CatalogObjects to be deleted. When an object is deleted, other objects in the graph that depend on that object will be deleted as well (for example, deleting a CatalogItem will delete its CatalogItemVariation.

📝 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

client.catalog().batchGet(
    BatchGetCatalogObjectsRequest
        .builder()
        .objectIds(
            Arrays.asList("W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK")
        )
        .includeRelatedObjects(true)
        .build()
);

⚙️ Parameters

objectIds: List<String> — The IDs of the CatalogObjects to be retrieved.

includeRelatedObjects: Optional<Boolean>

If true, the response will include additional objects that are related to the requested objects. Related objects are defined as any objects referenced by ID by the results in the objects field of the response. These objects are put in the related_objects field. Setting this to true is helpful when the objects are needed for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example,

if the objects field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects and CatalogModifierLists will be returned in the related_objects field of the response. If the objects field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in the related_objects field of the response.

Default value: false

catalogVersion: Optional<Long>

The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects' version attribute. If not included, results will be from the current version of the catalog.

includeDeletedObjects: Optional<Boolean> — Indicates whether to include (true) or not (false) in the response deleted objects, namely, those with the is_deleted attribute set to true.

includeCategoryPathToRoot: Optional<Boolean>

Specifies whether or not to include the path_to_root list for each returned category instance. The path_to_root list consists of CategoryPathToRootNode objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the path_to_root list is empty and is not returned in the response payload.

📝 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

client.catalog().batchUpsert(
    BatchUpsertCatalogObjectsRequest
        .builder()
        .idempotencyKey("789ff020-f723-43a9-b4b5-43b5dc1fa3dc")
        .batches(
            Arrays.asList(
                CatalogObjectBatch
                    .builder()
                    .objects(
                        Arrays.asList(
                            CatalogObject.item(
                                CatalogObjectItem
                                    .builder()
                                    .id("id")
                                    .build()
                            ),
                            CatalogObject.item(
                                CatalogObjectItem
                                    .builder()
                                    .id("id")
                                    .build()
                            ),
                            CatalogObject.item(
                                CatalogObjectItem
                                    .builder()
                                    .id("id")
                                    .build()
                            ),
                            CatalogObject.tax(
                                CatalogObjectTax
                                    .builder()
                                    .id("id")
                                    .build()
                            )
                        )
                    )
                    .build()
            )
        )
        .build()
);

⚙️ Parameters

idempotencyKey: String

A value you specify that uniquely identifies this request among all your requests. A common way to create a valid idempotency key is to use a Universally unique identifier (UUID).

If you're unsure whether a particular request was successful, you can reattempt it with the same idempotency key without worrying about creating duplicate objects.

See Idempotency for more information.

batches: List<CatalogObjectBatch>

A batch of CatalogObjects to be inserted/updated atomically. The objects within a batch will be inserted in an all-or-nothing fashion, i.e., if an error occurs attempting to insert or update an object within a batch, the entire batch will be rejected. However, an error in one batch will not affect other batches within the same request.

For each object, its updated_at field is ignored and replaced with a current timestamp, and its is_deleted field must not be set to true.

To modify an existing object, supply its ID. To create a new object, use an ID starting with #. These IDs may be used to create relationships between an object and attributes of other objects that reference it. For example, you can create a CatalogItem with ID #ABC and a CatalogItemVariation with its item_id attribute set to #ABC in order to associate the CatalogItemVariation with its parent CatalogItem.

Any #-prefixed IDs are valid only within a single atomic batch, and will be replaced by server-generated IDs.

Each batch may contain up to 1,000 objects. The total number of objects across all batches for a single request may not exceed 10,000. If either of these limits is violated, an error will be returned and no objects will be inserted or updated.

📝 Description

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

🔌 Usage

client.catalog().info();

📝 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

client.catalog().list(
    ListCatalogRequest
        .builder()
        .cursor("cursor")
        .types("types")
        .catalogVersion(1000000L)
        .build()
);

⚙️ Parameters

cursor: Optional<String>

The pagination cursor returned in the previous response. Leave unset for an initial request. The page size is currently set to be 100. See Pagination for more information.

types: Optional<String>

An optional case-insensitive, comma-separated list of object types to retrieve.

The valid values are defined in the CatalogObjectType enum, for example, ITEM, ITEM_VARIATION, CATEGORY, DISCOUNT, TAX, MODIFIER, MODIFIER_LIST, IMAGE, etc.

If this is unspecified, the operation returns objects of all the top level types at the version of the Square API used to make the request. Object types that are nested onto other object types are not included in the defaults.

At the current API version the default object types are: ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS.

catalogVersion: Optional<Long>

The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects' version attribute. If not included, results will be from the current version of the catalog.

📝 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

client.catalog().search(
    SearchCatalogObjectsRequest
        .builder()
        .objectTypes(
            Optional.of(
                Arrays.asList(CatalogObjectType.ITEM)
            )
        )
        .query(
            CatalogQuery
                .builder()
                .prefixQuery(
                    CatalogQueryPrefix
                        .builder()
                        .attributeName("name")
                        .attributePrefix("tea")
                        .build()
                )
                .build()
        )
        .limit(100)
        .build()
);

⚙️ Parameters

cursor: Optional<String>

The pagination cursor returned in the previous response. Leave unset for an initial request. See Pagination for more information.

objectTypes: Optional<List<CatalogObjectType>>

The desired set of object types to appear in the search results.

If this is unspecified, the operation returns objects of all the top level types at the version of the Square API used to make the request. Object types that are nested onto other object types are not included in the defaults.

At the current API version the default object types are: ITEM, CATEGORY, TAX, DISCOUNT, MODIFIER_LIST, PRICING_RULE, PRODUCT_SET, TIME_PERIOD, MEASUREMENT_UNIT, SUBSCRIPTION_PLAN, ITEM_OPTION, CUSTOM_ATTRIBUTE_DEFINITION, QUICK_AMOUNT_SETTINGS.

Note that if you wish for the query to return objects belonging to nested types (i.e., COMPONENT, IMAGE, ITEM_OPTION_VAL, ITEM_VARIATION, or MODIFIER), you must explicitly include all the types of interest in this field.

includeDeletedObjects: Optional<Boolean> — If true, deleted objects will be included in the results. Defaults to false. Deleted objects will have their is_deleted field set to true. If include_deleted_objects is true, then the include_category_path_to_root request parameter must be false. Both properties cannot be true at the same time.

includeRelatedObjects: Optional<Boolean>

If true, the response will include additional objects that are related to the requested objects. Related objects are objects that are referenced by object ID by the objects in the response. This is helpful if the objects are being fetched for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example:

If the objects field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects and CatalogModifierLists will be returned in the related_objects field of the response. If the objects field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in the related_objects field of the response.

Default value: false

beginTime: Optional<String>

Return objects modified after this timestamp, in RFC 3339 format, e.g., 2016-09-04T23:59:33.123Z. The timestamp is exclusive - objects with a timestamp equal to begin_time will not be included in the response.

query: Optional<CatalogQuery> — A query to be used to filter or sort the results. If no query is specified, the entire catalog will be returned.

limit: Optional<Integer>

A limit on the number of results to be returned in a single page. The limit is advisory - the implementation may return more or fewer results. If the supplied limit is negative, zero, or is higher than the maximum limit of 1,000, it will be ignored.

includeCategoryPathToRoot: Optional<Boolean> — Specifies whether or not to include the path_to_root list for each returned category instance. The path_to_root list consists of CategoryPathToRootNode objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the path_to_root list is empty and is not returned in the response payload. If include_category_path_to_root is true, then the include_deleted_objects request parameter must be false. Both properties cannot be true at the same time.

📝 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

client.catalog().searchItems(
    SearchCatalogItemsRequest
        .builder()
        .textFilter("red")
        .categoryIds(
            Optional.of(
                Arrays.asList("WINE_CATEGORY_ID")
            )
        )
        .stockLevels(
            Optional.of(
                Arrays.asList(SearchCatalogItemsRequestStockLevel.OUT, SearchCatalogItemsRequestStockLevel.LOW)
            )
        )
        .enabledLocationIds(
            Optional.of(
                Arrays.asList("ATL_LOCATION_ID")
            )
        )
        .limit(100)
        .sortOrder(SortOrder.ASC)
        .productTypes(
            Optional.of(
                Arrays.asList(CatalogItemProductType.REGULAR)
            )
        )
        .customAttributeFilters(
            Optional.of(
                Arrays.asList(
                    CustomAttributeFilter
                        .builder()
                        .customAttributeDefinitionId("VEGAN_DEFINITION_ID")
                        .boolFilter(true)
                        .build(),
                    CustomAttributeFilter
                        .builder()
                        .customAttributeDefinitionId("BRAND_DEFINITION_ID")
                        .stringFilter("Dark Horse")
                        .build(),
                    CustomAttributeFilter
                        .builder()
                        .key("VINTAGE")
                        .numberFilter(
                            Range
                                .builder()
                                .min("min")
                                .max("max")
                                .build()
                        )
                        .build(),
                    CustomAttributeFilter
                        .builder()
                        .customAttributeDefinitionId("VARIETAL_DEFINITION_ID")
                        .build()
                )
            )
        )
        .build()
);

⚙️ Parameters

textFilter: Optional<String>

The text filter expression to return items or item variations containing specified text in the name, description, or abbreviation attribute value of an item, or in the name, sku, or upc attribute value of an item variation.

categoryIds: Optional<List<String>> — The category id query expression to return items containing the specified category IDs.

stockLevels: Optional<List<SearchCatalogItemsRequestStockLevel>>

The stock-level query expression to return item variations with the specified stock levels. See SearchCatalogItemsRequestStockLevel for possible values

enabledLocationIds: Optional<List<String>> — The enabled-location query expression to return items and item variations having specified enabled locations.

cursor: Optional<String> — The pagination token, returned in the previous response, used to fetch the next batch of pending results.

limit: Optional<Integer> — The maximum number of results to return per page. The default value is 100.

sortOrder: Optional<SortOrder>

The order to sort the results by item names. The default sort order is ascending (ASC). See SortOrder for possible values

productTypes: Optional<List<CatalogItemProductType>> — The product types query expression to return items or item variations having the specified product types.

customAttributeFilters: Optional<List<CustomAttributeFilter>>

The customer-attribute filter to return items or item variations matching the specified custom attribute expressions. A maximum number of 10 custom attribute expressions are supported in a single call to the SearchCatalogItems endpoint.

archivedState: Optional<ArchivedState> — The query filter to return not archived (ARCHIVED_STATE_NOT_ARCHIVED), archived (ARCHIVED_STATE_ARCHIVED), or either type (ARCHIVED_STATE_ALL) of items.

📝 Description

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

🔌 Usage

client.catalog().updateItemModifierLists(
    UpdateItemModifierListsRequest
        .builder()
        .itemIds(
            Arrays.asList("H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6")
        )
        .modifierListsToEnable(
            Optional.of(
                Arrays.asList("H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6")
            )
        )
        .modifierListsToDisable(
            Optional.of(
                Arrays.asList("7WRC16CJZDVLSNDQ35PP6YAD")
            )
        )
        .build()
);

⚙️ Parameters

itemIds: List<String> — The IDs of the catalog items associated with the CatalogModifierList objects being updated.

modifierListsToEnable: Optional<List<String>>

The IDs of the CatalogModifierList objects to enable for the CatalogItem. At least one of modifier_lists_to_enable or modifier_lists_to_disable must be specified.

modifierListsToDisable: Optional<List<String>>

The IDs of the CatalogModifierList objects to disable for the CatalogItem. At least one of modifier_lists_to_enable or modifier_lists_to_disable must be specified.

📝 Description

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

🔌 Usage

client.catalog().updateItemTaxes(
    UpdateItemTaxesRequest
        .builder()
        .itemIds(
            Arrays.asList("H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6")
        )
        .taxesToEnable(
            Optional.of(
                Arrays.asList("4WRCNHCJZDVLSNDQ35PP6YAD")
            )
        )
        .taxesToDisable(
            Optional.of(
                Arrays.asList("AQCEGCEBBQONINDOHRGZISEX")
            )
        )
        .build()
);

⚙️ Parameters

itemIds: List<String>

IDs for the CatalogItems associated with the CatalogTax objects being updated. No more than 1,000 IDs may be provided.

taxesToEnable: Optional<List<String>>

IDs of the CatalogTax objects to enable. At least one of taxes_to_enable or taxes_to_disable must be specified.

taxesToDisable: Optional<List<String>>

IDs of the CatalogTax objects to disable. At least one of taxes_to_enable or taxes_to_disable must be specified.

📝 Description

🔌 Usage

client.channels().list(
    ListChannelsRequest
        .builder()
        .referenceType(ReferenceType.UNKNOWN_TYPE)
        .referenceId("reference_id")
        .status(ChannelStatus.ACTIVE)
        .cursor("cursor")
        .limit(1)
        .build()
);

⚙️ Parameters

referenceType: Optional<ReferenceType> — Type of reference associated to channel

referenceId: Optional<String> — id of reference associated to channel

status: Optional<ChannelStatus> — Status of channel

cursor: Optional<String> — Cursor to fetch the next result

limit: Optional<Integer>

Maximum number of results to return. When not provided the returned results will be cap at 100 channels.

📝 Description

🔌 Usage

client.channels().bulkRetrieve(
    BulkRetrieveChannelsRequest
        .builder()
        .channelIds(
            Arrays.asList("CH_9C03D0B59", "CH_6X139B5MN", "NOT_EXISTING")
        )
        .build()
);

⚙️ Parameters

channelIds: List<String>

📝 Description

🔌 Usage

client.channels().get(
    GetChannelsRequest
        .builder()
        .channelId("channel_id")
        .build()
);

⚙️ Parameters

channelId: String — A channel id

📝 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

client.customers().list(
    ListCustomersRequest
        .builder()
        .cursor("cursor")
        .limit(1)
        .sortField(CustomerSortField.DEFAULT)
        .sortOrder(SortOrder.DESC)
        .count(true)
        .build()
);

⚙️ Parameters

cursor: Optional<String>

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: Optional<Integer>

The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is less than 1 or greater than 100, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 100.

For more information, see Pagination.

sortField: Optional<CustomerSortField>

Indicates how customers should be sorted.

The default value is DEFAULT.

sortOrder: Optional<SortOrder>

Indicates whether customers should be sorted in ascending (ASC) or descending (DESC) order.

The default value is ASC.

count: Optional<Boolean>

Indicates whether to return the total count of customers in the count field of the response.

The default value is false.

📝 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

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

⚙️ Parameters

idempotencyKey: Optional<String>

The idempotency key for the request. For more information, see Idempotency.

givenName: Optional<String>

The given name (that is, the first name) associated with the customer profile.

The maximum length for this value is 300 characters.

familyName: Optional<String>

The family name (that is, the last name) associated with the customer profile.

The maximum length for this value is 300 characters.

companyName: Optional<String>

A business name associated with the customer profile.

The maximum length for this value is 500 characters.

nickname: Optional<String>

A nickname for the customer profile.

The maximum length for this value is 100 characters.

emailAddress: Optional<String>

The email address associated with the customer profile.

The maximum length for this value is 254 characters.

address: Optional<Address>

The physical address associated with the customer profile. For maximum length constraints, see Customer addresses. The first_name and last_name fields are ignored if they are present in the request.

phoneNumber: Optional<String>

The phone number associated with the customer profile. The phone number must be valid and can contain 9–16 digits, with an optional + prefix and country code. For more information, see Customer phone numbers.

referenceId: Optional<String>

An optional second ID used to associate the customer profile with an entity in another system.

The maximum length for this value is 100 characters.

note: Optional<String> — A custom note associated with the customer profile.

birthday: Optional<String>

The birthday associated with the customer profile, in YYYY-MM-DD or MM-DD format. For example, specify 1998-09-21 for September 21, 1998, or 09-21 for September 21. Birthdays are returned in YYYY-MM-DD format, where YYYY is the specified birth year or 0000 if a birth year is not specified.

taxIds: Optional<CustomerTaxIds>

The tax ID associated with the customer profile. This field is available only for customers of sellers in EU countries or the United Kingdom. For more information, see Customer tax IDs.

📝 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

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

⚙️ Parameters

customers: Map<String, BulkCreateCustomerData>

A map of 1 to 100 individual create requests, represented by idempotency key: { customer data } key-value pairs.

Each key is an idempotency key that uniquely identifies the create request. Each value contains the customer data used to create the customer profile.

📝 Description

Deletes multiple customer profiles.

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

🔌 Usage

client.customers().bulkDeleteCustomers(
    BulkDeleteCustomersRequest
        .builder()
        .customerIds(
            Arrays.asList("8DDA5NZVBZFGAX0V3HPF81HHE0", "N18CPRVXR5214XPBBA6BZQWF3C", "2GYD7WNXF7BJZW1PMGNXZ3Y8M8")
        )
        .build()
);

⚙️ Parameters

customerIds: List<String> — The IDs of the customer profiles to delete.

📝 Description

Retrieves multiple customer profiles.

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

🔌 Usage

client.customers().bulkRetrieveCustomers(
    BulkRetrieveCustomersRequest
        .builder()
        .customerIds(
            Arrays.asList("8DDA5NZVBZFGAX0V3HPF81HHE0", "N18CPRVXR5214XPBBA6BZQWF3C", "2GYD7WNXF7BJZW1PMGNXZ3Y8M8")
        )
        .build()
);

⚙️ Parameters

customerIds: List<String> — The IDs of the customer profiles to retrieve.

📝 Description

Updates multiple customer profiles.

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

🔌 Usage

client.customers().bulkUpdateCustomers(
    BulkUpdateCustomersRequest
        .builder()
        .customers(
            new HashMap<String, BulkUpdateCustomerData>() {{
                put("8DDA5NZVBZFGAX0V3HPF81HHE0", BulkUpdateCustomerData
                    .builder()
                    .emailAddress(Optional.of("New.Amelia.Earhart@example.com"))
                    .note(Optional.of("updated customer note"))
                    .version(Optional.of(2L))
                    .build());
                put("N18CPRVXR5214XPBBA6BZQWF3C", BulkUpdateCustomerData
                    .builder()
                    .givenName(Optional.of("Marie"))
                    .familyName(Optional.of("Curie"))
                    .version(Optional.of(0L))
                    .build());
            }}
        )
        .build()
);

⚙️ Parameters

customers: Map<String, BulkUpdateCustomerData>

A map of 1 to 100 individual update requests, represented by customer ID: { customer data } key-value pairs.

Each key is the ID of the customer profile to update. To update a customer profile that was created by merging existing profiles, provide the ID of the newly created profile.

Each value contains the updated customer data. Only new or changed fields are required. To add or update a field, specify the new value. To remove a field, specify null.

📝 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

client.customers().search(
    SearchCustomersRequest
        .builder()
        .limit(2L)
        .query(
            CustomerQuery
                .builder()
                .filter(
                    CustomerFilter
                        .builder()
                        .creationSource(
                            CustomerCreationSourceFilter
                                .builder()
                                .values(
                                    Optional.of(
                                        Arrays.asList(CustomerCreationSource.THIRD_PARTY)
                                    )
                                )
                                .rule(CustomerInclusionExclusion.INCLUDE)
                                .build()
                        )
                        .createdAt(
                            TimeRange
                                .builder()
                                .startAt("2018-01-01T00:00:00-00:00")
                                .endAt("2018-02-01T00:00:00-00:00")
                                .build()
                        )
                        .emailAddress(
                            CustomerTextFilter
                                .builder()
                                .fuzzy("example.com")
                                .build()
                        )
                        .groupIds(
                            FilterValue
                                .builder()
                                .all(
                                    Optional.of(
                                        Arrays.asList("545AXB44B4XXWMVQ4W8SBT3HHF")
                                    )
                                )
                                .build()
                        )
                        .build()
                )
                .sort(
                    CustomerSort
                        .builder()
                        .field(CustomerSortField.CREATED_AT)
                        .order(SortOrder.ASC)
                        .build()
                )
                .build()
        )
        .build()
);

⚙️ Parameters

cursor: Optional<String>

Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query.

For more information, see Pagination.

limit: Optional<Long>

The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is invalid, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 100.

For more information, see Pagination.

query: Optional<CustomerQuery>

The filtering and sorting criteria for the search request. If a query is not specified, Square returns all customer profiles ordered alphabetically by given_name and family_name.

count: Optional<Boolean>

Indicates whether to return the total count of matching customers in the count field of the response.

The default value is false.

📝 Description

Returns details for a single customer.

🔌 Usage

client.customers().get(
    GetCustomersRequest
        .builder()
        .customerId("customer_id")
        .build()
);

⚙️ Parameters

customerId: String — The ID of the customer to retrieve.

📝 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

client.customers().update(
    UpdateCustomerRequest
        .builder()
        .customerId("customer_id")
        .emailAddress("New.Amelia.Earhart@example.com")
        .note("updated customer note")
        .version(2L)
        .build()
);

⚙️ Parameters

customerId: String — The ID of the customer to update.

givenName: Optional<String>

The given name (that is, the first name) associated with the customer profile.

The maximum length for this value is 300 characters.

familyName: Optional<String>

The family name (that is, the last name) associated with the customer profile.

The maximum length for this value is 300 characters.

companyName: Optional<String>

A business name associated with the customer profile.

The maximum length for this value is 500 characters.

nickname: Optional<String>

A nickname for the customer profile.

The maximum length for this value is 100 characters.

emailAddress: Optional<String>

The email address associated with the customer profile.

The maximum length for this value is 254 characters.

address: Optional<Address>

The physical address associated with the customer profile. Only new or changed fields are required in the request.

For maximum length constraints, see Customer addresses. The first_name and last_name fields are ignored if they are present in the request.

phoneNumber: Optional<String>

The phone number associated with the customer profile. The phone number must be valid and can contain 9–16 digits, with an optional + prefix and country code. For more information, see Customer phone numbers.

referenceId: Optional<String>

An optional second ID used to associate the customer profile with an entity in another system.

The maximum length for this value is 100 characters.

note: Optional<String> — A custom note associated with the customer profile.

birthday: Optional<String>

The birthday associated with the customer profile, in YYYY-MM-DD or MM-DD format. For example, specify 1998-09-21 for September 21, 1998, or 09-21 for September 21. Birthdays are returned in YYYY-MM-DD format, where YYYY is the specified birth year or 0000 if a birth year is not specified.

version: Optional<Long>

The current version of the customer profile.

As a best practice, you should include this field to enable optimistic concurrency control. For more information, see Update a customer profile.

taxIds: Optional<CustomerTaxIds>

The tax ID associated with the customer profile. This field is available only for customers of sellers in EU countries or the United Kingdom. For more information, see Customer tax IDs.

📝 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

client.customers().delete(
    DeleteCustomersRequest
        .builder()
        .customerId("customer_id")
        .version(1000000L)
        .build()
);

⚙️ Parameters

customerId: String — The ID of the customer to delete.

version: Optional<Long>

The current version of the customer profile.

As a best practice, you should include this parameter to enable optimistic concurrency control. For more information, see Delete a customer profile.

📝 Description

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

🔌 Usage

client.devices().list(
    ListDevicesRequest
        .builder()
        .cursor("cursor")
        .sortOrder(SortOrder.DESC)
        .limit(1)
        .locationId("location_id")
        .build()
);

⚙️ Parameters

cursor: Optional<String>

A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. See Pagination for more information.

sortOrder: Optional<SortOrder>

The order in which results are listed.

• ASC - Oldest to newest.
• DESC - Newest to oldest (default).

limit: Optional<Integer> — The number of results to return in a single page.

locationId: Optional<String> — If present, only returns devices at the target location.

📝 Description

Retrieves Device with the associated device_id.

🔌 Usage

client.devices().get(
    GetDevicesRequest
        .builder()
        .deviceId("device_id")
        .build()
);

⚙️ Parameters

deviceId: String — The unique ID for the desired Device.

📝 Description

Returns a list of disputes associated with a particular account.

🔌 Usage

client.disputes().list(
    ListDisputesRequest
        .builder()
        .cursor("cursor")
        .states(DisputeState.INQUIRY_EVIDENCE_REQUIRED)
        .locationId("location_id")
        .build()
);

⚙️ Parameters

cursor: Optional<String>

A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see Pagination.

states: Optional<DisputeState> — The dispute states used to filter the result. If not specified, the endpoint returns all disputes.

locationId: Optional<String>

The ID of the location for which to return a list of disputes. If not specified, the endpoint returns disputes associated with all locations.

📝 Description

Returns details about a specific dispute.

🔌 Usage

client.disputes().get(
    GetDisputesRequest
        .builder()
        .disputeId("dispute_id")
        .build()
);

⚙️ Parameters

disputeId: String — The ID of the dispute you want more details about.

📝 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

client.disputes().accept(
    AcceptDisputesRequest
        .builder()
        .disputeId("dispute_id")
        .build()
);

⚙️ Parameters

disputeId: String — The ID of the dispute you want to accept.

📝 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

client.disputes().createEvidenceFile(
    CreateEvidenceFileDisputesRequest
        .builder()
        .disputeId("dispute_id")
        .build()
);

⚙️ Parameters

disputeId: String — The ID of the dispute for which you want to upload evidence.

📝 Description

Uploads text to use as evidence for a dispute challenge.

🔌 Usage

client.disputes().createEvidenceText(
    CreateDisputeEvidenceTextRequest
        .builder()
        .disputeId("dispute_id")
        .idempotencyKey("ed3ee3933d946f1514d505d173c82648")
        .evidenceText("1Z8888888888888888")
        .evidenceType(DisputeEvidenceType.TRACKING_NUMBER)
        .build()
);

⚙️ Parameters

disputeId: String — The ID of the dispute for which you want to upload evidence.

idempotencyKey: String — A unique key identifying the request. For more information, see Idempotency.

evidenceType: Optional<DisputeEvidenceType>

The type of evidence you are uploading. See DisputeEvidenceType for possible values

evidenceText: String — The evidence string.

📝 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

client.disputes().submitEvidence(
    SubmitEvidenceDisputesRequest
        .builder()
        .disputeId("dispute_id")
        .build()
);

⚙️ Parameters

disputeId: String — The ID of the dispute for which you want to submit evidence.

📝 Description

🔌 Usage

client.employees().list(
    ListEmployeesRequest
        .builder()
        .locationId("location_id")
        .status(EmployeeStatus.ACTIVE)
        .limit(1)
        .cursor("cursor")
        .build()
);

⚙️ Parameters

locationId: Optional<String> —

status: Optional<EmployeeStatus> — Specifies the EmployeeStatus to filter the employee by.

limit: Optional<Integer> — The number of employees to be returned on each page.

cursor: Optional<String> — The token required to retrieve the specified page of results.

📝 Description

🔌 Usage

client.employees().get(
    GetEmployeesRequest
        .builder()
        .id("id")
        .build()
);

⚙️ Parameters

id: String — UUID for the employee that was requested.

📝 Description

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

🔌 Usage

client.events().searchEvents(
    SearchEventsRequest
        .builder()
        .build()
);

⚙️ Parameters

cursor: Optional<String>

A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of events for your original query.

For more information, see Pagination.

limit: Optional<Integer>

The maximum number of events to return in a single page. The response might contain fewer events. The default value is 100, which is also the maximum allowed value.

For more information, see Pagination.

Default: 100

query: Optional<SearchEventsQuery> — The filtering and sorting criteria for the search request. To retrieve additional pages using a cursor, you must use the original query.

📝 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

client.events().disableEvents();

📝 Description

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

🔌 Usage

client.events().enableEvents();

📝 Description

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

🔌 Usage

client.events().listEventTypes(
    ListEventTypesRequest
        .builder()
        .apiVersion("api_version")
        .build()
);

⚙️ Parameters

apiVersion: Optional<String> — The API version for which to list event types. Setting this field overrides the default version used by the application.

📝 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

client.giftCards().list(
    ListGiftCardsRequest
        .builder()
        .type("type")
        .state("state")
        .limit(1)
        .cursor("cursor")
        .customerId("customer_id")
        .build()
);

⚙️ Parameters

type: Optional<String>

If a type is provided, the endpoint returns gift cards of the specified type. Otherwise, the endpoint returns gift cards of all types.

state: Optional<String>

If a state is provided, the endpoint returns the gift cards in the specified state. Otherwise, the endpoint returns the gift cards of all states.

limit: Optional<Integer>

If a limit is provided, the endpoint returns only the specified number of results per page. The maximum value is 200. The default value is 30. For more information, see Pagination.

cursor: Optional<String>

A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see Pagination.

customerId: Optional<String> — If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer.

📝 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

client.giftCards().create(
    CreateGiftCardRequest
        .builder()
        .idempotencyKey("NC9Tm69EjbjtConu")
        .locationId("81FN9BNFZTKS4")
        .giftCard(
            GiftCard
                .builder()
                .type(GiftCardType.DIGITAL)
                .build()
        )
        .build()
);

⚙️ Parameters

idempotencyKey: String

A unique identifier for this request, used to ensure idempotency. For more information, see Idempotency.

locationId: String

The ID of the location where the gift card should be registered for reporting purposes. Gift cards can be redeemed at any of the seller's locations.

giftCard: GiftCard

The gift card to create. The type field is required for this request. The gan_source and gan fields are included as follows:

To direct Square to generate a 16-digit GAN, omit gan_source and gan.

To provide a custom GAN, include gan_source and gan.

• For gan_source, specify OTHER.
• For gan, provide a custom GAN containing 8 to 20 alphanumeric characters. The GAN must be unique for the seller and cannot start with the same bank identification number (BIN) as major credit cards. Do not use GANs that are easy to guess (such as 12345678) because they greatly increase the risk of fraud. It is the responsibility of the developer to ensure the security of their custom GANs. For more information, see Custom GANs.

To register an unused, physical gift card that the seller previously ordered from Square, include gan and provide the GAN that is printed on the gift card.

📝 Description

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

🔌 Usage

client.giftCards().getFromGan(
    GetGiftCardFromGanRequest
        .builder()
        .gan("7783320001001635")
        .build()
);

⚙️ Parameters

gan: String

The gift card account number (GAN) of the gift card to retrieve. The maximum length of a GAN is 255 digits to account for third-party GANs that have been imported. Square-issued gift cards have 16-digit GANs.

📝 Description

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

🔌 Usage

client.giftCards().getFromNonce(
    GetGiftCardFromNonceRequest
        .builder()
        .nonce("cnon:7783322135245171")
        .build()
);

⚙️ Parameters

nonce: String

The payment token of the gift card to retrieve. Payment tokens are generated by the Web Payments SDK or In-App Payments SDK.

📝 Description

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

🔌 Usage

client.giftCards().linkCustomer(
    LinkCustomerToGiftCardRequest
        .builder()
        .giftCardId("gift_card_id")
        .customerId("GKY0FZ3V717AH8Q2D821PNT2ZW")
        .build()
);

⚙️ Parameters

giftCardId: String — The ID of the gift card to be linked.

customerId: String — The ID of the customer to link to the gift card.

📝 Description

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

🔌 Usage

client.giftCards().unlinkCustomer(
    UnlinkCustomerFromGiftCardRequest
        .builder()
        .giftCardId("gift_card_id")
        .customerId("GKY0FZ3V717AH8Q2D821PNT2ZW")
        .build()
);

⚙️ Parameters

giftCardId: String — The ID of the gift card to be unlinked.

customerId: String — The ID of the customer to unlink from the gift card.

📝 Description

Retrieves a gift card using the gift card ID.

🔌 Usage

client.giftCards().get(
    GetGiftCardsRequest
        .builder()
        .id("id")
        .build()
);

⚙️ Parameters

id: String — The ID of the gift card to retrieve.

📝 Description

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

🔌 Usage

client.inventory().deprecatedGetAdjustment(
    DeprecatedGetAdjustmentInventoryRequest
        .builder()
        .adjustmentId("adjustment_id")
        .build()
);

⚙️ Parameters

adjustmentId: String — ID of the InventoryAdjustment to retrieve.

📝 Description

Returns the InventoryAdjustment object with the provided adjustment_id.

🔌 Usage

client.inventory().getAdjustment(
    GetAdjustmentInventoryRequest
        .builder()
        .adjustmentId("adjustment_id")
        .build()
);

⚙️ Parameters

adjustmentId: String — ID of the InventoryAdjustment to retrieve.

📝 Description

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

🔌 Usage

client.inventory().deprecatedBatchChange(
    BatchChangeInventoryRequest
        .builder()
        .idempotencyKey("8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe")
        .changes(
            Optional.of(
                Arrays.asList(
                    InventoryChange
                        .builder()
                        .type(InventoryChangeType.PHYSICAL_COUNT)
                        .physicalCount(
                            InventoryPhysicalCount
                                .builder()
                                .referenceId("1536bfbf-efed-48bf-b17d-a197141b2a92")
                                .catalogObjectId("W62UWFY35CWMYGVWK6TWJDNI")
                                .state(InventoryState.IN_STOCK)
                                .locationId("C6W5YS5QM06F5")
                                .quantity("53")
                                .teamMemberId("LRK57NSQ5X7PUD05")
                                .occurredAt("2016-11-16T22:25:24.878Z")
                                .build()
                        )
                        .build()
                )
            )
        )
        .ignoreUnchangedCounts(true)
        .build()
);

⚙️ Parameters

request: BatchChangeInventoryRequest

📝 Description

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

🔌 Usage

client.inventory().deprecatedBatchGetChanges(
    BatchRetrieveInventoryChangesRequest
        .builder()
        .catalogObjectIds(
            Optional.of(
                Arrays.asList("W62UWFY35CWMYGVWK6TWJDNI")
            )
        )
        .locationIds(
            Optional.of(
                Arrays.asList("C6W5YS5QM06F5")
            )
        )
        .types(
            Optional.of(
                Arrays.asList(InventoryChangeType.PHYSICAL_COUNT)
            )
        )
        .states(
            Optional.of(
                Arrays.asList(InventoryState.IN_STOCK)
            )
        )
        .updatedAfter("2016-11-01T00:00:00.000Z")
        .updatedBefore("2016-12-01T00:00:00.000Z")
        .build()
);

⚙️ Parameters

request: BatchRetrieveInventoryChangesRequest

📝 Description

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

🔌 Usage

client.inventory().deprecatedBatchGetCounts(
    BatchGetInventoryCountsRequest
        .builder()
        .catalogObjectIds(
            Optional.of(
                Arrays.asList("W62UWFY35CWMYGVWK6TWJDNI")
            )
        )
        .locationIds(
            Optional.of(
                Arrays.asList("59TNP9SA8VGDA")
            )
        )
        .updatedAfter("2016-11-16T00:00:00.000Z")
        .build()
);

⚙️ Parameters

request: BatchGetInventoryCountsRequest

📝 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

client.inventory().batchCreateChanges(
    BatchChangeInventoryRequest
        .builder()
        .idempotencyKey("8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe")
        .changes(
            Optional.of(
                Arrays.asList(
                    InventoryChange
                        .builder()
                        .type(InventoryChangeType.PHYSICAL_COUNT)
                        .physicalCount(
                            InventoryPhysicalCount
                                .builder()
                                .referenceId("1536bfbf-efed-48bf-b17d-a197141b2a92")
                                .catalogObjectId("W62UWFY35CWMYGVWK6TWJDNI")
                                .state(InventoryState.IN_STOCK)
                                .locationId("C6W5YS5QM06F5")
                                .quantity("53")
                                .teamMemberId("LRK57NSQ5X7PUD05")
                                .occurredAt("2016-11-16T22:25:24.878Z")
                                .build()
                        )
                        .build()
                )
            )
        )
        .ignoreUnchangedCounts(true)
        .build()
);

⚙️ Parameters

request: BatchChangeInventoryRequest

📝 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

client.inventory().batchGetChanges(
    BatchRetrieveInventoryChangesRequest
        .builder()
        .catalogObjectIds(
            Optional.of(
                Arrays.asList("W62UWFY35CWMYGVWK6TWJDNI")
            )
        )
        .locationIds(
            Optional.of(
                Arrays.asList("C6W5YS5QM06F5")
            )
        )
        .types(
            Optional.of(
                Arrays.asList(InventoryChangeType.PHYSICAL_COUNT)
            )
        )
        .states(
            Optional.of(
                Arrays.asList(InventoryState.IN_STOCK)
            )
        )
        .updatedAfter("2016-11-01T00:00:00.000Z")
        .updatedBefore("2016-12-01T00:00:00.000Z")
        .build()
);

⚙️ Parameters

request: BatchRetrieveInventoryChangesRequest

📝 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

client.inventory().batchGetCounts(
    BatchGetInventoryCountsRequest
        .builder()
        .catalogObjectIds(
            Optional.of(
                Arrays.asList("W62UWFY35CWMYGVWK6TWJDNI")
            )
        )
        .locationIds(
            Optional.of(
                Arrays.asList("59TNP9SA8VGDA")
            )
        )
        .updatedAfter("2016-11-16T00:00:00.000Z")
        .build()
);

⚙️ Parameters

request: BatchGetInventoryCountsRequest

📝 Description

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

🔌 Usage

client.inventory().deprecatedGetPhysicalCount(
    DeprecatedGetPhysicalCountInventoryRequest
        .builder()
        .physicalCountId("physical_count_id")
        .build()
);

⚙️ Parameters

physicalCountId: String

ID of the InventoryPhysicalCount to retrieve.

📝 Description

Returns the InventoryPhysicalCount object with the provided physical_count_id.

🔌 Usage

client.inventory().getPhysicalCount(
    GetPhysicalCountInventoryRequest
        .builder()
        .physicalCountId("physical_count_id")
        .build()
);

⚙️ Parameters

physicalCountId: String

ID of the InventoryPhysicalCount to retrieve.

📝 Description

Returns the InventoryTransfer object with the provided transfer_id.

🔌 Usage

client.inventory().getTransfer(
    GetTransferInventoryRequest
        .builder()
        .transferId("transfer_id")
        .build()
);

⚙️ Parameters

transferId: String — ID of the InventoryTransfer to retrieve.

📝 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

client.inventory().get(
    GetInventoryRequest
        .builder()
        .catalogObjectId("catalog_object_id")
        .locationIds("location_ids")
        .cursor("cursor")
        .build()
);

⚙️ Parameters

catalogObjectId: String — ID of the CatalogObject to retrieve.

locationIds: Optional<String>

The Location IDs to look up as a comma-separated list. An empty list queries all locations.

cursor: Optional<String>

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query.

See the Pagination guide for more information.

📝 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

client.inventory().changes(
    ChangesInventoryRequest
        .builder()
        .catalogObjectId("catalog_object_id")
        .locationIds("location_ids")
        .cursor("cursor")
        .build()
);

⚙️ Parameters

catalogObjectId: String — ID of the CatalogObject to retrieve.

locationIds: Optional<String>

The Location IDs to look up as a comma-separated list. An empty list queries all locations.

cursor: Optional<String>

A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query.

See the Pagination guide for more information.

📝 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

client.invoices().list(
    ListInvoicesRequest
        .builder()
        .locationId("location_id")
        .cursor("cursor")
        .limit(1)
        .build()
);

⚙️ Parameters

locationId: String — The ID of the location for which to list invoices.

cursor: Optional<String>

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: Optional<Integer>

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

📝 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

client.invoices().create(
    CreateInvoiceRequest
        .builder()
        .invoice(
            Invoice
                .builder()
                .locationId("ES0RJRZYEC39A")
                .orderId("CAISENgvlJ6jLWAzERDzjyHVybY")
                .primaryRecipient(
                    InvoiceRecipient
                        .builder()
                        .customerId("JDKYHBWT1D4F8MFH63DBMEN8Y4")
                        .build()
                )
                .paymentRequests(
                    Optional.of(
                        Arrays.asList(
                            InvoicePaymentRequest
                                .builder()
                                .requestType(InvoiceRequestType.BALANCE)
                                .dueDate("2030-01-24")
                                .tippingEnabled(true)
                                .automaticPaymentSource(InvoiceAutomaticPaymentSource.NONE)
                                .reminders(
                                    Optional.of(
                                        Arrays.asList(
                                            InvoicePaymentReminder
                                                .builder()
                                                .relativeScheduledDays(-1)
                                                .message("Your invoice is due tomorrow")
                                                .build()
                                        )
                                    )
                                )
                                .build()
                        )
                    )
                )
                .deliveryMethod(InvoiceDeliveryMethod.EMAIL)
                .invoiceNumber("inv-100")
                .title("Event Planning Services")
                .description("We appreciate your business!")
                .scheduledAt("2030-01-13T10:00:00Z")
                .acceptedPaymentMethods(
                    InvoiceAcceptedPaymentMethods
                        .builder()
                        .card(true)
                        .squareGiftCard(false)
                        .bankAccount(false)
                        .buyNowPayLater(false)
                        .cashAppPay(false)
                        .build()
                )
                .customFields(
                    Optional.of(
                        Arrays.asList(
                            InvoiceCustomField
                                .builder()
                                .label("Event Reference Number")
                                .value("Ref. #1234")
                                .placement(InvoiceCustomFieldPlacement.ABOVE_LINE_ITEMS)
                                .build(),
                            InvoiceCustomField
                                .builder()
                                .label("Terms of Service")
                                .value("The terms of service are...")
                                .placement(InvoiceCustomFieldPlacement.BELOW_LINE_ITEMS)
                                .build()
                        )
                    )
                )
                .saleOrServiceDate("2030-01-24")
                .storePaymentMethodEnabled(false)
                .build()
        )
        .idempotencyKey("ce3748f9-5fc1-4762-aa12-aae5e843f1f4")
        .build()
);