Skip to content

Files

Latest commit

634f3c2 · May 6, 2025

History

History
29934 lines (21111 loc) · 503 KB

reference.md

File metadata and controls

29934 lines (21111 loc) · 503 KB

Reference

Mobile

client.mobile.authorization_code(...)

📝 Description

Note: This endpoint is used by the deprecated Reader SDK. Developers should update their integration to use the Mobile Payments SDK, which includes its own authorization methods.

Generates code to authorize a mobile application to connect to a Square card reader.

Authorization codes are one-time-use codes and expire 60 minutes after being issued.

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

Authorization: Bearer ACCESS_TOKEN

Replace ACCESS_TOKEN with a valid production authorization credential.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.mobile.authorization_code(
    location_id="YOUR_LOCATION_ID",
)

⚙️ Parameters

location_id: typing.Optional[str] — The Square location ID that the authorization code should be tied to.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

OAuth

client.o_auth.revoke_token(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.o_auth.revoke_token(
    client_id="CLIENT_ID",
    access_token="ACCESS_TOKEN",
)

⚙️ Parameters

client_id: typing.Optional[str]

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

access_token: typing.Optional[str]

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.

merchant_id: typing.Optional[str]

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

revoke_only_access_token: typing.Optional[bool]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.o_auth.obtain_token(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.o_auth.obtain_token(
    client_id="sq0idp-uaPHILoPzWZk3tlJqlML0g",
    client_secret="sq0csp-30a-4C_tVOnTh14Piza2BfTPBXyLafLPWSzY1qAjeBfM",
    code="sq0cgb-l0SBqxs4uwxErTVyYOdemg",
    grant_type="authorization_code",
)

⚙️ Parameters

client_id: str

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.

grant_type: str

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.

client_secret: typing.Optional[str]

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: typing.Optional[str]

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.

redirect_uri: typing.Optional[str]

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.

refresh_token: typing.Optional[str]

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.

migration_token: typing.Optional[str]

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: typing.Optional[typing.Sequence[str]]

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.

short_lived: typing.Optional[bool]

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.

code_verifier: typing.Optional[str]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.o_auth.retrieve_token_status()

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.o_auth.retrieve_token_status()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.o_auth.authorize()

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.o_auth.authorize()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

V1Transactions

client.v1transactions.v1list_orders(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.v1transactions.v1list_orders(
    location_id="location_id",
)

⚙️ Parameters

location_id: str — The ID of the location to list online store orders for.

order: typing.Optional[SortOrder] — The order in which payments are listed in the response.

limit: typing.Optional[int] — The maximum number of payments to return in a single response. This value cannot exceed 200.

batch_token: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.v1transactions.v1retrieve_order(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.v1transactions.v1retrieve_order(
    location_id="location_id",
    order_id="order_id",
)

⚙️ Parameters

location_id: str — The ID of the order's associated location.

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.v1transactions.v1update_order(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.v1transactions.v1update_order(
    location_id="location_id",
    order_id="order_id",
    action="COMPLETE",
)

⚙️ Parameters

location_id: str — The ID of the order's associated location.

order_id: str — 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

shipped_tracking_number: typing.Optional[str] — The tracking number of the shipment associated with the order. Only valid if action is COMPLETE.

completed_note: typing.Optional[str] — A merchant-specified note about the completion of the order. Only valid if action is COMPLETE.

refunded_note: typing.Optional[str] — A merchant-specified note about the refunding of the order. Only valid if action is REFUND.

canceled_note: typing.Optional[str] — A merchant-specified note about the canceling of the order. Only valid if action is CANCEL.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

ApplePay

client.apple_pay.register_domain(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.apple_pay.register_domain(
    domain_name="example.com",
)

⚙️ Parameters

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

BankAccounts

client.bank_accounts.list(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.bank_accounts.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

cursor: typing.Optional[str]

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: typing.Optional[int]

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.

location_id: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bank_accounts.get_by_v1id(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bank_accounts.get_by_v1id(
    v1bank_account_id="v1_bank_account_id",
)

⚙️ Parameters

v1bank_account_id: str

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bank_accounts.get(...)

📝 Description

Returns details of a BankAccount linked to a Square account.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bank_accounts.get(
    bank_account_id="bank_account_id",
)

⚙️ Parameters

bank_account_id: str — Square-issued ID of the desired BankAccount.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Bookings

client.bookings.list(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.bookings.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

limit: typing.Optional[int] — The maximum number of results per page to return in a paged response.

cursor: typing.Optional[str] — 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.

customer_id: typing.Optional[str] — The customer for whom to retrieve bookings. If this is not set, bookings for all customers are retrieved.

team_member_id: typing.Optional[str] — The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved.

location_id: typing.Optional[str] — The location for which to retrieve bookings. If this is not set, all locations' bookings are retrieved.

start_at_min: typing.Optional[str] — The RFC 3339 timestamp specifying the earliest of the start time. If this is not set, the current time is used.

start_at_max: typing.Optional[str] — 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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.create(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.create(
    booking={},
)

⚙️ Parameters

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

idempotency_key: typing.Optional[str] — A unique key to make this request an idempotent operation.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.search_availability(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.search_availability(
    query={"filter": {"start_at_range": {}}},
)

⚙️ Parameters

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.bulk_retrieve_bookings(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.bulk_retrieve_bookings(
    booking_ids=["booking_ids"],
)

⚙️ Parameters

booking_ids: typing.Sequence[str] — A non-empty list of Booking IDs specifying bookings to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.get_business_profile()

📝 Description

Retrieves a seller's booking profile.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.get_business_profile()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.retrieve_location_booking_profile(...)

📝 Description

Retrieves a seller's location booking profile.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.retrieve_location_booking_profile(
    location_id="location_id",
)

⚙️ Parameters

location_id: str — The ID of the location to retrieve the booking profile.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.bulk_retrieve_team_member_booking_profiles(...)

📝 Description

Retrieves one or more team members' booking profiles.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.bulk_retrieve_team_member_booking_profiles(
    team_member_ids=["team_member_ids"],
)

⚙️ Parameters

team_member_ids: typing.Sequence[str] — A non-empty list of IDs of team members whose booking profiles you want to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.get(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.get(
    booking_id="booking_id",
)

⚙️ Parameters

booking_id: str — The ID of the Booking object representing the to-be-retrieved booking.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.update(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.update(
    booking_id="booking_id",
    booking={},
)

⚙️ Parameters

booking_id: str — The ID of the Booking object representing the to-be-updated booking.

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

idempotency_key: typing.Optional[str] — A unique key to make this request an idempotent operation.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.cancel(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.cancel(
    booking_id="booking_id",
)

⚙️ Parameters

booking_id: str — The ID of the Booking object representing the to-be-cancelled booking.

idempotency_key: typing.Optional[str] — A unique key to make this request an idempotent operation.

booking_version: typing.Optional[int] — The revision number for the booking used for optimistic concurrency.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Cards

client.cards.list(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.cards.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

cursor: typing.Optional[str]

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.

customer_id: typing.Optional[str]

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

include_disabled: typing.Optional[bool]

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

reference_id: typing.Optional[str] — Limit results to cards associated with the reference_id supplied.

sort_order: typing.Optional[SortOrder]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.cards.create(...)

📝 Description

Adds a card on file to an existing merchant.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.cards.create(
    idempotency_key="4935a656-a929-4792-b97c-8848be85c27c",
    source_id="cnon:uIbfJXhXETSP197M3GB",
    card={
        "cardholder_name": "Amelia Earhart",
        "billing_address": {
            "address_line1": "500 Electric Ave",
            "address_line2": "Suite 600",
            "locality": "New York",
            "administrative_district_level1": "NY",
            "postal_code": "10003",
            "country": "US",
        },
        "customer_id": "VDKXEEKPJN48QDG3BGGFAK05P8",
        "reference_id": "user-id-1",
    },
)

⚙️ Parameters

idempotency_key: str

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.

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

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

verification_token: typing.Optional[str]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.cards.get(...)

📝 Description

Retrieves details for a specific Card.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.cards.get(
    card_id="card_id",
)

⚙️ Parameters

card_id: str — Unique ID for the desired Card.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.cards.disable(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.cards.disable(
    card_id="card_id",
)

⚙️ Parameters

card_id: str — Unique ID for the desired Card.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Catalog

client.catalog.batch_delete(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.catalog.batch_delete(
    object_ids=["W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK"],
)

⚙️ Parameters

object_ids: typing.Sequence[str]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.catalog.batch_get(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.catalog.batch_get(
    object_ids=["W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK"],
    include_related_objects=True,
)

⚙️ Parameters

object_ids: typing.Sequence[str] — The IDs of the CatalogObjects to be retrieved.

include_related_objects: typing.Optional[bool]

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

catalog_version: typing.Optional[int]

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.

include_deleted_objects: typing.Optional[bool] — Indicates whether to include (true) or not (false) in the response deleted objects, namely, those with the is_deleted attribute set to true.

include_category_path_to_root: typing.Optional[bool]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.catalog.batch_upsert(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.catalog.batch_upsert(
    idempotency_key="789ff020-f723-43a9-b4b5-43b5dc1fa3dc",
    batches=[
        {
            "objects": [
                {
                    "type": "IMAGE",
                    "id": "#Tea",
                    "present_at_all_locations": True,
                },
                {
                    "type": "IMAGE",
                    "id": "#Coffee",
                    "present_at_all_locations": True,
                },
                {
                    "type": "ITEM",
                    "id": "#Beverages",
                    "present_at_all_locations": True,
                },
                {
                    "type": "TAX",
                    "id": "#SalesTax",
                    "present_at_all_locations": True,
                    "tax_data": {
                        "name": "Sales Tax",
                        "calculation_phase": "TAX_SUBTOTAL_PHASE",
                        "inclusion_type": "ADDITIVE",
                        "percentage": "5.0",
                        "applies_to_custom_amounts": True,
                        "enabled": True,
                    },
                },
            ]
        }
    ],
)

⚙️ Parameters

idempotency_key: str

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: typing.Sequence[CatalogObjectBatchParams]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.catalog.info()

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.catalog.info()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.catalog.list(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.catalog.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

cursor: typing.Optional[str]

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: typing.Optional[str]

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.

catalog_version: typing.Optional[int]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.catalog.search(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.catalog.search(
    object_types=["ITEM"],
    query={
        "prefix_query": {"attribute_name": "name", "attribute_prefix": "tea"}
    },
    limit=100,
)

⚙️ Parameters

cursor: typing.Optional[str]

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

object_types: typing.Optional[typing.Sequence[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.

include_deleted_objects: typing.Optional[bool] — 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.

include_related_objects: typing.Optional[bool]

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

begin_time: typing.Optional[str]

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: typing.Optional[CatalogQueryParams] — A query to be used to filter or sort the results. If no query is specified, the entire catalog will be returned.

limit: typing.Optional[int]

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.

include_category_path_to_root: typing.Optional[bool] — 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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.catalog.search_items(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.catalog.search_items(
    text_filter="red",
    category_ids=["WINE_CATEGORY_ID"],
    stock_levels=["OUT", "LOW"],
    enabled_location_ids=["ATL_LOCATION_ID"],
    limit=100,
    sort_order="ASC",
    product_types=["REGULAR"],
    custom_attribute_filters=[
        {
            "custom_attribute_definition_id": "VEGAN_DEFINITION_ID",
            "bool_filter": True,
        },
        {
            "custom_attribute_definition_id": "BRAND_DEFINITION_ID",
            "string_filter": "Dark Horse",
        },
        {"key": "VINTAGE", "number_filter": {"min": "min", "max": "max"}},
        {"custom_attribute_definition_id": "VARIETAL_DEFINITION_ID"},
    ],
)

⚙️ Parameters

text_filter: typing.Optional[str]

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.

category_ids: typing.Optional[typing.Sequence[str]] — The category id query expression to return items containing the specified category IDs.

stock_levels: typing.Optional[typing.Sequence[SearchCatalogItemsRequestStockLevel]]

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

enabled_location_ids: typing.Optional[typing.Sequence[str]] — The enabled-location query expression to return items and item variations having specified enabled locations.

cursor: typing.Optional[str] — The pagination token, returned in the previous response, used to fetch the next batch of pending results.

limit: typing.Optional[int] — The maximum number of results to return per page. The default value is 100.

sort_order: typing.Optional[SortOrder]

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

product_types: typing.Optional[typing.Sequence[CatalogItemProductType]] — The product types query expression to return items or item variations having the specified product types.

custom_attribute_filters: typing.Optional[typing.Sequence[CustomAttributeFilterParams]]

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.

archived_state: typing.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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.catalog.update_item_modifier_lists(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.catalog.update_item_modifier_lists(
    item_ids=["H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6"],
    modifier_lists_to_enable=[
        "H42BRLUJ5KTZTTMPVSLFAACQ",
        "2JXOBJIHCWBQ4NZ3RIXQGJA6",
    ],
    modifier_lists_to_disable=["7WRC16CJZDVLSNDQ35PP6YAD"],
)

⚙️ Parameters

item_ids: typing.Sequence[str] — The IDs of the catalog items associated with the CatalogModifierList objects being updated.

modifier_lists_to_enable: typing.Optional[typing.Sequence[str]]

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.

modifier_lists_to_disable: typing.Optional[typing.Sequence[str]]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.catalog.update_item_taxes(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.catalog.update_item_taxes(
    item_ids=["H42BRLUJ5KTZTTMPVSLFAACQ", "2JXOBJIHCWBQ4NZ3RIXQGJA6"],
    taxes_to_enable=["4WRCNHCJZDVLSNDQ35PP6YAD"],
    taxes_to_disable=["AQCEGCEBBQONINDOHRGZISEX"],
)

⚙️ Parameters

item_ids: typing.Sequence[str]

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

taxes_to_enable: typing.Optional[typing.Sequence[str]]

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

taxes_to_disable: typing.Optional[typing.Sequence[str]]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Customers

client.customers.list(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.customers.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

cursor: typing.Optional[str]

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: typing.Optional[int]

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.

sort_field: typing.Optional[CustomerSortField]

Indicates how customers should be sorted.

The default value is DEFAULT.

sort_order: typing.Optional[SortOrder]

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

The default value is ASC.

count: typing.Optional[bool]

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

The default value is false.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.create(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.create(
    given_name="Amelia",
    family_name="Earhart",
    email_address="Amelia.Earhart@example.com",
    address={
        "address_line1": "500 Electric Ave",
        "address_line2": "Suite 600",
        "locality": "New York",
        "administrative_district_level1": "NY",
        "postal_code": "10003",
        "country": "US",
    },
    phone_number="+1-212-555-4240",
    reference_id="YOUR_REFERENCE_ID",
    note="a customer",
)

⚙️ Parameters

idempotency_key: typing.Optional[str]

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

given_name: typing.Optional[str]

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

The maximum length for this value is 300 characters.

family_name: typing.Optional[str]

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

The maximum length for this value is 300 characters.

company_name: typing.Optional[str]

A business name associated with the customer profile.

The maximum length for this value is 500 characters.

nickname: typing.Optional[str]

A nickname for the customer profile.

The maximum length for this value is 100 characters.

email_address: typing.Optional[str]

The email address associated with the customer profile.

The maximum length for this value is 254 characters.

address: typing.Optional[AddressParams]

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.

phone_number: typing.Optional[str]

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.

reference_id: typing.Optional[str]

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: typing.Optional[str] — A custom note associated with the customer profile.

birthday: typing.Optional[str]

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.

tax_ids: typing.Optional[CustomerTaxIdsParams]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.batch_create(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.batch_create(
    customers={
        "8bb76c4f-e35d-4c5b-90de-1194cd9179f0": {
            "given_name": "Amelia",
            "family_name": "Earhart",
            "email_address": "Amelia.Earhart@example.com",
            "address": {
                "address_line1": "500 Electric Ave",
                "address_line2": "Suite 600",
                "locality": "New York",
                "administrative_district_level1": "NY",
                "postal_code": "10003",
                "country": "US",
            },
            "phone_number": "+1-212-555-4240",
            "reference_id": "YOUR_REFERENCE_ID",
            "note": "a customer",
        },
        "d1689f23-b25d-4932-b2f0-aed00f5e2029": {
            "given_name": "Marie",
            "family_name": "Curie",
            "email_address": "Marie.Curie@example.com",
            "address": {
                "address_line1": "500 Electric Ave",
                "address_line2": "Suite 601",
                "locality": "New York",
                "administrative_district_level1": "NY",
                "postal_code": "10003",
                "country": "US",
            },
            "phone_number": "+1-212-444-4240",
            "reference_id": "YOUR_REFERENCE_ID",
            "note": "another customer",
        },
    },
)

⚙️ Parameters

customers: typing.Dict[str, BulkCreateCustomerDataParams]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.bulk_delete_customers(...)

📝 Description

Deletes multiple customer profiles.

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.bulk_delete_customers(
    customer_ids=[
        "8DDA5NZVBZFGAX0V3HPF81HHE0",
        "N18CPRVXR5214XPBBA6BZQWF3C",
        "2GYD7WNXF7BJZW1PMGNXZ3Y8M8",
    ],
)

⚙️ Parameters

customer_ids: typing.Sequence[str] — The IDs of the customer profiles to delete.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.bulk_retrieve_customers(...)

📝 Description

Retrieves multiple customer profiles.

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.bulk_retrieve_customers(
    customer_ids=[
        "8DDA5NZVBZFGAX0V3HPF81HHE0",
        "N18CPRVXR5214XPBBA6BZQWF3C",
        "2GYD7WNXF7BJZW1PMGNXZ3Y8M8",
    ],
)

⚙️ Parameters

customer_ids: typing.Sequence[str] — The IDs of the customer profiles to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.bulk_update_customers(...)

📝 Description

Updates multiple customer profiles.

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.bulk_update_customers(
    customers={
        "8DDA5NZVBZFGAX0V3HPF81HHE0": {
            "email_address": "New.Amelia.Earhart@example.com",
            "note": "updated customer note",
            "version": 2,
        },
        "N18CPRVXR5214XPBBA6BZQWF3C": {
            "given_name": "Marie",
            "family_name": "Curie",
            "version": 0,
        },
    },
)

⚙️ Parameters

customers: typing.Dict[str, BulkUpdateCustomerDataParams]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.search(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.search(
    limit=2,
    query={
        "filter": {
            "creation_source": {"values": ["THIRD_PARTY"], "rule": "INCLUDE"},
            "created_at": {
                "start_at": "2018-01-01T00:00:00-00:00",
                "end_at": "2018-02-01T00:00:00-00:00",
            },
            "email_address": {"fuzzy": "example.com"},
            "group_ids": {"all_": ["545AXB44B4XXWMVQ4W8SBT3HHF"]},
        },
        "sort": {"field": "CREATED_AT", "order": "ASC"},
    },
)

⚙️ Parameters

cursor: typing.Optional[str]

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: typing.Optional[int]

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: typing.Optional[CustomerQueryParams]

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: typing.Optional[bool]

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

The default value is false.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.get(...)

📝 Description

Returns details for a single customer.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.get(
    customer_id="customer_id",
)

⚙️ Parameters

customer_id: str — The ID of the customer to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.update(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.update(
    customer_id="customer_id",
    email_address="New.Amelia.Earhart@example.com",
    note="updated customer note",
    version=2,
)

⚙️ Parameters

customer_id: str — The ID of the customer to update.

given_name: typing.Optional[str]

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

The maximum length for this value is 300 characters.

family_name: typing.Optional[str]

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

The maximum length for this value is 300 characters.

company_name: typing.Optional[str]

A business name associated with the customer profile.

The maximum length for this value is 500 characters.

nickname: typing.Optional[str]

A nickname for the customer profile.

The maximum length for this value is 100 characters.

email_address: typing.Optional[str]

The email address associated with the customer profile.

The maximum length for this value is 254 characters.

address: typing.Optional[AddressParams]

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.

phone_number: typing.Optional[str]

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.

reference_id: typing.Optional[str]

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: typing.Optional[str] — A custom note associated with the customer profile.

birthday: typing.Optional[str]

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: typing.Optional[int]

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.

tax_ids: typing.Optional[CustomerTaxIdsParams]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.delete(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.delete(
    customer_id="customer_id",
)

⚙️ Parameters

customer_id: str — The ID of the customer to delete.

version: typing.Optional[int]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Devices

client.devices.list(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.devices.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

cursor: typing.Optional[str]

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.

sort_order: typing.Optional[SortOrder]

The order in which results are listed.

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

limit: typing.Optional[int] — The number of results to return in a single page.

location_id: typing.Optional[str] — If present, only returns devices at the target location.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.devices.get(...)

📝 Description

Retrieves Device with the associated device_id.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.devices.get(
    device_id="device_id",
)

⚙️ Parameters

device_id: str — The unique ID for the desired Device.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Disputes

client.disputes.list(...)

📝 Description

Returns a list of disputes associated with a particular account.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.disputes.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

cursor: typing.Optional[str]

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: typing.Optional[DisputeState] — The dispute states used to filter the result. If not specified, the endpoint returns all disputes.

location_id: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.disputes.get(...)

📝 Description

Returns details about a specific dispute.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.disputes.get(
    dispute_id="dispute_id",
)

⚙️ Parameters

dispute_id: str — The ID of the dispute you want more details about.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.disputes.accept(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.disputes.accept(
    dispute_id="dispute_id",
)

⚙️ Parameters

dispute_id: str — The ID of the dispute you want to accept.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.disputes.create_evidence_file(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.disputes.create_evidence_file(
    dispute_id="dispute_id",
)

⚙️ Parameters

dispute_id: str — The ID of the dispute for which you want to upload evidence.

request: typing.Optional[CreateDisputeEvidenceFileRequestParams]

image_file: `from future import annotations

typing.Optional[core.File]` — See core.File for more documentation

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.disputes.create_evidence_text(...)

📝 Description

Uploads text to use as evidence for a dispute challenge.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.disputes.create_evidence_text(
    dispute_id="dispute_id",
    idempotency_key="ed3ee3933d946f1514d505d173c82648",
    evidence_type="TRACKING_NUMBER",
    evidence_text="1Z8888888888888888",
)

⚙️ Parameters

dispute_id: str — The ID of the dispute for which you want to upload evidence.

idempotency_key: str — A unique key identifying the request. For more information, see Idempotency.

evidence_text: str — The evidence string.

evidence_type: typing.Optional[DisputeEvidenceType]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.disputes.submit_evidence(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.disputes.submit_evidence(
    dispute_id="dispute_id",
)

⚙️ Parameters

dispute_id: str — The ID of the dispute for which you want to submit evidence.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Employees

client.employees.list(...)

📝 Description

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.employees.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

location_id: typing.Optional[str]

status: typing.Optional[EmployeeStatus] — Specifies the EmployeeStatus to filter the employee by.

limit: typing.Optional[int] — The number of employees to be returned on each page.

cursor: typing.Optional[str] — The token required to retrieve the specified page of results.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.employees.get(...)

📝 Description

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.employees.get(
    id="id",
)

⚙️ Parameters

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Events

client.events.search_events(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.events.search_events()

⚙️ Parameters

cursor: typing.Optional[str]

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: typing.Optional[int]

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: typing.Optional[SearchEventsQueryParams] — The filtering and sorting criteria for the search request. To retrieve additional pages using a cursor, you must use the original query.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.events.disable_events()

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.events.disable_events()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.events.enable_events()

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.events.enable_events()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.events.list_event_types(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.events.list_event_types()

⚙️ Parameters

api_version: typing.Optional[str] — The API version for which to list event types. Setting this field overrides the default version used by the application.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

GiftCards

client.gift_cards.list(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.gift_cards.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

type: typing.Optional[str]

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

state: typing.Optional[str]

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: typing.Optional[int]

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: typing.Optional[str]

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.

customer_id: typing.Optional[str] — If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.gift_cards.create(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.gift_cards.create(
    idempotency_key="NC9Tm69EjbjtConu",
    location_id="81FN9BNFZTKS4",
    gift_card={"type": "DIGITAL"},
)

⚙️ Parameters

idempotency_key: str

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

location_id: str

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.

gift_card: GiftCardParams

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.gift_cards.get_from_gan(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.gift_cards.get_from_gan(
    gan="7783320001001635",
)

⚙️ Parameters

gan: str

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.gift_cards.get_from_nonce(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.gift_cards.get_from_nonce(
    nonce="cnon:7783322135245171",
)

⚙️ Parameters

nonce: str

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.gift_cards.link_customer(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.gift_cards.link_customer(
    gift_card_id="gift_card_id",
    customer_id="GKY0FZ3V717AH8Q2D821PNT2ZW",
)

⚙️ Parameters

gift_card_id: str — The ID of the gift card to be linked.

customer_id: str — The ID of the customer to link to the gift card.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.gift_cards.unlink_customer(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.gift_cards.unlink_customer(
    gift_card_id="gift_card_id",
    customer_id="GKY0FZ3V717AH8Q2D821PNT2ZW",
)

⚙️ Parameters

gift_card_id: str — The ID of the gift card to be unlinked.

customer_id: str — The ID of the customer to unlink from the gift card.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.gift_cards.get(...)

📝 Description

Retrieves a gift card using the gift card ID.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.gift_cards.get(
    id="id",
)

⚙️ Parameters

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Inventory

client.inventory.deprecated_get_adjustment(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.inventory.deprecated_get_adjustment(
    adjustment_id="adjustment_id",
)

⚙️ Parameters

adjustment_id: str — ID of the InventoryAdjustment to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.inventory.get_adjustment(...)

📝 Description

Returns the InventoryAdjustment object with the provided adjustment_id.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.inventory.get_adjustment(
    adjustment_id="adjustment_id",
)

⚙️ Parameters

adjustment_id: str — ID of the InventoryAdjustment to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.inventory.deprecated_batch_change(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.inventory.deprecated_batch_change(
    idempotency_key="8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe",
    changes=[
        {
            "type": "PHYSICAL_COUNT",
            "physical_count": {
                "reference_id": "1536bfbf-efed-48bf-b17d-a197141b2a92",
                "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
                "state": "IN_STOCK",
                "location_id": "C6W5YS5QM06F5",
                "quantity": "53",
                "team_member_id": "LRK57NSQ5X7PUD05",
                "occurred_at": "2016-11-16T22:25:24.878Z",
            },
        }
    ],
    ignore_unchanged_counts=True,
)

⚙️ Parameters

idempotency_key: str

A client-supplied, universally unique identifier (UUID) for the request.

See Idempotency in the API Development 101 section for more information.

changes: typing.Optional[typing.Sequence[InventoryChangeParams]]

The set of physical counts and inventory adjustments to be made. Changes are applied based on the client-supplied timestamp and may be sent out of order.

ignore_unchanged_counts: typing.Optional[bool]

Indicates whether the current physical count should be ignored if the quantity is unchanged since the last physical count. Default: true.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.inventory.deprecated_batch_get_changes(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.inventory.deprecated_batch_get_changes(
    catalog_object_ids=["W62UWFY35CWMYGVWK6TWJDNI"],
    location_ids=["C6W5YS5QM06F5"],
    types=["PHYSICAL_COUNT"],
    states=["IN_STOCK"],
    updated_after="2016-11-01T00:00:00.000Z",
    updated_before="2016-12-01T00:00:00.000Z",
)

⚙️ Parameters

catalog_object_ids: typing.Optional[typing.Sequence[str]]

The filter to return results by CatalogObject ID. The filter is only applicable when set. The default value is null.

location_ids: typing.Optional[typing.Sequence[str]]

The filter to return results by Location ID. The filter is only applicable when set. The default value is null.

types: typing.Optional[typing.Sequence[InventoryChangeType]]

The filter to return results by InventoryChangeType values other than TRANSFER. The default value is [PHYSICAL_COUNT, ADJUSTMENT].

states: typing.Optional[typing.Sequence[InventoryState]]

The filter to return ADJUSTMENT query results by InventoryState. This filter is only applied when set. The default value is null.

updated_after: typing.Optional[str]

The filter to return results with their calculated_at value after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (1970-01-01T00:00:00Z).

updated_before: typing.Optional[str]

The filter to return results with their created_at or calculated_at value strictly before the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (1970-01-01T00:00:00Z).

cursor: typing.Optional[str]

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.

limit: typing.Optional[int] — The number of records to return.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.inventory.deprecated_batch_get_counts(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.inventory.deprecated_batch_get_counts(
    catalog_object_ids=["W62UWFY35CWMYGVWK6TWJDNI"],
    location_ids=["59TNP9SA8VGDA"],
    updated_after="2016-11-16T00:00:00.000Z",
)

⚙️ Parameters

catalog_object_ids: typing.Optional[typing.Sequence[str]]

The filter to return results by CatalogObject ID. The filter is applicable only when set. The default is null.

location_ids: typing.Optional[typing.Sequence[str]]

The filter to return results by Location ID. This filter is applicable only when set. The default is null.

updated_after: typing.Optional[str]

The filter to return results with their calculated_at value after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (1970-01-01T00:00:00Z).

cursor: typing.Optional[str]

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.

states: typing.Optional[typing.Sequence[InventoryState]]

The filter to return results by InventoryState. The filter is only applicable when set. Ignored are untracked states of NONE, SOLD, and UNLINKED_RETURN. The default is null.

limit: typing.Optional[int] — The number of records to return.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.inventory.batch_create_changes(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.inventory.batch_create_changes(
    idempotency_key="8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe",
    changes=[
        {
            "type": "PHYSICAL_COUNT",
            "physical_count": {
                "reference_id": "1536bfbf-efed-48bf-b17d-a197141b2a92",
                "catalog_object_id": "W62UWFY35CWMYGVWK6TWJDNI",
                "state": "IN_STOCK",
                "location_id": "C6W5YS5QM06F5",
                "quantity": "53",
                "team_member_id": "LRK57NSQ5X7PUD05",
                "occurred_at": "2016-11-16T22:25:24.878Z",
            },
        }
    ],
    ignore_unchanged_counts=True,
)

⚙️ Parameters

idempotency_key: str

A client-supplied, universally unique identifier (UUID) for the request.

See Idempotency in the API Development 101 section for more information.

changes: typing.Optional[typing.Sequence[InventoryChangeParams]]

The set of physical counts and inventory adjustments to be made. Changes are applied based on the client-supplied timestamp and may be sent out of order.

ignore_unchanged_counts: typing.Optional[bool]

Indicates whether the current physical count should be ignored if the quantity is unchanged since the last physical count. Default: true.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.inventory.batch_get_changes(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.inventory.batch_get_changes(
    catalog_object_ids=["W62UWFY35CWMYGVWK6TWJDNI"],
    location_ids=["C6W5YS5QM06F5"],
    types=["PHYSICAL_COUNT"],
    states=["IN_STOCK"],
    updated_after="2016-11-01T00:00:00.000Z",
    updated_before="2016-12-01T00:00:00.000Z",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

catalog_object_ids: typing.Optional[typing.Sequence[str]]

The filter to return results by CatalogObject ID. The filter is only applicable when set. The default value is null.

location_ids: typing.Optional[typing.Sequence[str]]

The filter to return results by Location ID. The filter is only applicable when set. The default value is null.

types: typing.Optional[typing.Sequence[InventoryChangeType]]

The filter to return results by InventoryChangeType values other than TRANSFER. The default value is [PHYSICAL_COUNT, ADJUSTMENT].

states: typing.Optional[typing.Sequence[InventoryState]]

The filter to return ADJUSTMENT query results by InventoryState. This filter is only applied when set. The default value is null.

updated_after: typing.Optional[str]

The filter to return results with their calculated_at value after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (1970-01-01T00:00:00Z).

updated_before: typing.Optional[str]

The filter to return results with their created_at or calculated_at value strictly before the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (1970-01-01T00:00:00Z).

cursor: typing.Optional[str]

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.

limit: typing.Optional[int] — The number of records to return.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.inventory.batch_get_counts(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.inventory.batch_get_counts(
    catalog_object_ids=["W62UWFY35CWMYGVWK6TWJDNI"],
    location_ids=["59TNP9SA8VGDA"],
    updated_after="2016-11-16T00:00:00.000Z",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

catalog_object_ids: typing.Optional[typing.Sequence[str]]

The filter to return results by CatalogObject ID. The filter is applicable only when set. The default is null.

location_ids: typing.Optional[typing.Sequence[str]]

The filter to return results by Location ID. This filter is applicable only when set. The default is null.

updated_after: typing.Optional[str]

The filter to return results with their calculated_at value after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (1970-01-01T00:00:00Z).

cursor: typing.Optional[str]

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.

states: typing.Optional[typing.Sequence[InventoryState]]

The filter to return results by InventoryState. The filter is only applicable when set. Ignored are untracked states of NONE, SOLD, and UNLINKED_RETURN. The default is null.

limit: typing.Optional[int] — The number of records to return.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.inventory.deprecated_get_physical_count(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.inventory.deprecated_get_physical_count(
    physical_count_id="physical_count_id",
)

⚙️ Parameters

physical_count_id: str

ID of the InventoryPhysicalCount to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.inventory.get_physical_count(...)

📝 Description

Returns the InventoryPhysicalCount object with the provided physical_count_id.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.inventory.get_physical_count(
    physical_count_id="physical_count_id",
)

⚙️ Parameters

physical_count_id: str

ID of the InventoryPhysicalCount to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.inventory.get_transfer(...)

📝 Description

Returns the InventoryTransfer object with the provided transfer_id.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.inventory.get_transfer(
    transfer_id="transfer_id",
)

⚙️ Parameters

transfer_id: str — ID of the InventoryTransfer to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.inventory.get(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.inventory.get(
    catalog_object_id="catalog_object_id",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

catalog_object_id: str — ID of the CatalogObject to retrieve.

location_ids: typing.Optional[str]

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

cursor: typing.Optional[str]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.inventory.changes(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.inventory.changes(
    catalog_object_id="catalog_object_id",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

catalog_object_id: str — ID of the CatalogObject to retrieve.

location_ids: typing.Optional[str]

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

cursor: typing.Optional[str]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Invoices

client.invoices.list(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.invoices.list(
    location_id="location_id",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

location_id: str — The ID of the location for which to list invoices.

cursor: typing.Optional[str]

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: typing.Optional[int]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.invoices.create(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.invoices.create(
    invoice={
        "location_id": "ES0RJRZYEC39A",
        "order_id": "CAISENgvlJ6jLWAzERDzjyHVybY",
        "primary_recipient": {"customer_id": "JDKYHBWT1D4F8MFH63DBMEN8Y4"},
        "payment_requests": [
            {
                "request_type": "BALANCE",
                "due_date": "2030-01-24",
                "tipping_enabled": True,
                "automatic_payment_source": "NONE",
                "reminders": [
                    {
                        "relative_scheduled_days": -1,
                        "message": "Your invoice is due tomorrow",
                    }
                ],
            }
        ],
        "delivery_method": "EMAIL",
        "invoice_number": "inv-100",
        "title": "Event Planning Services",
        "description": "We appreciate your business!",
        "scheduled_at": "2030-01-13T10:00:00Z",
        "accepted_payment_methods": {
            "card": True,
            "square_gift_card": False,
            "bank_account": False,
            "buy_now_pay_later": False,
            "cash_app_pay": False,
        },
        "custom_fields": [
            {
                "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",
            },
        ],
        "sale_or_service_date": "2030-01-24",
        "store_payment_method_enabled": False,
    },
    idempotency_key="ce3748f9-5fc1-4762-aa12-aae5e843f1f4",
)

⚙️ Parameters

invoice: InvoiceParams — The invoice to create.

idempotency_key: typing.Optional[str]

A unique string that identifies the CreateInvoice request. If you do not provide idempotency_key (or provide an empty string as the value), the endpoint treats each request as independent.

For more information, see Idempotency.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.invoices.search(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.invoices.search(
    query={
        "filter": {
            "location_ids": ["ES0RJRZYEC39A"],
            "customer_ids": ["JDKYHBWT1D4F8MFH63DBMEN8Y4"],
        },
        "sort": {"field": "INVOICE_SORT_DATE", "order": "DESC"},
    },
    limit=100,
)

⚙️ Parameters

query: InvoiceQueryParams — Describes the query criteria for searching invoices.

limit: typing.Optional[int]

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

cursor: typing.Optional[str]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.invoices.get(...)

📝 Description

Retrieves an invoice by invoice ID.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.invoices.get(
    invoice_id="invoice_id",
)

⚙️ Parameters

invoice_id: str — The ID of the invoice to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.invoices.update(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.invoices.update(
    invoice_id="invoice_id",
    invoice={
        "version": 1,
        "payment_requests": [
            {
                "uid": "2da7964f-f3d2-4f43-81e8-5aa220bf3355",
                "tipping_enabled": False,
            }
        ],
    },
    idempotency_key="4ee82288-0910-499e-ab4c-5d0071dad1be",
)

⚙️ Parameters

invoice_id: str — The ID of the invoice to update.

invoice: InvoiceParams

The invoice fields to add, change, or clear. Fields can be cleared using null values or the remove field (for individual payment requests or reminders). The current invoice version is also required. For more information, including requirements, limitations, and more examples, see Update an Invoice.

idempotency_key: typing.Optional[str]

A unique string that identifies the UpdateInvoice request. If you do not provide idempotency_key (or provide an empty string as the value), the endpoint treats each request as independent.

For more information, see Idempotency.

fields_to_clear: typing.Optional[typing.Sequence[str]]

The list of fields to clear. Although this field is currently supported, we recommend using null values or the remove field when possible. For examples, see Update an Invoice.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.invoices.delete(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.invoices.delete(
    invoice_id="invoice_id",
)

⚙️ Parameters

invoice_id: str — The ID of the invoice to delete.

version: typing.Optional[int]

The version of the invoice to delete. If you do not know the version, you can call GetInvoice or ListInvoices.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.invoices.create_invoice_attachment(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.invoices.create_invoice_attachment(
    invoice_id="invoice_id",
)

⚙️ Parameters

invoice_id: str — The ID of the invoice to attach the file to.

request: typing.Optional[CreateInvoiceAttachmentRequestDataParams]

image_file: `from future import annotations

typing.Optional[core.File]` — See core.File for more documentation

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.invoices.delete_invoice_attachment(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.invoices.delete_invoice_attachment(
    invoice_id="invoice_id",
    attachment_id="attachment_id",
)

⚙️ Parameters

invoice_id: str — The ID of the invoice to delete the attachment from.

attachment_id: str — The ID of the attachment to delete.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.invoices.cancel(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.invoices.cancel(
    invoice_id="invoice_id",
    version=0,
)

⚙️ Parameters

invoice_id: str — The ID of the invoice to cancel.

version: int

The version of the invoice to cancel. If you do not know the version, you can call GetInvoice or ListInvoices.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.invoices.publish(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.invoices.publish(
    invoice_id="invoice_id",
    version=1,
    idempotency_key="32da42d0-1997-41b0-826b-f09464fc2c2e",
)

⚙️ Parameters

invoice_id: str — The ID of the invoice to publish.

version: int

The version of the invoice to publish. This must match the current version of the invoice; otherwise, the request is rejected.

idempotency_key: typing.Optional[str]

A unique string that identifies the PublishInvoice request. If you do not provide idempotency_key (or provide an empty string as the value), the endpoint treats each request as independent.

For more information, see Idempotency.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Locations

client.locations.list()

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.list()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.create(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.create(
    location={
        "name": "Midtown",
        "address": {
            "address_line1": "1234 Peachtree St. NE",
            "locality": "Atlanta",
            "administrative_district_level1": "GA",
            "postal_code": "30309",
        },
        "description": "Midtown Atlanta store",
    },
)

⚙️ Parameters

location: typing.Optional[LocationParams]

The initial values of the location being created. The name field is required and must be unique within a seller account. All other fields are optional, but any information you care about for the location should be included. The remaining fields are automatically added based on the data from the main location.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.get(...)

📝 Description

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.get(
    location_id="location_id",
)

⚙️ Parameters

location_id: str

The ID of the location to retrieve. Specify the string "main" to return the main location.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.update(...)

📝 Description

Updates a location.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.update(
    location_id="location_id",
    location={
        "business_hours": {
            "periods": [
                {
                    "day_of_week": "FRI",
                    "start_local_time": "07:00",
                    "end_local_time": "18:00",
                },
                {
                    "day_of_week": "SAT",
                    "start_local_time": "07:00",
                    "end_local_time": "18:00",
                },
                {
                    "day_of_week": "SUN",
                    "start_local_time": "09:00",
                    "end_local_time": "15:00",
                },
            ]
        },
        "description": "Midtown Atlanta store - Open weekends",
    },
)

⚙️ Parameters

location_id: str — The ID of the location to update.

location: typing.Optional[LocationParams] — The Location object with only the fields to update.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.checkouts(...)

📝 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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.checkouts(
    location_id="location_id",
    idempotency_key="86ae1696-b1e3-4328-af6d-f1e04d947ad6",
    order={
        "order": {
            "location_id": "location_id",
            "reference_id": "reference_id",
            "customer_id": "customer_id",
            "line_items": [
                {
                    "name": "Printed T Shirt",
                    "quantity": "2",
                    "applied_taxes": [
                        {"tax_uid": "38ze1696-z1e3-5628-af6d-f1e04d947fg3"}
                    ],
                    "applied_discounts": [
                        {"discount_uid": "56ae1696-z1e3-9328-af6d-f1e04d947gd4"}
                    ],
                    "base_price_money": {"amount": 1500, "currency": "USD"},
                },
                {
                    "name": "Slim Jeans",
                    "quantity": "1",
                    "base_price_money": {"amount": 2500, "currency": "USD"},
                },
                {
                    "name": "Woven Sweater",
                    "quantity": "3",
                    "base_price_money": {"amount": 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",
                    "amount_money": {"amount": 100, "currency": "USD"},
                    "scope": "LINE_ITEM",
                }
            ],
        },
        "idempotency_key": "12ae1696-z1e3-4328-af6d-f1e04d947gd4",
    },
    ask_for_shipping_address=True,
    merchant_support_email="merchant+support@website.com",
    pre_populate_buyer_email="example@email.com",
    pre_populate_shipping_address={
        "address_line1": "1455 Market St.",
        "address_line2": "Suite 600",
        "locality": "San Francisco",
        "administrative_district_level1": "CA",
        "postal_code": "94103",
        "country": "US",
        "first_name": "Jane",
        "last_name": "Doe",
    },
    redirect_url="https://merchant.website.com/order-confirm",
    additional_recipients=[
        {
            "location_id": "057P5VYJ4A5X1",
            "description": "Application fees",
            "amount_money": {"amount": 60, "currency": "USD"},
        }
    ],
)

⚙️ Parameters

location_id: str — The ID of the business location to associate the checkout with.

idempotency_key: str

A unique string that identifies this checkout among others you have created. It can be any valid string but must be unique for every order sent to Square Checkout for a given location ID.

The idempotency key is used to avoid processing the same order more than once. If you are unsure whether a particular checkout was created successfully, you can attempt it again with the same idempotency key and all the same other parameters without worrying about creating duplicates.

You should use a random number/string generator native to the language you are working in to generate strings for your idempotency keys.

For more information, see Idempotency.

order: CreateOrderRequestParams — The order including line items to be checked out.

ask_for_shipping_address: typing.Optional[bool]

If true, Square Checkout collects shipping information on your behalf and stores that information with the transaction information in the Square Seller Dashboard.

Default: false.

merchant_support_email: typing.Optional[str]

The email address to display on the Square Checkout confirmation page and confirmation email that the buyer can use to contact the seller.

If this value is not set, the confirmation page and email display the primary email address associated with the seller's Square account.

Default: none; only exists if explicitly set.

pre_populate_buyer_email: typing.Optional[str]

If provided, the buyer's email is prepopulated on the checkout page as an editable text field.

Default: none; only exists if explicitly set.

pre_populate_shipping_address: typing.Optional[AddressParams]

If provided, the buyer's shipping information is prepopulated on the checkout page as editable text fields.

Default: none; only exists if explicitly set.

redirect_url: typing.Optional[str]

The URL to redirect to after the checkout is completed with checkoutId, transactionId, and referenceId appended as URL parameters. For example, if the provided redirect URL is http://www.example.com/order-complete, a successful transaction redirects the customer to:

http://www.example.com/order-complete?checkoutId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx

If you do not provide a redirect URL, Square Checkout displays an order confirmation page on your behalf; however, it is strongly recommended that you provide a redirect URL so you can verify the transaction results and finalize the order through your existing/normal confirmation workflow.

Default: none; only exists if explicitly set.

additional_recipients: typing.Optional[typing.Sequence[ChargeRequestAdditionalRecipientParams]]

The basic primitive of a multi-party transaction. The value is optional. The transaction facilitated by you can be split from here.

If you provide this value, the amount_money value in your additional_recipients field cannot be more than 90% of the total_money calculated by Square for your order. The location_id must be a valid seller location where the checkout is occurring.

This field requires PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission.

This field is currently not supported in the Square Sandbox.

note: typing.Optional[str]

An optional note to associate with the checkout object.

This value cannot exceed 60 characters.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Loyalty

client.loyalty.search_events(...)

📝 Description

Searches for loyalty events.

A Square loyalty program maintains a ledger of events that occur during the lifetime of a buyer's loyalty account. Each change in the point balance (for example, points earned, points redeemed, and points expired) is recorded in the ledger. Using this endpoint, you can search the ledger for events.

Search results are sorted by created_at in descending order.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.search_events(
    query={
        "filter": {
            "order_filter": {"order_id": "PyATxhYLfsMqpVkcKJITPydgEYfZY"}
        }
    },
    limit=30,
)

⚙️ Parameters

query: typing.Optional[LoyaltyEventQueryParams]

A set of one or more predefined query filters to apply when searching for loyalty events. The endpoint performs a logical AND to evaluate multiple filters and performs a logical OR on arrays
that specifies multiple field values.

limit: typing.Optional[int]

The maximum number of results to include in the response. The last page might contain fewer events. The default is 30 events.

cursor: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Merchants

client.merchants.list(...)

📝 Description

Provides details about the merchant associated with a given access token.

The access token used to connect your application to a Square seller is associated with a single merchant. That means that ListMerchants returns a list with a single Merchant object. You can specify your personal access token to get your own merchant information or specify an OAuth token to get the information for the merchant that granted your application access.

If you know the merchant ID, you can also use the RetrieveMerchant endpoint to retrieve the merchant information.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.merchants.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

cursor: typing.Optional[int] — The cursor generated by the previous response.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.merchants.get(...)

📝 Description

Retrieves the Merchant object for the given merchant_id.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.merchants.get(
    merchant_id="merchant_id",
)

⚙️ Parameters

merchant_id: str

The ID of the merchant to retrieve. If the string "me" is supplied as the ID, then retrieve the merchant that is currently accessible to this call.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Checkout

client.checkout.retrieve_location_settings(...)

📝 Description

Retrieves the location-level settings for a Square-hosted checkout page.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.checkout.retrieve_location_settings(
    location_id="location_id",
)

⚙️ Parameters

location_id: str — The ID of the location for which to retrieve settings.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.checkout.update_location_settings(...)

📝 Description

Updates the location-level settings for a Square-hosted checkout page.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.checkout.update_location_settings(
    location_id="location_id",
    location_settings={},
)

⚙️ Parameters

location_id: str — The ID of the location for which to retrieve settings.

location_settings: CheckoutLocationSettingsParams — Describe your updates using the location_settings object. Make sure it contains only the fields that have changed.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.checkout.retrieve_merchant_settings()

📝 Description

Retrieves the merchant-level settings for a Square-hosted checkout page.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.checkout.retrieve_merchant_settings()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.checkout.update_merchant_settings(...)

📝 Description

Updates the merchant-level settings for a Square-hosted checkout page.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.checkout.update_merchant_settings(
    merchant_settings={},
)

⚙️ Parameters

merchant_settings: CheckoutMerchantSettingsParams — Describe your updates using the merchant_settings object. Make sure it contains only the fields that have changed.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Orders

client.orders.create(...)

📝 Description

Creates a new order that can include information about products for purchase and settings to apply to the purchase.

To pay for a created order, see Pay for Orders.

You can modify open orders using the UpdateOrder endpoint.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.create(
    order={
        "location_id": "057P5VYJ4A5X1",
        "reference_id": "my-order-001",
        "line_items": [
            {
                "name": "New York Strip Steak",
                "quantity": "1",
                "base_price_money": {"amount": 1599, "currency": "USD"},
            },
            {
                "quantity": "2",
                "catalog_object_id": "BEMYCSMIJL46OCDV4KYIKXIB",
                "modifiers": [
                    {"catalog_object_id": "CHQX7Y4KY6N5KINJKZCFURPZ"}
                ],
                "applied_discounts": [{"discount_uid": "one-dollar-off"}],
            },
        ],
        "taxes": [
            {
                "uid": "state-sales-tax",
                "name": "State Sales Tax",
                "percentage": "9",
                "scope": "ORDER",
            }
        ],
        "discounts": [
            {
                "uid": "labor-day-sale",
                "name": "Labor Day Sale",
                "percentage": "5",
                "scope": "ORDER",
            },
            {
                "uid": "membership-discount",
                "catalog_object_id": "DB7L55ZH2BGWI4H23ULIWOQ7",
                "scope": "ORDER",
            },
            {
                "uid": "one-dollar-off",
                "name": "Sale - $1.00 off",
                "amount_money": {"amount": 100, "currency": "USD"},
                "scope": "LINE_ITEM",
            },
        ],
    },
    idempotency_key="8193148c-9586-11e6-99f9-28cfe92138cf",
)

⚙️ Parameters

order: typing.Optional[OrderParams]

The order to create. If this field is set, the only other top-level field that can be set is the idempotency_key.

idempotency_key: typing.Optional[str]

A value you specify that uniquely identifies this order among orders you have created.

If you are unsure whether a particular order was created successfully, you can try it again with the same idempotency key without worrying about creating duplicate orders.

For more information, see Idempotency.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.batch_get(...)

📝 Description

Retrieves a set of orders by their IDs.

If a given order ID does not exist, the ID is ignored instead of generating an error.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.batch_get(
    location_id="057P5VYJ4A5X1",
    order_ids=["CAISEM82RcpmcFBM0TfOyiHV3es", "CAISENgvlJ6jLWAzERDzjyHVybY"],
)

⚙️ Parameters

order_ids: typing.Sequence[str] — The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request.

location_id: typing.Optional[str]

The ID of the location for these orders. This field is optional: omit it to retrieve orders within the scope of the current authorization's merchant ID.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.calculate(...)

📝 Description

Enables applications to preview order pricing without creating an order.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.calculate(
    order={
        "location_id": "D7AVYMEAPJ3A3",
        "line_items": [
            {
                "name": "Item 1",
                "quantity": "1",
                "base_price_money": {"amount": 500, "currency": "USD"},
            },
            {
                "name": "Item 2",
                "quantity": "2",
                "base_price_money": {"amount": 300, "currency": "USD"},
            },
        ],
        "discounts": [
            {"name": "50% Off", "percentage": "50", "scope": "ORDER"}
        ],
    },
)

⚙️ Parameters

order: OrderParams — The order to be calculated. Expects the entire order, not a sparse update.

proposed_rewards: typing.Optional[typing.Sequence[OrderRewardParams]]

Identifies one or more loyalty reward tiers to apply during the order calculation. The discounts defined by the reward tiers are added to the order only to preview the effect of applying the specified rewards. The rewards do not correspond to actual redemptions; that is, no rewards are created. Therefore, the reward ids are random strings used only to reference the reward tier.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.clone(...)

📝 Description

Creates a new order, in the DRAFT state, by duplicating an existing order. The newly created order has only the core fields (such as line items, taxes, and discounts) copied from the original order.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.clone(
    order_id="ZAISEM52YcpmcWAzERDOyiWS123",
    version=3,
    idempotency_key="UNIQUE_STRING",
)

⚙️ Parameters

order_id: str — The ID of the order to clone.

version: typing.Optional[int]

An optional order version for concurrency protection.

If a version is provided, it must match the latest stored version of the order to clone. If a version is not provided, the API clones the latest version.

idempotency_key: typing.Optional[str]

A value you specify that uniquely identifies this clone request.

If you are unsure whether a particular order was cloned successfully, you can reattempt the call with the same idempotency key without worrying about creating duplicate cloned orders. The originally cloned order is returned.

For more information, see Idempotency.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.search(...)

📝 Description

Search all orders for one or more locations. Orders include all sales, returns, and exchanges regardless of how or when they entered the Square ecosystem (such as Point of Sale, Invoices, and Connect APIs).

SearchOrders requests need to specify which locations to search and define a SearchOrdersQuery object that controls how to sort or filter the results. Your SearchOrdersQuery can:

Set filter criteria. Set the sort order. Determine whether to return results as complete Order objects or as OrderEntry objects.

Note that details for orders processed with Square Point of Sale while in offline mode might not be transmitted to Square for up to 72 hours. Offline orders have a created_at value that reflects the time the order was created, not the time it was subsequently transmitted to Square.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.search(
    location_ids=["057P5VYJ4A5X1", "18YC4JDH91E1H"],
    query={
        "filter": {
            "state_filter": {"states": ["COMPLETED"]},
            "date_time_filter": {
                "closed_at": {
                    "start_at": "2018-03-03T20:00:00+00:00",
                    "end_at": "2019-03-04T21:54:45+00:00",
                }
            },
        },
        "sort": {"sort_field": "CLOSED_AT", "sort_order": "DESC"},
    },
    limit=3,
    return_entries=True,
)

⚙️ Parameters

location_ids: typing.Optional[typing.Sequence[str]]

The location IDs for the orders to query. All locations must belong to the same merchant.

Max: 10 location IDs.

cursor: typing.Optional[str]

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.

query: typing.Optional[SearchOrdersQueryParams]

Query conditions used to filter or sort the results. Note that when retrieving additional pages using a cursor, you must use the original query.

limit: typing.Optional[int]

The maximum number of results to be returned in a single page.

Default: 500 Max: 1000

return_entries: typing.Optional[bool]

A Boolean that controls the format of the search results. If true, SearchOrders returns OrderEntry objects. If false, SearchOrders returns complete order objects.

Default: false.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.get(...)

📝 Description

Retrieves an Order by ID.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.get(
    order_id="order_id",
)

⚙️ Parameters

order_id: str — The ID of the order to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.update(...)

📝 Description

Updates an open order by adding, replacing, or deleting fields. Orders with a COMPLETED or CANCELED state cannot be updated.

An UpdateOrder request requires the following:

  • The order_id in the endpoint path, identifying the order to update.
  • The latest version of the order to update.
  • The sparse order containing only the fields to update and the version to which the update is being applied.
  • If deleting fields, the dot notation paths identifying the fields to clear.

To pay for an order, see Pay for Orders.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.update(
    order_id="order_id",
    order={
        "location_id": "location_id",
        "line_items": [
            {
                "uid": "cookie_uid",
                "name": "COOKIE",
                "quantity": "2",
                "base_price_money": {"amount": 200, "currency": "USD"},
            }
        ],
        "version": 1,
    },
    fields_to_clear=["discounts"],
    idempotency_key="UNIQUE_STRING",
)

⚙️ Parameters

order_id: str — The ID of the order to update.

order: typing.Optional[OrderParams]

The sparse order containing only the fields to update and the version to which the update is being applied.

fields_to_clear: typing.Optional[typing.Sequence[str]]

The dot notation paths fields to clear. For example, line_items[uid].note. For more information, see Deleting fields.

idempotency_key: typing.Optional[str]

A value you specify that uniquely identifies this update request.

If you are unsure whether a particular update was applied to an order successfully, you can reattempt it with the same idempotency key without worrying about creating duplicate updates to the order. The latest order version is returned.

For more information, see Idempotency.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.pay(...)

📝 Description

Pay for an order using one or more approved payments or settle an order with a total of 0.

The total of the payment_ids listed in the request must be equal to the order total. Orders with a total amount of 0 can be marked as paid by specifying an empty array of payment_ids in the request.

To be used with PayOrder, a payment must:

  • Reference the order by specifying the order_id when creating the payment. Any approved payments that reference the same order_id not specified in the payment_ids is canceled.
  • Be approved with delayed capture. Using a delayed capture payment with PayOrder completes the approved payment.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.pay(
    order_id="order_id",
    idempotency_key="c043a359-7ad9-4136-82a9-c3f1d66dcbff",
    payment_ids=["EnZdNAlWCmfh6Mt5FMNST1o7taB", "0LRiVlbXVwe8ozu4KbZxd12mvaB"],
)

⚙️ Parameters

order_id: str — The ID of the order being paid.

idempotency_key: str

A value you specify that uniquely identifies this request among requests you have sent. If you are unsure whether a particular payment request was completed successfully, you can reattempt it with the same idempotency key without worrying about duplicate payments.

For more information, see Idempotency.

order_version: typing.Optional[int] — The version of the order being paid. If not supplied, the latest version will be paid.

payment_ids: typing.Optional[typing.Sequence[str]]

The IDs of the payments to collect. The payment total must match the order total.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Payments

client.payments.list(...)

📝 Description

Retrieves a list of payments taken by the account making the request.

Results are eventually consistent, and new payments or changes to payments might take several seconds to appear.

The maximum results per page is 100.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.payments.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

begin_time: typing.Optional[str]

Indicates the start of the time range to retrieve payments for, in RFC 3339 format.
The range is determined using the created_at field for each Payment. Inclusive. Default: The current time minus one year.

end_time: typing.Optional[str]

Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the created_at field for each Payment.

Default: The current time.

sort_order: typing.Optional[str]

The order in which results are listed by ListPaymentsRequest.sort_field:

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

cursor: typing.Optional[str]

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.

location_id: typing.Optional[str]

Limit results to the location supplied. By default, results are returned for the default (main) location associated with the seller.

total: typing.Optional[int] — The exact amount in the total_money for a payment.

last4: typing.Optional[str] — The last four digits of a payment card.

card_brand: typing.Optional[str] — The brand of the payment card (for example, VISA).

limit: typing.Optional[int]

The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page.

The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead.

Default: 100

is_offline_payment: typing.Optional[bool] — Whether the payment was taken offline or not.

offline_begin_time: typing.Optional[str]

Indicates the start of the time range for which to retrieve offline payments, in RFC 3339 format for timestamps. The range is determined using the offline_payment_details.client_created_at field for each Payment. If set, payments without a value set in offline_payment_details.client_created_at will not be returned.

Default: The current time.

offline_end_time: typing.Optional[str]

Indicates the end of the time range for which to retrieve offline payments, in RFC 3339 format for timestamps. The range is determined using the offline_payment_details.client_created_at field for each Payment. If set, payments without a value set in offline_payment_details.client_created_at will not be returned.

Default: The current time.

updated_at_begin_time: typing.Optional[str]

Indicates the start of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the updated_at field for each Payment.

updated_at_end_time: typing.Optional[str]

Indicates the end of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the updated_at field for each Payment.

sort_field: typing.Optional[ListPaymentsRequestSortField] — The field used to sort results by. The default is CREATED_AT.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.payments.create(...)

📝 Description

Creates a payment using the provided source. You can use this endpoint to charge a card (credit/debit card or
Square gift card) or record a payment that the seller received outside of Square (cash payment from a buyer or a payment that an external entity processed on behalf of the seller).

The endpoint creates a Payment object and returns it in the response.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.payments.create(
    source_id="ccof:GaJGNaZa8x4OgDJn4GB",
    idempotency_key="7b0f3ec5-086a-4871-8f13-3c81b3875218",
    amount_money={"amount": 1000, "currency": "USD"},
    app_fee_money={"amount": 10, "currency": "USD"},
    autocomplete=True,
    customer_id="W92WH6P11H4Z77CTET0RNTGFW8",
    location_id="L88917AVBK2S5",
    reference_id="123456",
    note="Brief description",
)

⚙️ Parameters

source_id: str

The ID for the source of funds for this payment. This could be a payment token generated by the Web Payments SDK for any of its supported methods, including cards, bank transfers, Afterpay or Cash App Pay. If recording a payment that the seller received outside of Square, specify either "CASH" or "EXTERNAL". For more information, see Take Payments.

idempotency_key: str

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

Note: The number of allowed characters might be less than the stated maximum, if multi-byte characters are used.

For more information, see Idempotency.

amount_money: typing.Optional[MoneyParams]

The amount of money to accept for this payment, not including tip_money.

The amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see Working with Monetary Amounts.

The currency code must match the currency associated with the business that is accepting the payment.

tip_money: typing.Optional[MoneyParams]

The amount designated as a tip, in addition to amount_money.

The amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see Working with Monetary Amounts.

The currency code must match the currency associated with the business that is accepting the payment.

app_fee_money: typing.Optional[MoneyParams]

The amount of money that the developer is taking as a fee for facilitating the payment on behalf of the seller.

The amount cannot be more than 90% of the total amount of the payment.

The amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see Working with Monetary Amounts.

The fee currency code must match the currency associated with the seller that is accepting the payment. The application must be from a developer account in the same country and using the same currency code as the seller.

For more information about the application fee scenario, see Take Payments and Collect Fees.

To set this field, PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission is required. For more information, see Permissions.

delay_duration: typing.Optional[str]

The duration of time after the payment's creation when Square automatically either completes or cancels the payment depending on the delay_action field value. For more information, see Time threshold.

This parameter should be specified as a time duration, in RFC 3339 format.

Note: This feature is only supported for card payments. This parameter can only be set for a delayed capture payment (autocomplete=false).

Default:

  • Card-present payments: "PT36H" (36 hours) from the creation time.
  • Card-not-present payments: "P7D" (7 days) from the creation time.

delay_action: typing.Optional[str]

The action to be applied to the payment when the delay_duration has elapsed. The action must be CANCEL or COMPLETE. For more information, see Time Threshold.

Default: CANCEL

autocomplete: typing.Optional[bool]

If set to true, this payment will be completed when possible. If set to false, this payment is held in an approved state until either explicitly completed (captured) or canceled (voided). For more information, see Delayed capture.

Default: true

order_id: typing.Optional[str] — Associates a previously created order with this payment.

customer_id: typing.Optional[str]

The Customer ID of the customer associated with the payment.

This is required if the source_id refers to a card on file created using the Cards API.

location_id: typing.Optional[str]

The location ID to associate with the payment. If not specified, the main location is used.

team_member_id: typing.Optional[str]

An optional TeamMember ID to associate with this payment.

reference_id: typing.Optional[str]

A user-defined ID to associate with the payment.

You can use this field to associate the payment to an entity in an external system (for example, you might specify an order ID that is generated by a third-party shopping cart).

verification_token: typing.Optional[str]

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.

For more information, see SCA Overview.

accept_partial_authorization: typing.Optional[bool]

If set to true and charging a Square Gift Card, a payment might be returned with amount_money equal to less than what was requested. For example, a request for $20 when charging a Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose to prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card payment. This field cannot be true when autocomplete = true.

For more information, see Partial amount with Square Gift Cards.

Default: false

buyer_email_address: typing.Optional[str] — The buyer's email address.

buyer_phone_number: typing.Optional[str]

The buyer's phone number. Must follow the following format:

  1. A leading + symbol (followed by a country code)
  2. The phone number can contain spaces and the special characters ( , ) , - , and .. Alphabetical characters aren't allowed.
  3. The phone number must contain between 9 and 16 digits.

billing_address: typing.Optional[AddressParams] — The buyer's billing address.

shipping_address: typing.Optional[AddressParams] — The buyer's shipping address.

note: typing.Optional[str] — An optional note to be entered by the developer when creating a payment.

statement_description_identifier: typing.Optional[str]

Optional additional payment information to include on the customer's card statement as part of the statement description. This can be, for example, an invoice number, ticket number, or short description that uniquely identifies the purchase.

Note that the statement_description_identifier might get truncated on the statement description to fit the required information including the Square identifier (SQ *) and name of the seller taking the payment.

cash_details: typing.Optional[CashPaymentDetailsParams] — Additional details required when recording a cash payment (source_id is CASH).

external_details: typing.Optional[ExternalPaymentDetailsParams] — Additional details required when recording an external payment (source_id is EXTERNAL).

customer_details: typing.Optional[CustomerDetailsParams] — Details about the customer making the payment.

offline_payment_details: typing.Optional[OfflinePaymentDetailsParams]

An optional field for specifying the offline payment details. This is intended for internal 1st-party callers only.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.payments.cancel_by_idempotency_key(...)

📝 Description

Cancels (voids) a payment identified by the idempotency key that is specified in the request.

Use this method when the status of a CreatePayment request is unknown (for example, after you send a CreatePayment request, a network error occurs and you do not get a response). In this case, you can direct Square to cancel the payment using this endpoint. In the request, you provide the same idempotency key that you provided in your CreatePayment request that you want to cancel. After canceling the payment, you can submit your CreatePayment request again.

Note that if no payment with the specified idempotency key is found, no action is taken and the endpoint returns successfully.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.payments.cancel_by_idempotency_key(
    idempotency_key="a7e36d40-d24b-11e8-b568-0800200c9a66",
)

⚙️ Parameters

idempotency_key: str — The idempotency_key identifying the payment to be canceled.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.payments.get(...)

📝 Description

Retrieves details for a specific payment.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.payments.get(
    payment_id="payment_id",
)

⚙️ Parameters

payment_id: str — A unique ID for the desired payment.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.payments.update(...)

📝 Description

Updates a payment with the APPROVED status. You can update the amount_money and tip_money using this endpoint.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.payments.update(
    payment_id="payment_id",
    payment={
        "amount_money": {"amount": 1000, "currency": "USD"},
        "tip_money": {"amount": 100, "currency": "USD"},
        "version_token": "ODhwVQ35xwlzRuoZEwKXucfu7583sPTzK48c5zoGd0g6o",
    },
    idempotency_key="956f8b13-e4ec-45d6-85e8-d1d95ef0c5de",
)

⚙️ Parameters

payment_id: str — The ID of the payment to update.

idempotency_key: str

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

For more information, see Idempotency.

payment: typing.Optional[PaymentParams] — The updated Payment object.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.payments.cancel(...)

📝 Description

Cancels (voids) a payment. You can use this endpoint to cancel a payment with the APPROVED status.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.payments.cancel(
    payment_id="payment_id",
)

⚙️ Parameters

payment_id: str — The ID of the payment to cancel.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.payments.complete(...)

📝 Description

Completes (captures) a payment. By default, payments are set to complete immediately after they are created.

You can use this endpoint to complete a payment with the APPROVED status.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.payments.complete(
    payment_id="payment_id",
)

⚙️ Parameters

payment_id: str — The unique ID identifying the payment to be completed.

version_token: typing.Optional[str]

Used for optimistic concurrency. This opaque token identifies the current Payment version that the caller expects. If the server has a different version of the Payment, the update fails and a response with a VERSION_MISMATCH error is returned.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Payouts

client.payouts.list(...)

📝 Description

Retrieves a list of all payouts for the default location. You can filter payouts by location ID, status, time range, and order them in ascending or descending order. To call this endpoint, set PAYOUTS_READ for the OAuth scope.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.payouts.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

location_id: typing.Optional[str]

The ID of the location for which to list the payouts. By default, payouts are returned for the default (main) location associated with the seller.

status: typing.Optional[PayoutStatus] — If provided, only payouts with the given status are returned.

begin_time: typing.Optional[str]

The timestamp for the beginning of the payout creation time, in RFC 3339 format. Inclusive. Default: The current time minus one year.

end_time: typing.Optional[str]

The timestamp for the end of the payout creation time, in RFC 3339 format. Default: The current time.

sort_order: typing.Optional[SortOrder] — The order in which payouts are listed.

cursor: typing.Optional[str]

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. If request parameters change between requests, subsequent results may contain duplicates or missing records.

limit: typing.Optional[int]

The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default: 100

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.payouts.get(...)

📝 Description

Retrieves details of a specific payout identified by a payout ID. To call this endpoint, set PAYOUTS_READ for the OAuth scope.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.payouts.get(
    payout_id="payout_id",
)

⚙️ Parameters

payout_id: str — The ID of the payout to retrieve the information for.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.payouts.list_entries(...)

📝 Description

Retrieves a list of all payout entries for a specific payout. To call this endpoint, set PAYOUTS_READ for the OAuth scope.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.payouts.list_entries(
    payout_id="payout_id",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

payout_id: str — The ID of the payout to retrieve the information for.

sort_order: typing.Optional[SortOrder] — The order in which payout entries are listed.

cursor: typing.Optional[str]

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. If request parameters change between requests, subsequent results may contain duplicates or missing records.

limit: typing.Optional[int]

The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default: 100

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Refunds

client.refunds.list(...)

📝 Description

Retrieves a list of refunds for the account making the request.

Results are eventually consistent, and new refunds or changes to refunds might take several seconds to appear.

The maximum results per page is 100.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.refunds.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

begin_time: typing.Optional[str]

Indicates the start of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the created_at field for each PaymentRefund.

Default: The current time minus one year.

end_time: typing.Optional[str]

Indicates the end of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the created_at field for each PaymentRefund.

Default: The current time.

sort_order: typing.Optional[str]

The order in which results are listed by PaymentRefund.created_at:

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

cursor: typing.Optional[str]

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.

location_id: typing.Optional[str]

Limit results to the location supplied. By default, results are returned for all locations associated with the seller.

status: typing.Optional[str]

If provided, only refunds with the given status are returned. For a list of refund status values, see PaymentRefund.

Default: If omitted, refunds are returned regardless of their status.

source_type: typing.Optional[str]

If provided, only returns refunds whose payments have the indicated source type. Current values include CARD, BANK_ACCOUNT, WALLET, CASH, and EXTERNAL. For information about these payment source types, see Take Payments.

Default: If omitted, refunds are returned regardless of the source type.

limit: typing.Optional[int]

The maximum number of results to be returned in a single page.

It is possible to receive fewer results than the specified limit on a given page.

If the supplied value is greater than 100, no more than 100 results are returned.

Default: 100

updated_at_begin_time: typing.Optional[str]

Indicates the start of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the updated_at field for each PaymentRefund.

Default: If omitted, the time range starts at begin_time.

updated_at_end_time: typing.Optional[str]

Indicates the end of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the updated_at field for each PaymentRefund.

Default: The current time.

sort_field: typing.Optional[ListPaymentRefundsRequestSortField] — The field used to sort results by. The default is CREATED_AT.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.refunds.refund_payment(...)

📝 Description

Refunds a payment. You can refund the entire payment amount or a portion of it. You can use this endpoint to refund a card payment or record a refund of a cash or external payment. For more information, see Refund Payment.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.refunds.refund_payment(
    idempotency_key="9b7f2dcf-49da-4411-b23e-a2d6af21333a",
    amount_money={"amount": 1000, "currency": "USD"},
    app_fee_money={"amount": 10, "currency": "USD"},
    payment_id="R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY",
    reason="Example",
)

⚙️ Parameters

idempotency_key: str

A unique string that identifies this RefundPayment request. The key can be any valid string but must be unique for every RefundPayment request.

Keys are limited to a max of 45 characters - however, the number of allowed characters might be less than 45, if multi-byte characters are used.

For more information, see Idempotency.

amount_money: MoneyParams

The amount of money to refund.

This amount cannot be more than the total_money value of the payment minus the total amount of all previously completed refunds for this payment.

This amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see Working with Monetary Amounts.

The currency code must match the currency associated with the business that is charging the card.

app_fee_money: typing.Optional[MoneyParams]

The amount of money the developer contributes to help cover the refunded amount. This amount is specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents).

The value cannot be more than the amount_money.

You can specify this parameter in a refund request only if the same parameter was also included when taking the payment. This is part of the application fee scenario the API supports. For more information, see Take Payments and Collect Fees.

To set this field, PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission is required. For more information, see Permissions.

payment_id: typing.Optional[str]

The unique ID of the payment being refunded. Required when unlinked=false, otherwise must not be set.

destination_id: typing.Optional[str]

The ID indicating where funds will be refunded to. Required for unlinked refunds. For more information, see Process an Unlinked Refund.

For refunds linked to Square payments, destination_id is usually omitted; in this case, funds will be returned to the original payment source. The field may be specified in order to request a cross-method refund to a gift card. For more information, see Cross-method refunds to gift cards.

unlinked: typing.Optional[bool]

Indicates that the refund is not linked to a Square payment. If set to true, destination_id and location_id must be supplied while payment_id must not be provided.

location_id: typing.Optional[str]

The location ID associated with the unlinked refund. Required for requests specifying unlinked=true. Otherwise, if included when unlinked=false, will throw an error.

customer_id: typing.Optional[str]

The Customer ID of the customer associated with the refund. This is required if the destination_id refers to a card on file created using the Cards API. Only allowed when unlinked=true.

reason: typing.Optional[str] — A description of the reason for the refund.

payment_version_token: typing.Optional[str]

Used for optimistic concurrency. This opaque token identifies the current Payment version that the caller expects. If the server has a different version of the Payment, the update fails and a response with a VERSION_MISMATCH error is returned. If the versions match, or the field is not provided, the refund proceeds as normal.

team_member_id: typing.Optional[str] — An optional TeamMember ID to associate with this refund.

cash_details: typing.Optional[DestinationDetailsCashRefundDetailsParams] — Additional details required when recording an unlinked cash refund (destination_id is CASH).

external_details: typing.Optional[DestinationDetailsExternalRefundDetailsParams]

Additional details required when recording an unlinked external refund (destination_id is EXTERNAL).

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.refunds.get(...)

📝 Description

Retrieves a specific refund using the refund_id.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.refunds.get(
    refund_id="refund_id",
)

⚙️ Parameters

refund_id: str — The unique ID for the desired PaymentRefund.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Sites

client.sites.list()

📝 Description

Lists the Square Online sites that belong to a seller. Sites are listed in descending order by the created_at date.

Note: Square Online APIs are publicly available as part of an early access program. For more information, see Early access program for Square Online APIs.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.sites.list()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Snippets

client.snippets.get(...)

📝 Description

Retrieves your snippet from a Square Online site. A site can contain snippets from multiple snippet applications, but you can retrieve only the snippet that was added by your application.

You can call ListSites to get the IDs of the sites that belong to a seller.

Note: Square Online APIs are publicly available as part of an early access program. For more information, see Early access program for Square Online APIs.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.snippets.get(
    site_id="site_id",
)

⚙️ Parameters

site_id: str — The ID of the site that contains the snippet.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.snippets.upsert(...)

📝 Description

Adds a snippet to a Square Online site or updates the existing snippet on the site. The snippet code is appended to the end of the head element on every page of the site, except checkout pages. A snippet application can add one snippet to a given site.

You can call ListSites to get the IDs of the sites that belong to a seller.

Note: Square Online APIs are publicly available as part of an early access program. For more information, see Early access program for Square Online APIs.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.snippets.upsert(
    site_id="site_id",
    snippet={"content": "<script>var js = 1;</script>"},
)

⚙️ Parameters

site_id: str — The ID of the site where you want to add or update the snippet.

snippet: SnippetParams — The snippet for the site.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.snippets.delete(...)

📝 Description

Removes your snippet from a Square Online site.

You can call ListSites to get the IDs of the sites that belong to a seller.

Note: Square Online APIs are publicly available as part of an early access program. For more information, see Early access program for Square Online APIs.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.snippets.delete(
    site_id="site_id",
)

⚙️ Parameters

site_id: str — The ID of the site that contains the snippet.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Subscriptions

client.subscriptions.create(...)

📝 Description

Enrolls a customer in a subscription.

If you provide a card on file in the request, Square charges the card for the subscription. Otherwise, Square sends an invoice to the customer's email address. The subscription starts immediately, unless the request includes the optional start_date. Each individual subscription is associated with a particular location.

For more information, see Create a subscription.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.subscriptions.create(
    idempotency_key="8193148c-9586-11e6-99f9-28cfe92138cf",
    location_id="S8GWD5R9QB376",
    plan_variation_id="6JHXF3B2CW3YKHDV4XEM674H",
    customer_id="CHFGVKYY8RSV93M5KCYTG4PN0G",
    start_date="2023-06-20",
    card_id="ccof:qy5x8hHGYsgLrp4Q4GB",
    timezone="America/Los_Angeles",
    source={"name": "My Application"},
    phases=[
        {"ordinal": 0, "order_template_id": "U2NaowWxzXwpsZU697x7ZHOAnCNZY"}
    ],
)

⚙️ Parameters

location_id: str — The ID of the location the subscription is associated with.

customer_id: str — The ID of the customer subscribing to the subscription plan variation.

idempotency_key: typing.Optional[str]

A unique string that identifies this CreateSubscription request. If you do not provide a unique string (or provide an empty string as the value), the endpoint treats each request as independent.

For more information, see Idempotency keys.

plan_variation_id: typing.Optional[str] — The ID of the subscription plan variation created using the Catalog API.

start_date: typing.Optional[str]

The YYYY-MM-DD-formatted date to start the subscription. If it is unspecified, the subscription starts immediately.

canceled_date: typing.Optional[str]

The YYYY-MM-DD-formatted date when the newly created subscription is scheduled for cancellation.

This date overrides the cancellation date set in the plan variation configuration. If the cancellation date is earlier than the end date of a subscription cycle, the subscription stops at the canceled date and the subscriber is sent a prorated invoice at the beginning of the canceled cycle.

When the subscription plan of the newly created subscription has a fixed number of cycles and the canceled_date occurs before the subscription plan expires, the specified canceled_date sets the date when the subscription stops through the end of the last cycle.

tax_percentage: typing.Optional[str]

The tax to add when billing the subscription. The percentage is expressed in decimal form, using a '.' as the decimal separator and without a '%' sign. For example, a value of 7.5 corresponds to 7.5%.

price_override_money: typing.Optional[MoneyParams]

A custom price which overrides the cost of a subscription plan variation with STATIC pricing. This field does not affect itemized subscriptions with RELATIVE pricing. Instead, you should edit the Subscription's order template.

card_id: typing.Optional[str]

The ID of the subscriber's card to charge. If it is not specified, the subscriber receives an invoice via email with a link to pay for their subscription.

timezone: typing.Optional[str]

The timezone that is used in date calculations for the subscription. If unset, defaults to the location timezone. If a timezone is not configured for the location, defaults to "America/New_York". Format: the IANA Timezone Database identifier for the location timezone. For a list of time zones, see List of tz database time zones.

source: typing.Optional[SubscriptionSourceParams] — The origination details of the subscription.

monthly_billing_anchor_date: typing.Optional[int] — The day-of-the-month to change the billing date to.

phases: typing.Optional[typing.Sequence[PhaseParams]] — array of phases for this subscription

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.subscriptions.bulk_swap_plan(...)

📝 Description

Schedules a plan variation change for all active subscriptions under a given plan variation. For more information, see Swap Subscription Plan Variations.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.subscriptions.bulk_swap_plan(
    new_plan_variation_id="FQ7CDXXWSLUJRPM3GFJSJGZ7",
    old_plan_variation_id="6JHXF3B2CW3YKHDV4XEM674H",
    location_id="S8GWD5R9QB376",
)

⚙️ Parameters

new_plan_variation_id: str

The ID of the new subscription plan variation.

This field is required.

old_plan_variation_id: str

The ID of the plan variation whose subscriptions should be swapped. Active subscriptions using this plan variation will be subscribed to the new plan variation on their next billing day.

location_id: str — The ID of the location to associate with the swapped subscriptions.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.subscriptions.search(...)

📝 Description

Searches for subscriptions.

Results are ordered chronologically by subscription creation date. If the request specifies more than one location ID, the endpoint orders the result by location ID, and then by creation date within each location. If no locations are given in the query, all locations are searched.

You can also optionally specify customer_ids to search by customer. If left unset, all customers associated with the specified locations are returned. If the request specifies customer IDs, the endpoint orders results first by location, within location by customer ID, and within customer by subscription creation date.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.subscriptions.search(
    query={
        "filter": {
            "customer_ids": ["CHFGVKYY8RSV93M5KCYTG4PN0G"],
            "location_ids": ["S8GWD5R9QB376"],
            "source_names": ["My App"],
        }
    },
)

⚙️ Parameters

cursor: typing.Optional[str]

When the total number of resulting subscriptions exceeds the limit of a paged response, specify the cursor returned from a preceding response here to fetch the next set of results. If the cursor is unset, the response contains the last page of the results.

For more information, see Pagination.

limit: typing.Optional[int]

The upper limit on the number of subscriptions to return in a paged response.

query: typing.Optional[SearchSubscriptionsQueryParams]

A subscription query consisting of specified filtering conditions.

If this query field is unspecified, the SearchSubscriptions call will return all subscriptions.

include: typing.Optional[typing.Sequence[str]]

An option to include related information in the response.

The supported values are:

  • actions: to include scheduled actions on the targeted subscriptions.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.subscriptions.get(...)

📝 Description

Retrieves a specific subscription.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.subscriptions.get(
    subscription_id="subscription_id",
)

⚙️ Parameters

subscription_id: str — The ID of the subscription to retrieve.

include: typing.Optional[str]

A query parameter to specify related information to be included in the response.

The supported query parameter values are:

  • actions: to include scheduled actions on the targeted subscription.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.subscriptions.update(...)

📝 Description

Updates a subscription by modifying or clearing subscription field values. To clear a field, set its value to null.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.subscriptions.update(
    subscription_id="subscription_id",
    subscription={"card_id": "{NEW CARD ID}"},
)

⚙️ Parameters

subscription_id: str — The ID of the subscription to update.

subscription: typing.Optional[SubscriptionParams]

The subscription object containing the current version, and fields to update. Unset fields will be left at their current server values, and JSON null values will be treated as a request to clear the relevant data.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.subscriptions.delete_action(...)

📝 Description

Deletes a scheduled action for a subscription.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.subscriptions.delete_action(
    subscription_id="subscription_id",
    action_id="action_id",
)

⚙️ Parameters

subscription_id: str — The ID of the subscription the targeted action is to act upon.

action_id: str — The ID of the targeted action to be deleted.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.subscriptions.change_billing_anchor_date(...)

📝 Description

Changes the billing anchor date for a subscription.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.subscriptions.change_billing_anchor_date(
    subscription_id="subscription_id",
    monthly_billing_anchor_date=1,
)

⚙️ Parameters

subscription_id: str — The ID of the subscription to update the billing anchor date.

monthly_billing_anchor_date: typing.Optional[int] — The anchor day for the billing cycle.

effective_date: typing.Optional[str]

The YYYY-MM-DD-formatted date when the scheduled BILLING_ANCHOR_CHANGE action takes place on the subscription.

When this date is unspecified or falls within the current billing cycle, the billing anchor date is changed immediately.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.subscriptions.cancel(...)

📝 Description

Schedules a CANCEL action to cancel an active subscription. This sets the canceled_date field to the end of the active billing period. After this date, the subscription status changes from ACTIVE to CANCELED.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.subscriptions.cancel(
    subscription_id="subscription_id",
)

⚙️ Parameters

subscription_id: str — The ID of the subscription to cancel.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.subscriptions.list_events(...)

📝 Description

Lists all events for a specific subscription.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.subscriptions.list_events(
    subscription_id="subscription_id",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

subscription_id: str — The ID of the subscription to retrieve the events for.

cursor: typing.Optional[str]

When the total number of resulting subscription events exceeds the limit of a paged response, specify the cursor returned from a preceding response here to fetch the next set of results. If the cursor is unset, the response contains the last page of the results.

For more information, see Pagination.

limit: typing.Optional[int]

The upper limit on the number of subscription events to return in a paged response.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.subscriptions.pause(...)

📝 Description

Schedules a PAUSE action to pause an active subscription.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.subscriptions.pause(
    subscription_id="subscription_id",
)

⚙️ Parameters

subscription_id: str — The ID of the subscription to pause.

pause_effective_date: typing.Optional[str]

The YYYY-MM-DD-formatted date when the scheduled PAUSE action takes place on the subscription.

When this date is unspecified or falls within the current billing cycle, the subscription is paused on the starting date of the next billing cycle.

pause_cycle_duration: typing.Optional[int]

The number of billing cycles the subscription will be paused before it is reactivated.

When this is set, a RESUME action is also scheduled to take place on the subscription at the end of the specified pause cycle duration. In this case, neither resume_effective_date nor resume_change_timing may be specified.

resume_effective_date: typing.Optional[str]

The date when the subscription is reactivated by a scheduled RESUME action. This date must be at least one billing cycle ahead of pause_effective_date.

resume_change_timing: typing.Optional[ChangeTiming]

The timing whether the subscription is reactivated immediately or at the end of the billing cycle, relative to resume_effective_date. See ChangeTiming for possible values

pause_reason: typing.Optional[str] — The user-provided reason to pause the subscription.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.subscriptions.resume(...)

📝 Description

Schedules a RESUME action to resume a paused or a deactivated subscription.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.subscriptions.resume(
    subscription_id="subscription_id",
)

⚙️ Parameters

subscription_id: str — The ID of the subscription to resume.

resume_effective_date: typing.Optional[str] — The YYYY-MM-DD-formatted date when the subscription reactivated.

resume_change_timing: typing.Optional[ChangeTiming]

The timing to resume a subscription, relative to the specified resume_effective_date attribute value. See ChangeTiming for possible values

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.subscriptions.swap_plan(...)

📝 Description

Schedules a SWAP_PLAN action to swap a subscription plan variation in an existing subscription. For more information, see Swap Subscription Plan Variations.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.subscriptions.swap_plan(
    subscription_id="subscription_id",
    new_plan_variation_id="FQ7CDXXWSLUJRPM3GFJSJGZ7",
    phases=[
        {"ordinal": 0, "order_template_id": "uhhnjH9osVv3shUADwaC0b3hNxQZY"}
    ],
)

⚙️ Parameters

subscription_id: str — The ID of the subscription to swap the subscription plan for.

new_plan_variation_id: typing.Optional[str]

The ID of the new subscription plan variation.

This field is required.

phases: typing.Optional[typing.Sequence[PhaseInputParams]] — A list of PhaseInputs, to pass phase-specific information used in the swap.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

TeamMembers

client.team_members.create(...)

📝 Description

Creates a single TeamMember object. The TeamMember object is returned on successful creates. You must provide the following values in your request to this endpoint:

  • given_name
  • family_name

Learn about Troubleshooting the Team API.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.team_members.create(
    idempotency_key="idempotency-key-0",
    team_member={
        "reference_id": "reference_id_1",
        "status": "ACTIVE",
        "given_name": "Joe",
        "family_name": "Doe",
        "email_address": "joe_doe@gmail.com",
        "phone_number": "+14159283333",
        "assigned_locations": {
            "assignment_type": "EXPLICIT_LOCATIONS",
            "location_ids": ["YSGH2WBKG94QZ", "GA2Y9HSJ8KRYT"],
        },
        "wage_setting": {
            "job_assignments": [
                {
                    "pay_type": "SALARY",
                    "annual_rate": {"amount": 3000000, "currency": "USD"},
                    "weekly_hours": 40,
                    "job_id": "FjS8x95cqHiMenw4f1NAUH4P",
                },
                {
                    "pay_type": "HOURLY",
                    "hourly_rate": {"amount": 2000, "currency": "USD"},
                    "job_id": "VDNpRv8da51NU8qZFC5zDWpF",
                },
            ],
            "is_overtime_exempt": True,
        },
    },
)

⚙️ Parameters

idempotency_key: typing.Optional[str]

A unique string that identifies this CreateTeamMember request. Keys can be any valid string, but must be unique for every request. For more information, see Idempotency.

The minimum length is 1 and the maximum length is 45.

team_member: typing.Optional[TeamMemberParams]

Required The data used to create the TeamMember object. If you include wage_setting, you must provide job_id for each job assignment. To get job IDs, call ListJobs.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.team_members.batch_create(...)

📝 Description

Creates multiple TeamMember objects. The created TeamMember objects are returned on successful creates. This process is non-transactional and processes as much of the request as possible. If one of the creates in the request cannot be successfully processed, the request is not marked as failed, but the body of the response contains explicit error information for the failed create.

Learn about Troubleshooting the Team API.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.team_members.batch_create(
    team_members={
        "idempotency-key-1": {
            "team_member": {
                "reference_id": "reference_id_1",
                "given_name": "Joe",
                "family_name": "Doe",
                "email_address": "joe_doe@gmail.com",
                "phone_number": "+14159283333",
                "assigned_locations": {
                    "assignment_type": "EXPLICIT_LOCATIONS",
                    "location_ids": ["YSGH2WBKG94QZ", "GA2Y9HSJ8KRYT"],
                },
            }
        },
        "idempotency-key-2": {
            "team_member": {
                "reference_id": "reference_id_2",
                "given_name": "Jane",
                "family_name": "Smith",
                "email_address": "jane_smith@gmail.com",
                "phone_number": "+14159223334",
                "assigned_locations": {
                    "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
                },
            }
        },
    },
)

⚙️ Parameters

team_members: typing.Dict[str, CreateTeamMemberRequestParams]

The data used to create the TeamMember objects. Each key is the idempotency_key that maps to the CreateTeamMemberRequest. The maximum number of create objects is 25.

If you include a team member's wage_setting, you must provide job_id for each job assignment. To get job IDs, call ListJobs.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.team_members.batch_update(...)

📝 Description

Updates multiple TeamMember objects. The updated TeamMember objects are returned on successful updates. This process is non-transactional and processes as much of the request as possible. If one of the updates in the request cannot be successfully processed, the request is not marked as failed, but the body of the response contains explicit error information for the failed update. Learn about Troubleshooting the Team API.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.team_members.batch_update(
    team_members={
        "AFMwA08kR-MIF-3Vs0OE": {
            "team_member": {
                "reference_id": "reference_id_2",
                "is_owner": False,
                "status": "ACTIVE",
                "given_name": "Jane",
                "family_name": "Smith",
                "email_address": "jane_smith@gmail.com",
                "phone_number": "+14159223334",
                "assigned_locations": {
                    "assignment_type": "ALL_CURRENT_AND_FUTURE_LOCATIONS"
                },
            }
        },
        "fpgteZNMaf0qOK-a4t6P": {
            "team_member": {
                "reference_id": "reference_id_1",
                "is_owner": False,
                "status": "ACTIVE",
                "given_name": "Joe",
                "family_name": "Doe",
                "email_address": "joe_doe@gmail.com",
                "phone_number": "+14159283333",
                "assigned_locations": {
                    "assignment_type": "EXPLICIT_LOCATIONS",
                    "location_ids": ["YSGH2WBKG94QZ", "GA2Y9HSJ8KRYT"],
                },
            }
        },
    },
)

⚙️ Parameters

team_members: typing.Dict[str, UpdateTeamMemberRequestParams]

The data used to update the TeamMember objects. Each key is the team_member_id that maps to the UpdateTeamMemberRequest. The maximum number of update objects is 25.

For each team member, include the fields to add, change, or clear. Fields can be cleared using a null value. To update wage_setting.job_assignments, you must provide the complete list of job assignments. If needed, call ListJobs to get the required job_id values.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.team_members.search(...)

📝 Description

Returns a paginated list of TeamMember objects for a business. The list can be filtered by location IDs, ACTIVE or INACTIVE status, or whether the team member is the Square account owner.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.team_members.search(
    query={"filter": {"location_ids": ["0G5P3VGACMMQZ"], "status": "ACTIVE"}},
    limit=10,
)

⚙️ Parameters

query: typing.Optional[SearchTeamMembersQueryParams] — The query parameters.

limit: typing.Optional[int] — The maximum number of TeamMember objects in a page (100 by default).

cursor: typing.Optional[str]

The opaque cursor for fetching the next page. For more information, see pagination.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.team_members.get(...)

📝 Description

Retrieves a TeamMember object for the given TeamMember.id. Learn about Troubleshooting the Team API.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.team_members.get(
    team_member_id="team_member_id",
)

⚙️ Parameters

team_member_id: str — The ID of the team member to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.team_members.update(...)

📝 Description

Updates a single TeamMember object. The TeamMember object is returned on successful updates. Learn about Troubleshooting the Team API.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.team_members.update(
    team_member_id="team_member_id",
    team_member={
        "reference_id": "reference_id_1",
        "status": "ACTIVE",
        "given_name": "Joe",
        "family_name": "Doe",
        "email_address": "joe_doe@gmail.com",
        "phone_number": "+14159283333",
        "assigned_locations": {
            "assignment_type": "EXPLICIT_LOCATIONS",
            "location_ids": ["YSGH2WBKG94QZ", "GA2Y9HSJ8KRYT"],
        },
        "wage_setting": {
            "job_assignments": [
                {
                    "pay_type": "SALARY",
                    "annual_rate": {"amount": 3000000, "currency": "USD"},
                    "weekly_hours": 40,
                    "job_id": "FjS8x95cqHiMenw4f1NAUH4P",
                },
                {
                    "pay_type": "HOURLY",
                    "hourly_rate": {"amount": 1200, "currency": "USD"},
                    "job_id": "VDNpRv8da51NU8qZFC5zDWpF",
                },
            ],
            "is_overtime_exempt": True,
        },
    },
)

⚙️ Parameters

team_member_id: str — The ID of the team member to update.

team_member: typing.Optional[TeamMemberParams]

The team member fields to add, change, or clear. Fields can be cleared using a null value. To update wage_setting.job_assignments, you must provide the complete list of job assignments. If needed, call ListJobs to get the required job_id values.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Team

client.team.list_jobs(...)

📝 Description

Lists jobs in a seller account. Results are sorted by title in ascending order.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.team.list_jobs()

⚙️ Parameters

cursor: typing.Optional[str]

The pagination cursor returned by the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.team.create_job(...)

📝 Description

Creates a job in a seller account. A job defines a title and tip eligibility. Note that compensation is defined in a job assignment in a team member's wage setting.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.team.create_job(
    job={"title": "Cashier", "is_tip_eligible": True},
    idempotency_key="idempotency-key-0",
)

⚙️ Parameters

job: JobParams — The job to create. The title field is required and is_tip_eligible defaults to true.

idempotency_key: str

A unique identifier for the CreateJob request. Keys can be any valid string, but must be unique for each request. For more information, see Idempotency.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.team.retrieve_job(...)

📝 Description

Retrieves a specified job.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.team.retrieve_job(
    job_id="job_id",
)

⚙️ Parameters

job_id: str — The ID of the job to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.team.update_job(...)

📝 Description

Updates the title or tip eligibility of a job. Changes to the title propagate to all JobAssignment, Shift, and TeamMemberWage objects that reference the job ID. Changes to tip eligibility propagate to all TeamMemberWage objects that reference the job ID.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.team.update_job(
    job_id="job_id",
    job={"title": "Cashier 1", "is_tip_eligible": True},
)

⚙️ Parameters

job_id: str — The ID of the job to update.

job: JobParams

The job with the updated fields, either title, is_tip_eligible, or both. Only changed fields need to be included in the request. Optionally include version to enable optimistic concurrency control.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Terminal

client.terminal.dismiss_terminal_action(...)

📝 Description

Dismisses a Terminal action request if the status and type of the request permits it.

See Link and Dismiss Actions for more details.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.dismiss_terminal_action(
    action_id="action_id",
)

⚙️ Parameters

action_id: str — Unique ID for the TerminalAction associated with the action to be dismissed.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.terminal.dismiss_terminal_checkout(...)

📝 Description

Dismisses a Terminal checkout request if the status and type of the request permits it.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.dismiss_terminal_checkout(
    checkout_id="checkout_id",
)

⚙️ Parameters

checkout_id: str — Unique ID for the TerminalCheckout associated with the checkout to be dismissed.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.terminal.dismiss_terminal_refund(...)

📝 Description

Dismisses a Terminal refund request if the status and type of the request permits it.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.dismiss_terminal_refund(
    terminal_refund_id="terminal_refund_id",
)

⚙️ Parameters

terminal_refund_id: str — Unique ID for the TerminalRefund associated with the refund to be dismissed.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Vendors

client.vendors.batch_create(...)

📝 Description

Creates one or more Vendor objects to represent suppliers to a seller.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.vendors.batch_create(
    vendors={
        "8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe": {
            "name": "Joe's Fresh Seafood",
            "address": {
                "address_line1": "505 Electric Ave",
                "address_line2": "Suite 600",
                "locality": "New York",
                "administrative_district_level1": "NY",
                "postal_code": "10003",
                "country": "US",
            },
            "contacts": [
                {
                    "name": "Joe Burrow",
                    "email_address": "joe@joesfreshseafood.com",
                    "phone_number": "1-212-555-4250",
                    "ordinal": 1,
                }
            ],
            "account_number": "4025391",
            "note": "a vendor",
        }
    },
)

⚙️ Parameters

vendors: typing.Dict[str, VendorParams] — Specifies a set of new Vendor objects as represented by a collection of idempotency-key/Vendor-object pairs.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.vendors.batch_get(...)

📝 Description

Retrieves one or more vendors of specified Vendor IDs.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.vendors.batch_get(
    vendor_ids=["INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4"],
)

⚙️ Parameters

vendor_ids: typing.Optional[typing.Sequence[str]] — IDs of the Vendor objects to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.vendors.batch_update(...)

📝 Description

Updates one or more of existing Vendor objects as suppliers to a seller.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.vendors.batch_update(
    vendors={
        "FMCYHBWT1TPL8MFH52PBMEN92A": {"vendor": {}},
        "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4": {"vendor": {}},
    },
)

⚙️ Parameters

vendors: typing.Dict[str, UpdateVendorRequestParams]

A set of UpdateVendorRequest objects encapsulating to-be-updated Vendor objects. The set is represented by a collection of Vendor-ID/UpdateVendorRequest-object pairs.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.vendors.create(...)

📝 Description

Creates a single Vendor object to represent a supplier to a seller.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.vendors.create(
    idempotency_key="8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe",
    vendor={
        "name": "Joe's Fresh Seafood",
        "address": {
            "address_line1": "505 Electric Ave",
            "address_line2": "Suite 600",
            "locality": "New York",
            "administrative_district_level1": "NY",
            "postal_code": "10003",
            "country": "US",
        },
        "contacts": [
            {
                "name": "Joe Burrow",
                "email_address": "joe@joesfreshseafood.com",
                "phone_number": "1-212-555-4250",
                "ordinal": 1,
            }
        ],
        "account_number": "4025391",
        "note": "a vendor",
    },
)

⚙️ Parameters

idempotency_key: str

A client-supplied, universally unique identifier (UUID) to make this CreateVendor call idempotent.

See Idempotency in the API Development 101 section for more information.

vendor: typing.Optional[VendorParams] — The requested Vendor to be created.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.vendors.search(...)

📝 Description

Searches for vendors using a filter against supported Vendor properties and a supported sorter.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.vendors.search()

⚙️ Parameters

filter: typing.Optional[SearchVendorsRequestFilterParams] — Specifies a filter used to search for vendors.

sort: typing.Optional[SearchVendorsRequestSortParams] — Specifies a sorter used to sort the returned vendors.

cursor: typing.Optional[str]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.vendors.get(...)

📝 Description

Retrieves the vendor of a specified Vendor ID.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.vendors.get(
    vendor_id="vendor_id",
)

⚙️ Parameters

vendor_id: str — ID of the Vendor to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.vendors.update(...)

📝 Description

Updates an existing Vendor object as a supplier to a seller.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.vendors.update(
    vendor_id="vendor_id",
    idempotency_key="8fc6a5b0-9fe8-4b46-b46b-2ef95793abbe",
    vendor={
        "id": "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4",
        "name": "Jack's Chicken Shack",
        "version": 1,
        "status": "ACTIVE",
    },
)

⚙️ Parameters

vendor_id: str — ID of the Vendor to retrieve.

vendor: VendorParams — The specified Vendor to be updated.

idempotency_key: typing.Optional[str]

A client-supplied, universally unique identifier (UUID) for the request.

See Idempotency in the API Development 101 section for more information.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Bookings CustomAttributeDefinitions

client.bookings.custom_attribute_definitions.list(...)

📝 Description

Get all bookings custom attribute definitions.

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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.bookings.custom_attribute_definitions.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

limit: typing.Optional[int]

The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.

cursor: typing.Optional[str]

The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.custom_attribute_definitions.create(...)

📝 Description

Creates a bookings custom attribute definition.

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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.custom_attribute_definitions.create(
    custom_attribute_definition={},
)

⚙️ Parameters

custom_attribute_definition: CustomAttributeDefinitionParams

The custom attribute definition to create, with the following fields:

  • key

  • name. If provided, name must be unique (case-sensitive) across all visible booking-related custom attribute definitions for the seller.

  • description

  • visibility. Note that all custom attributes are visible in exported booking data, including those set to VISIBILITY_HIDDEN.

  • schema. With the exception of the Selection data type, the schema is specified as a simple URL to the JSON schema definition hosted on the Square CDN. For more information, see Specifying the schema.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.custom_attribute_definitions.get(...)

📝 Description

Retrieves a bookings custom attribute definition.

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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.custom_attribute_definitions.get(
    key="key",
)

⚙️ Parameters

key: str

The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.

version: typing.Optional[int]

The current version of the custom attribute definition, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.custom_attribute_definitions.update(...)

📝 Description

Updates a bookings custom attribute definition.

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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.custom_attribute_definitions.update(
    key="key",
    custom_attribute_definition={},
)

⚙️ Parameters

key: str — The key of the custom attribute definition to update.

custom_attribute_definition: CustomAttributeDefinitionParams

The custom attribute definition that contains the fields to update. Only the following fields can be updated:

  • name
  • description
  • visibility
  • schema for a Selection data type. Only changes to the named options or the maximum number of allowed selections are supported.

For more information, see Updatable definition fields.

To enable optimistic concurrency control, include the optional version field and specify the current version of the custom attribute definition.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.custom_attribute_definitions.delete(...)

📝 Description

Deletes a bookings custom attribute definition.

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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.custom_attribute_definitions.delete(
    key="key",
)

⚙️ Parameters

key: str — The key of the custom attribute definition to delete.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Bookings CustomAttributes

client.bookings.custom_attributes.batch_delete(...)

📝 Description

Bulk deletes bookings custom attributes.

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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.custom_attributes.batch_delete(
    values={"key": {"booking_id": "booking_id", "key": "key"}},
)

⚙️ Parameters

values: typing.Dict[str, BookingCustomAttributeDeleteRequestParams]

A map containing 1 to 25 individual Delete requests. For each request, provide an arbitrary ID that is unique for this BulkDeleteBookingCustomAttributes request and the information needed to delete a custom attribute.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.custom_attributes.batch_upsert(...)

📝 Description

Bulk upserts bookings custom attributes.

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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.custom_attributes.batch_upsert(
    values={"key": {"booking_id": "booking_id", "custom_attribute": {}}},
)

⚙️ Parameters

values: typing.Dict[str, BookingCustomAttributeUpsertRequestParams]

A map containing 1 to 25 individual upsert requests. For each request, provide an arbitrary ID that is unique for this BulkUpsertBookingCustomAttributes request and the information needed to create or update a custom attribute.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.custom_attributes.list(...)

📝 Description

Lists a booking's custom attributes.

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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.bookings.custom_attributes.list(
    booking_id="booking_id",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

booking_id: str — The ID of the target booking.

limit: typing.Optional[int]

The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.

cursor: typing.Optional[str]

The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.

with_definitions: typing.Optional[bool]

Indicates whether to return the custom attribute definition in the definition field of each custom attribute. Set this parameter to true to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is false.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.custom_attributes.get(...)

📝 Description

Retrieves a bookings custom attribute.

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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.custom_attributes.get(
    booking_id="booking_id",
    key="key",
)

⚙️ Parameters

booking_id: str — The ID of the target booking.

key: str

The key of the custom attribute to retrieve. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.

with_definition: typing.Optional[bool]

Indicates whether to return the custom attribute definition in the definition field of the custom attribute. Set this parameter to true to get the name and description of the custom attribute, information about the data type, or other definition details. The default value is false.

version: typing.Optional[int]

The current version of the custom attribute, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.custom_attributes.upsert(...)

📝 Description

Upserts a bookings custom attribute.

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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.custom_attributes.upsert(
    booking_id="booking_id",
    key="key",
    custom_attribute={},
)

⚙️ Parameters

booking_id: str — The ID of the target booking.

key: str

The key of the custom attribute to create or update. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.

custom_attribute: CustomAttributeParams

The custom attribute to create or update, with the following fields:

  • value. This value must conform to the schema specified by the definition. For more information, see Value data types.

  • version. To enable optimistic concurrency control for an update operation, include this optional field and specify the current version of the custom attribute.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.custom_attributes.delete(...)

📝 Description

Deletes a bookings custom attribute.

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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.custom_attributes.delete(
    booking_id="booking_id",
    key="key",
)

⚙️ Parameters

booking_id: str — The ID of the target booking.

key: str

The key of the custom attribute to delete. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Bookings LocationProfiles

client.bookings.location_profiles.list(...)

📝 Description

Lists location booking profiles of a seller.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.bookings.location_profiles.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

limit: typing.Optional[int] — The maximum number of results to return in a paged response.

cursor: typing.Optional[str] — 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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Bookings TeamMemberProfiles

client.bookings.team_member_profiles.list(...)

📝 Description

Lists booking profiles for team members.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.bookings.team_member_profiles.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

bookable_only: typing.Optional[bool] — Indicates whether to include only bookable team members in the returned result (true) or not (false).

limit: typing.Optional[int] — The maximum number of results to return in a paged response.

cursor: typing.Optional[str] — 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.

location_id: typing.Optional[str] — Indicates whether to include only team members enabled at the given location in the returned result.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.bookings.team_member_profiles.get(...)

📝 Description

Retrieves a team member's booking profile.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.bookings.team_member_profiles.get(
    team_member_id="team_member_id",
)

⚙️ Parameters

team_member_id: str — The ID of the team member to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

CashDrawers Shifts

client.cash_drawers.shifts.list(...)

📝 Description

Provides the details for all of the cash drawer shifts for a location in a date range.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.cash_drawers.shifts.list(
    location_id="location_id",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

location_id: str — The ID of the location to query for a list of cash drawer shifts.

sort_order: typing.Optional[SortOrder]

The order in which cash drawer shifts are listed in the response, based on their opened_at field. Default value: ASC

begin_time: typing.Optional[str] — The inclusive start time of the query on opened_at, in ISO 8601 format.

end_time: typing.Optional[str] — The exclusive end date of the query on opened_at, in ISO 8601 format.

limit: typing.Optional[int]

Number of cash drawer shift events in a page of results (200 by default, 1000 max).

cursor: typing.Optional[str] — Opaque cursor for fetching the next page of results.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.cash_drawers.shifts.get(...)

📝 Description

Provides the summary details for a single cash drawer shift. See ListCashDrawerShiftEvents for a list of cash drawer shift events.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.cash_drawers.shifts.get(
    shift_id="shift_id",
    location_id="location_id",
)

⚙️ Parameters

shift_id: str — The shift ID.

location_id: str — The ID of the location to retrieve cash drawer shifts from.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.cash_drawers.shifts.list_events(...)

📝 Description

Provides a paginated list of events for a single cash drawer shift.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.cash_drawers.shifts.list_events(
    shift_id="shift_id",
    location_id="location_id",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

shift_id: str — The shift ID.

location_id: str — The ID of the location to list cash drawer shifts for.

limit: typing.Optional[int]

Number of resources to be returned in a page of results (200 by default, 1000 max).

cursor: typing.Optional[str] — Opaque cursor for fetching the next page of results.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Catalog Images

client.catalog.images.create(...)

📝 Description

Uploads an image file to be represented by a CatalogImage object that can be linked to an existing CatalogObject instance. The resulting CatalogImage is unattached to any CatalogObject if the object_id is not specified.

This CreateCatalogImage endpoint accepts HTTP multipart/form-data requests with a JSON part and an image file part in JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.catalog.images.create()

⚙️ Parameters

request: typing.Optional[CreateCatalogImageRequestParams]

image_file: `from future import annotations

typing.Optional[core.File]` — See core.File for more documentation

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.catalog.images.update(...)

📝 Description

Uploads a new image file to replace the existing one in the specified CatalogImage object.

This UpdateCatalogImage endpoint accepts HTTP multipart/form-data requests with a JSON part and an image file part in JPEG, PJPEG, PNG, or GIF format. The maximum file size is 15MB.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.catalog.images.update(
    image_id="image_id",
)

⚙️ Parameters

image_id: str — The ID of the CatalogImage object to update the encapsulated image file.

request: typing.Optional[UpdateCatalogImageRequestParams]

image_file: `from future import annotations

typing.Optional[core.File]` — See core.File for more documentation

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Catalog Object

client.catalog.object.upsert(...)

📝 Description

Creates a new or updates the specified CatalogObject.

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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.catalog.object.upsert(
    idempotency_key="af3d1afc-7212-4300-b463-0bfc5314a5ae",
    object={"type": "IMAGE", "id": "#Cocoa"},
)

⚙️ Parameters

idempotency_key: str

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.

object: CatalogObjectParams

A CatalogObject to be created or updated.

  • For updates, the object must be active (the is_deleted field is not true).
  • For creates, the object ID must start with #. The provided ID is replaced with a server-generated ID.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.catalog.object.get(...)

📝 Description

Returns a single CatalogItem as a CatalogObject based on the provided ID. The returned object includes all of the relevant CatalogItem information including: CatalogItemVariation children, references to its CatalogModifierList objects, and the ids of any CatalogTax objects that apply to it.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.catalog.object.get(
    object_id="object_id",
)

⚙️ Parameters

object_id: str — The object ID of any type of catalog objects to be retrieved.

include_related_objects: typing.Optional[bool]

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

catalog_version: typing.Optional[int]

Requests objects as of a specific version of the catalog. This allows you to retrieve historical versions of objects. The value to retrieve a specific version of an object can be found in the version field of CatalogObjects. If not included, results will be from the current version of the catalog.

include_category_path_to_root: typing.Optional[bool]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.catalog.object.delete(...)

📝 Description

Deletes a single CatalogObject based on the provided ID and returns the 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.

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

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.catalog.object.delete(
    object_id="object_id",
)

⚙️ Parameters

object_id: str

The ID of the catalog object 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 catalog item will delete its catalog item variations).

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Checkout PaymentLinks

client.checkout.payment_links.list(...)

📝 Description

Lists all payment links.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.checkout.payment_links.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

cursor: typing.Optional[str]

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.

limit: typing.Optional[int]

A limit on the number of results to return per page. The limit is advisory and the implementation might return more or less results. If the supplied limit is negative, zero, or greater than the maximum limit of 1000, it is ignored.

Default value: 100

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.checkout.payment_links.create(...)

📝 Description

Creates a Square-hosted checkout page. Applications can share the resulting payment link with their buyer to pay for goods and services.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.checkout.payment_links.create(
    idempotency_key="cd9e25dc-d9f2-4430-aedb-61605070e95f",
    quick_pay={
        "name": "Auto Detailing",
        "price_money": {"amount": 10000, "currency": "USD"},
        "location_id": "A9Y43N9ABXZBP",
    },
)

⚙️ Parameters

idempotency_key: typing.Optional[str]

A unique string that identifies this CreatePaymentLinkRequest request. If you do not provide a unique string (or provide an empty string as the value), the endpoint treats each request as independent.

For more information, see Idempotency.

description: typing.Optional[str]

A description of the payment link. You provide this optional description that is useful in your application context. It is not used anywhere.

quick_pay: typing.Optional[QuickPayParams]

Describes an ad hoc item and price for which to generate a quick pay checkout link. For more information, see Quick Pay Checkout.

order: typing.Optional[OrderParams]

Describes the Order for which to create a checkout link. For more information, see Square Order Checkout.

checkout_options: typing.Optional[CheckoutOptionsParams]

Describes optional fields to add to the resulting checkout page. For more information, see Optional Checkout Configurations.

pre_populated_data: typing.Optional[PrePopulatedDataParams]

Describes fields to prepopulate in the resulting checkout page. For more information, see Prepopulate the shipping address.

payment_note: typing.Optional[str] — A note for the payment. After processing the payment, Square adds this note to the resulting Payment.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.checkout.payment_links.get(...)

📝 Description

Retrieves a payment link.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.checkout.payment_links.get(
    id="id",
)

⚙️ Parameters

id: str — The ID of link to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.checkout.payment_links.update(...)

📝 Description

Updates a payment link. You can update the payment_link fields such as description, checkout_options, and pre_populated_data. You cannot update other fields such as the order_id, version, URL, or timestamp field.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.checkout.payment_links.update(
    id="id",
    payment_link={
        "version": 1,
        "checkout_options": {"ask_for_shipping_address": True},
    },
)

⚙️ Parameters

id: str — The ID of the payment link to update.

payment_link: PaymentLinkParams

The payment_link object describing the updates to apply. For more information, see Update a payment link.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.checkout.payment_links.delete(...)

📝 Description

Deletes a payment link.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.checkout.payment_links.delete(
    id="id",
)

⚙️ Parameters

id: str — The ID of the payment link to delete.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Customers CustomAttributeDefinitions

client.customers.custom_attribute_definitions.list(...)

📝 Description

Lists the customer-related custom attribute definitions that belong to a Square seller account.

When all response pages are retrieved, the results include all custom attribute definitions that are visible to the requesting application, including those that are created by other applications and set to VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.customers.custom_attribute_definitions.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

limit: typing.Optional[int]

The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.

cursor: typing.Optional[str]

The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.custom_attribute_definitions.create(...)

📝 Description

Creates a customer-related custom attribute definition for a Square seller account. Use this endpoint to define a custom attribute that can be associated with customer profiles.

A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute. After the definition is created, you can call UpsertCustomerCustomAttribute or BulkUpsertCustomerCustomAttributes to set the custom attribute for customer profiles in the seller's Customer Directory.

Sellers can view all custom attributes in exported customer data, including those set to VISIBILITY_HIDDEN.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.custom_attribute_definitions.create(
    custom_attribute_definition={
        "key": "favoritemovie",
        "schema": {
            "ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
        },
        "name": "Favorite Movie",
        "description": "The favorite movie of the customer.",
        "visibility": "VISIBILITY_HIDDEN",
    },
)

⚙️ Parameters

custom_attribute_definition: CustomAttributeDefinitionParams

The custom attribute definition to create. Note the following:

  • With the exception of the Selection data type, the schema is specified as a simple URL to the JSON schema definition hosted on the Square CDN. For more information, including supported values and constraints, see Specifying the schema.
  • If provided, name must be unique (case-sensitive) across all visible customer-related custom attribute definitions for the seller.
  • All custom attributes are visible in exported customer data, including those set to VISIBILITY_HIDDEN.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.custom_attribute_definitions.get(...)

📝 Description

Retrieves a customer-related custom attribute definition from a Square seller account.

To retrieve a custom attribute definition created by another application, the visibility setting must be VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.custom_attribute_definitions.get(
    key="key",
)

⚙️ Parameters

key: str

The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.

version: typing.Optional[int]

The current version of the custom attribute definition, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.custom_attribute_definitions.update(...)

📝 Description

Updates a customer-related custom attribute definition for a Square seller account.

Use this endpoint to update the following fields: name, description, visibility, or the schema for a Selection data type.

Only the definition owner can update a custom attribute definition. Note that sellers can view all custom attributes in exported customer data, including those set to VISIBILITY_HIDDEN.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.custom_attribute_definitions.update(
    key="key",
    custom_attribute_definition={
        "description": "Update the description as desired.",
        "visibility": "VISIBILITY_READ_ONLY",
    },
)

⚙️ Parameters

key: str — The key of the custom attribute definition to update.

custom_attribute_definition: CustomAttributeDefinitionParams

The custom attribute definition that contains the fields to update. This endpoint supports sparse updates, so only new or changed fields need to be included in the request. Only the following fields can be updated:

  • name
  • description
  • visibility
  • schema for a Selection data type. Only changes to the named options or the maximum number of allowed selections are supported.

For more information, see Updatable definition fields.

To enable optimistic concurrency control, include the optional version field and specify the current version of the custom attribute definition.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.custom_attribute_definitions.delete(...)

📝 Description

Deletes a customer-related custom attribute definition from a Square seller account.

Deleting a custom attribute definition also deletes the corresponding custom attribute from all customer profiles in the seller's Customer Directory.

Only the definition owner can delete a custom attribute definition.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.custom_attribute_definitions.delete(
    key="key",
)

⚙️ Parameters

key: str — The key of the custom attribute definition to delete.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.custom_attribute_definitions.batch_upsert(...)

📝 Description

Creates or updates custom attributes for customer profiles as a bulk operation.

Use this endpoint to set the value of one or more custom attributes for one or more customer profiles. A custom attribute is based on a custom attribute definition in a Square seller account, which is created using the CreateCustomerCustomAttributeDefinition endpoint.

This BulkUpsertCustomerCustomAttributes endpoint accepts a map of 1 to 25 individual upsert requests and returns a map of individual upsert responses. Each upsert request has a unique ID and provides a customer ID and custom attribute. Each upsert response is returned with the ID of the corresponding request.

To create or update a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.custom_attribute_definitions.batch_upsert(
    values={
        "id1": {
            "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8",
            "custom_attribute": {"key": "favoritemovie", "value": "Dune"},
        },
        "id2": {
            "customer_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM",
            "custom_attribute": {"key": "ownsmovie", "value": False},
        },
        "id3": {
            "customer_id": "SY8EMWRNDN3TQDP2H4KS1QWMMM",
            "custom_attribute": {"key": "favoritemovie", "value": "Star Wars"},
        },
        "id4": {
            "customer_id": "N3NCVYY3WS27HF0HKANA3R9FP8",
            "custom_attribute": {
                "key": "square:a0f1505a-2aa1-490d-91a8-8d31ff181808",
                "value": "10.5",
            },
        },
        "id5": {
            "customer_id": "70548QG1HN43B05G0KCZ4MMC1G",
            "custom_attribute": {
                "key": "sq0ids-0evKIskIGaY45fCyNL66aw:backupemail",
                "value": "fake-email@squareup.com",
            },
        },
    },
)

⚙️ Parameters

values: typing.Dict[ str, BatchUpsertCustomerCustomAttributesRequestCustomerCustomAttributeUpsertRequestParams, ]

A map containing 1 to 25 individual upsert requests. For each request, provide an arbitrary ID that is unique for this BulkUpsertCustomerCustomAttributes request and the information needed to create or update a custom attribute.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Customers Groups

client.customers.groups.list(...)

📝 Description

Retrieves the list of customer groups of a business.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.customers.groups.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

cursor: typing.Optional[str]

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: typing.Optional[int]

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 limit is less than 1 or greater than 50, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 50.

For more information, see Pagination.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.groups.create(...)

📝 Description

Creates a new customer group for a business.

The request must include the name value of the group.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.groups.create(
    group={"name": "Loyal Customers"},
)

⚙️ Parameters

group: CustomerGroupParams — The customer group to create.

idempotency_key: typing.Optional[str] — The idempotency key for the request. For more information, see Idempotency.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.groups.get(...)

📝 Description

Retrieves a specific customer group as identified by the group_id value.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.groups.get(
    group_id="group_id",
)

⚙️ Parameters

group_id: str — The ID of the customer group to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.groups.update(...)

📝 Description

Updates a customer group as identified by the group_id value.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.groups.update(
    group_id="group_id",
    group={"name": "Loyal Customers"},
)

⚙️ Parameters

group_id: str — The ID of the customer group to update.

group: CustomerGroupParams — The CustomerGroup object including all the updates you want to make.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.groups.delete(...)

📝 Description

Deletes a customer group as identified by the group_id value.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.groups.delete(
    group_id="group_id",
)

⚙️ Parameters

group_id: str — The ID of the customer group to delete.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.groups.add(...)

📝 Description

Adds a group membership to a customer.

The customer is identified by the customer_id value and the customer group is identified by the group_id value.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.groups.add(
    customer_id="customer_id",
    group_id="group_id",
)

⚙️ Parameters

customer_id: str — The ID of the customer to add to a group.

group_id: str — The ID of the customer group to add the customer to.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.groups.remove(...)

📝 Description

Removes a group membership from a customer.

The customer is identified by the customer_id value and the customer group is identified by the group_id value.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.groups.remove(
    customer_id="customer_id",
    group_id="group_id",
)

⚙️ Parameters

customer_id: str — The ID of the customer to remove from the group.

group_id: str — The ID of the customer group to remove the customer from.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Customers Segments

client.customers.segments.list(...)

📝 Description

Retrieves the list of customer segments of a business.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.customers.segments.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

cursor: typing.Optional[str]

A pagination cursor returned by previous calls to ListCustomerSegments. This cursor is used to retrieve the next set of query results.

For more information, see Pagination.

limit: typing.Optional[int]

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 50, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 50.

For more information, see Pagination.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.segments.get(...)

📝 Description

Retrieves a specific customer segment as identified by the segment_id value.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.segments.get(
    segment_id="segment_id",
)

⚙️ Parameters

segment_id: str — The Square-issued ID of the customer segment.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Customers Cards

client.customers.cards.create(...)

📝 Description

Adds a card on file to an existing customer.

As with charges, calls to CreateCustomerCard are idempotent. Multiple calls with the same card nonce return the same card record that was created with the provided nonce during the first call.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.cards.create(
    customer_id="customer_id",
    card_nonce="YOUR_CARD_NONCE",
    billing_address={
        "address_line1": "500 Electric Ave",
        "address_line2": "Suite 600",
        "locality": "New York",
        "administrative_district_level1": "NY",
        "postal_code": "10003",
        "country": "US",
    },
    cardholder_name="Amelia Earhart",
)

⚙️ Parameters

customer_id: str — The Square ID of the customer profile the card is linked to.

card_nonce: str

A card nonce representing the credit card to link to the customer.

Card nonces are generated by the Square payment form when customers enter their card information. For more information, see Walkthrough: Integrate Square Payments in a Website.

NOTE: Card nonces generated by digital wallets (such as Apple Pay) cannot be used to create a customer card.

billing_address: typing.Optional[AddressParams]

Address information for the card on file.

NOTE: If a billing address is provided in the request, the CreateCustomerCardRequest.billing_address.postal_code must match the postal code encoded in the card nonce.

cardholder_name: typing.Optional[str] — The full name printed on the credit card.

verification_token: typing.Optional[str]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.cards.delete(...)

📝 Description

Removes a card on file from a customer.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.cards.delete(
    customer_id="customer_id",
    card_id="card_id",
)

⚙️ Parameters

customer_id: str — The ID of the customer that the card on file belongs to.

card_id: str — The ID of the card on file to delete.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Customers CustomAttributes

client.customers.custom_attributes.list(...)

📝 Description

Lists the custom attributes associated with a customer profile.

You can use the with_definitions query parameter to also retrieve custom attribute definitions in the same call.

When all response pages are retrieved, the results include all custom attributes that are visible to the requesting application, including those that are owned by other applications and set to VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.customers.custom_attributes.list(
    customer_id="customer_id",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

customer_id: str — The ID of the target customer profile.

limit: typing.Optional[int]

The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.

cursor: typing.Optional[str]

The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.

with_definitions: typing.Optional[bool]

Indicates whether to return the custom attribute definition in the definition field of each custom attribute. Set this parameter to true to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is false.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.custom_attributes.get(...)

📝 Description

Retrieves a custom attribute associated with a customer profile.

You can use the with_definition query parameter to also retrieve the custom attribute definition in the same call.

To retrieve a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.custom_attributes.get(
    customer_id="customer_id",
    key="key",
)

⚙️ Parameters

customer_id: str — The ID of the target customer profile.

key: str

The key of the custom attribute to retrieve. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.

with_definition: typing.Optional[bool]

Indicates whether to return the custom attribute definition in the definition field of the custom attribute. Set this parameter to true to get the name and description of the custom attribute, information about the data type, or other definition details. The default value is false.

version: typing.Optional[int]

The current version of the custom attribute, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.custom_attributes.upsert(...)

📝 Description

Creates or updates a custom attribute for a customer profile.

Use this endpoint to set the value of a custom attribute for a specified customer profile. A custom attribute is based on a custom attribute definition in a Square seller account, which is created using the CreateCustomerCustomAttributeDefinition endpoint.

To create or update a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.custom_attributes.upsert(
    customer_id="customer_id",
    key="key",
    custom_attribute={"value": "Dune"},
)

⚙️ Parameters

customer_id: str — The ID of the target customer profile.

key: str

The key of the custom attribute to create or update. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.

custom_attribute: CustomAttributeParams

The custom attribute to create or update, with the following fields:

  • value. This value must conform to the schema specified by the definition. For more information, see Value data types.

  • version. To enable optimistic concurrency control for an update operation, include this optional field and specify the current version of the custom attribute.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.customers.custom_attributes.delete(...)

📝 Description

Deletes a custom attribute associated with a customer profile.

To delete a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.customers.custom_attributes.delete(
    customer_id="customer_id",
    key="key",
)

⚙️ Parameters

customer_id: str — The ID of the target customer profile.

key: str

The key of the custom attribute to delete. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Devices Codes

client.devices.codes.list(...)

📝 Description

Lists all DeviceCodes associated with the merchant.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.devices.codes.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

cursor: typing.Optional[str]

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 Paginating results for more information.

location_id: typing.Optional[str]

If specified, only returns DeviceCodes of the specified location. Returns DeviceCodes of all locations if empty.

product_type: typing.Optional[ProductType]

If specified, only returns DeviceCodes targeting the specified product type. Returns DeviceCodes of all product types if empty.

status: typing.Optional[DeviceCodeStatus]

If specified, returns DeviceCodes with the specified statuses. Returns DeviceCodes of status PAIRED and UNPAIRED if empty.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.devices.codes.create(...)

📝 Description

Creates a DeviceCode that can be used to login to a Square Terminal device to enter the connected terminal mode.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.devices.codes.create(
    idempotency_key="01bb00a6-0c86-4770-94ed-f5fca973cd56",
    device_code={
        "name": "Counter 1",
        "product_type": "TERMINAL_API",
        "location_id": "B5E4484SHHNYH",
    },
)

⚙️ Parameters

idempotency_key: str

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

See Idempotency keys for more information.

device_code: DeviceCodeParams — The device code to create.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.devices.codes.get(...)

📝 Description

Retrieves DeviceCode with the associated ID.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.devices.codes.get(
    id="id",
)

⚙️ Parameters

id: str — The unique identifier for the device code.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Disputes Evidence

client.disputes.evidence.list(...)

📝 Description

Returns a list of evidence associated with a dispute.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.disputes.evidence.list(
    dispute_id="dispute_id",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

dispute_id: str — The ID of the dispute.

cursor: typing.Optional[str]

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.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.disputes.evidence.get(...)

📝 Description

Returns the metadata for the evidence specified in the request URL path.

You must maintain a copy of any evidence uploaded if you want to reference it later. Evidence cannot be downloaded after you upload it.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.disputes.evidence.get(
    dispute_id="dispute_id",
    evidence_id="evidence_id",
)

⚙️ Parameters

dispute_id: str — The ID of the dispute from which you want to retrieve evidence metadata.

evidence_id: str — The ID of the evidence to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.disputes.evidence.delete(...)

📝 Description

Removes specified evidence from a dispute. Square does not send the bank any evidence that is removed.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.disputes.evidence.delete(
    dispute_id="dispute_id",
    evidence_id="evidence_id",
)

⚙️ Parameters

dispute_id: str — The ID of the dispute from which you want to remove evidence.

evidence_id: str — The ID of the evidence you want to remove.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

GiftCards Activities

client.gift_cards.activities.list(...)

📝 Description

Lists gift card activities. By default, you get gift card activities for all gift cards in the seller's account. You can optionally specify query parameters to filter the list. For example, you can get a list of gift card activities for a gift card, for all gift cards in a specific region, or for activities within a time window.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.gift_cards.activities.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

gift_card_id: typing.Optional[str]

If a gift card ID is provided, the endpoint returns activities related to the specified gift card. Otherwise, the endpoint returns all gift card activities for the seller.

type: typing.Optional[str]

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

location_id: typing.Optional[str]

If a location ID is provided, the endpoint returns gift card activities for the specified location. Otherwise, the endpoint returns gift card activities for all locations.

begin_time: typing.Optional[str]

The timestamp for the beginning of the reporting period, in RFC 3339 format. This start time is inclusive. The default value is the current time minus one year.

end_time: typing.Optional[str]

The timestamp for the end of the reporting period, in RFC 3339 format. This end time is inclusive. The default value is the current time.

limit: typing.Optional[int]

If a limit is provided, the endpoint returns the specified number of results (or fewer) per page. The maximum value is 100. The default value is 50. For more information, see Pagination.

cursor: typing.Optional[str]

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.

sort_order: typing.Optional[str]

The order in which the endpoint returns the activities, based on created_at.

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.gift_cards.activities.create(...)

📝 Description

Creates a gift card activity to manage the balance or state of a gift card. For example, create an ACTIVATE activity to activate a gift card with an initial balance before first use.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.gift_cards.activities.create(
    idempotency_key="U16kfr-kA70er-q4Rsym-7U7NnY",
    gift_card_activity={
        "type": "ACTIVATE",
        "location_id": "81FN9BNFZTKS4",
        "gift_card_id": "gftc:6d55a72470d940c6ba09c0ab8ad08d20",
        "activate_activity_details": {
            "order_id": "jJNGHm4gLI6XkFbwtiSLqK72KkAZY",
            "line_item_uid": "eIWl7X0nMuO9Ewbh0ChIx",
        },
    },
)

⚙️ Parameters

idempotency_key: str — A unique string that identifies the CreateGiftCardActivity request.

gift_card_activity: GiftCardActivityParams

The activity to create for the gift card. This activity must specify gift_card_id or gift_card_gan for the target gift card, the location_id where the activity occurred, and the activity type along with the corresponding activity details.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Labor BreakTypes

client.labor.break_types.list(...)

📝 Description

Returns a paginated list of BreakType instances for a business.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.labor.break_types.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

location_id: typing.Optional[str]

Filter the returned BreakType results to only those that are associated with the specified location.

limit: typing.Optional[int]

The maximum number of BreakType results to return per page. The number can range between 1 and 200. The default is 200.

cursor: typing.Optional[str] — A pointer to the next page of BreakType results to fetch.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.labor.break_types.create(...)

📝 Description

Creates a new BreakType.

A BreakType is a template for creating Break objects. You must provide the following values in your request to this endpoint:

  • location_id
  • break_name
  • expected_duration
  • is_paid

You can only have three BreakType instances per location. If you attempt to add a fourth BreakType for a location, an INVALID_REQUEST_ERROR "Exceeded limit of 3 breaks per location." is returned.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.break_types.create(
    idempotency_key="PAD3NG5KSN2GL",
    break_type={
        "location_id": "CGJN03P1D08GF",
        "break_name": "Lunch Break",
        "expected_duration": "PT30M",
        "is_paid": True,
    },
)

⚙️ Parameters

break_type: BreakTypeParams — The BreakType to be created.

idempotency_key: typing.Optional[str] — A unique string value to ensure the idempotency of the operation.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.labor.break_types.get(...)

📝 Description

Returns a single BreakType specified by id.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.break_types.get(
    id="id",
)

⚙️ Parameters

id: str — The UUID for the BreakType being retrieved.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.labor.break_types.update(...)

📝 Description

Updates an existing BreakType.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.break_types.update(
    id="id",
    break_type={
        "location_id": "26M7H24AZ9N6R",
        "break_name": "Lunch",
        "expected_duration": "PT50M",
        "is_paid": True,
        "version": 1,
    },
)

⚙️ Parameters

id: str — The UUID for the BreakType being updated.

break_type: BreakTypeParams — The updated BreakType.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.labor.break_types.delete(...)

📝 Description

Deletes an existing BreakType.

A BreakType can be deleted even if it is referenced from a Shift.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.break_types.delete(
    id="id",
)

⚙️ Parameters

id: str — The UUID for the BreakType being deleted.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Labor EmployeeWages

client.labor.employee_wages.list(...)

📝 Description

Returns a paginated list of EmployeeWage instances for a business.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.labor.employee_wages.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

employee_id: typing.Optional[str] — Filter the returned wages to only those that are associated with the specified employee.

limit: typing.Optional[int]

The maximum number of EmployeeWage results to return per page. The number can range between 1 and 200. The default is 200.

cursor: typing.Optional[str] — A pointer to the next page of EmployeeWage results to fetch.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.labor.employee_wages.get(...)

📝 Description

Returns a single EmployeeWage specified by id.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.employee_wages.get(
    id="id",
)

⚙️ Parameters

id: str — The UUID for the EmployeeWage being retrieved.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Labor Shifts

client.labor.shifts.create(...)

📝 Description

Creates a new Shift.

A Shift 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 Shift can result in a BAD_REQUEST error when:

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.shifts.create(
    idempotency_key="HIDSNG5KS478L",
    shift={
        "location_id": "PAA1RJZZKXBFG",
        "start_at": "2019-01-25T03:11:00-05:00",
        "end_at": "2019-01-25T13:11:00-05:00",
        "wage": {
            "title": "Barista",
            "hourly_rate": {"amount": 1100, "currency": "USD"},
            "tip_eligible": True,
        },
        "breaks": [
            {
                "start_at": "2019-01-25T06:11:00-05:00",
                "end_at": "2019-01-25T06:16:00-05:00",
                "break_type_id": "REGS1EQR1TPZ5",
                "name": "Tea Break",
                "expected_duration": "PT5M",
                "is_paid": True,
            }
        ],
        "team_member_id": "ormj0jJJZ5OZIzxrZYJI",
        "declared_cash_tip_money": {"amount": 500, "currency": "USD"},
    },
)

⚙️ Parameters

shift: ShiftParams — The Shift to be created.

idempotency_key: typing.Optional[str] — A unique string value to ensure the idempotency of the operation.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.labor.shifts.search(...)

📝 Description

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

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

The list can be sorted by:

  • START_AT
  • END_AT
  • CREATED_AT
  • UPDATED_AT

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.shifts.search(
    query={
        "filter": {
            "workday": {
                "date_range": {
                    "start_date": "2019-01-20",
                    "end_date": "2019-02-03",
                },
                "match_shifts_by": "START_AT",
                "default_timezone": "America/Los_Angeles",
            }
        }
    },
    limit=100,
)

⚙️ Parameters

query: typing.Optional[ShiftQueryParams] — Query filters.

limit: typing.Optional[int] — The number of resources in a page (200 by default).

cursor: typing.Optional[str] — An opaque cursor for fetching the next page.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.labor.shifts.get(...)

📝 Description

Returns a single Shift specified by id.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.shifts.get(
    id="id",
)

⚙️ Parameters

id: str — The UUID for the Shift being retrieved.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.labor.shifts.update(...)

📝 Description

Updates an existing Shift.

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

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

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.shifts.update(
    id="id",
    shift={
        "location_id": "PAA1RJZZKXBFG",
        "start_at": "2019-01-25T03:11:00-05:00",
        "end_at": "2019-01-25T13:11:00-05:00",
        "wage": {
            "title": "Bartender",
            "hourly_rate": {"amount": 1500, "currency": "USD"},
            "tip_eligible": True,
        },
        "breaks": [
            {
                "id": "X7GAQYVVRRG6P",
                "start_at": "2019-01-25T06:11:00-05:00",
                "end_at": "2019-01-25T06:16:00-05:00",
                "break_type_id": "REGS1EQR1TPZ5",
                "name": "Tea Break",
                "expected_duration": "PT5M",
                "is_paid": True,
            }
        ],
        "version": 1,
        "team_member_id": "ormj0jJJZ5OZIzxrZYJI",
        "declared_cash_tip_money": {"amount": 500, "currency": "USD"},
    },
)

⚙️ Parameters

id: str — The ID of the object being updated.

shift: ShiftParams — The updated Shift object.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.labor.shifts.delete(...)

📝 Description

Deletes a Shift.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.shifts.delete(
    id="id",
)

⚙️ Parameters

id: str — The UUID for the Shift being deleted.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Labor TeamMemberWages

client.labor.team_member_wages.list(...)

📝 Description

Returns a paginated list of TeamMemberWage instances for a business.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.labor.team_member_wages.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

team_member_id: typing.Optional[str]

Filter the returned wages to only those that are associated with the specified team member.

limit: typing.Optional[int]

The maximum number of TeamMemberWage results to return per page. The number can range between 1 and 200. The default is 200.

cursor: typing.Optional[str] — A pointer to the next page of EmployeeWage results to fetch.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.labor.team_member_wages.get(...)

📝 Description

Returns a single TeamMemberWage specified by id.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.team_member_wages.get(
    id="id",
)

⚙️ Parameters

id: str — The UUID for the TeamMemberWage being retrieved.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Labor WorkweekConfigs

client.labor.workweek_configs.list(...)

📝 Description

Returns a list of WorkweekConfig instances for a business.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.labor.workweek_configs.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

limit: typing.Optional[int] — The maximum number of WorkweekConfigs results to return per page.

cursor: typing.Optional[str] — A pointer to the next page of WorkweekConfig results to fetch.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.labor.workweek_configs.get(...)

📝 Description

Updates a WorkweekConfig.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.labor.workweek_configs.get(
    id="id",
    workweek_config={
        "start_of_week": "MON",
        "start_of_day_local_time": "10:00",
        "version": 10,
    },
)

⚙️ Parameters

id: str — The UUID for the WorkweekConfig object being updated.

workweek_config: WorkweekConfigParams — The updated WorkweekConfig object.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Locations CustomAttributeDefinitions

client.locations.custom_attribute_definitions.list(...)

📝 Description

Lists the location-related custom attribute definitions that belong to a Square seller account. When all response pages are retrieved, the results include all custom attribute definitions that are visible to the requesting application, including those that are created by other applications and set to VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.locations.custom_attribute_definitions.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

visibility_filter: typing.Optional[VisibilityFilter] — Filters the CustomAttributeDefinition results by their visibility values.

limit: typing.Optional[int]

The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.

cursor: typing.Optional[str]

The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.custom_attribute_definitions.create(...)

📝 Description

Creates a location-related custom attribute definition for a Square seller account. Use this endpoint to define a custom attribute that can be associated with locations. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute. After the definition is created, you can call UpsertLocationCustomAttribute or BulkUpsertLocationCustomAttributes to set the custom attribute for locations.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.custom_attribute_definitions.create(
    custom_attribute_definition={
        "key": "bestseller",
        "schema": {
            "ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
        },
        "name": "Bestseller",
        "description": "Bestselling item at location",
        "visibility": "VISIBILITY_READ_WRITE_VALUES",
    },
)

⚙️ Parameters

custom_attribute_definition: CustomAttributeDefinitionParams

The custom attribute definition to create. Note the following:

  • With the exception of the Selection data type, the schema is specified as a simple URL to the JSON schema definition hosted on the Square CDN. For more information, including supported values and constraints, see Supported data types.
  • name is required unless visibility is set to VISIBILITY_HIDDEN.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.custom_attribute_definitions.get(...)

📝 Description

Retrieves a location-related custom attribute definition from a Square seller account. To retrieve a custom attribute definition created by another application, the visibility setting must be VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.custom_attribute_definitions.get(
    key="key",
)

⚙️ Parameters

key: str

The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.

version: typing.Optional[int]

The current version of the custom attribute definition, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.custom_attribute_definitions.update(...)

📝 Description

Updates a location-related custom attribute definition for a Square seller account. Use this endpoint to update the following fields: name, description, visibility, or the schema for a Selection data type. Only the definition owner can update a custom attribute definition.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.custom_attribute_definitions.update(
    key="key",
    custom_attribute_definition={
        "description": "Update the description as desired.",
        "visibility": "VISIBILITY_READ_ONLY",
    },
)

⚙️ Parameters

key: str — The key of the custom attribute definition to update.

custom_attribute_definition: CustomAttributeDefinitionParams

The custom attribute definition that contains the fields to update. This endpoint supports sparse updates, so only new or changed fields need to be included in the request. Only the following fields can be updated:

  • name
  • description
  • visibility
  • schema for a Selection data type. Only changes to the named options or the maximum number of allowed selections are supported.

For more information, see Update a location custom attribute definition. To enable optimistic concurrency control, specify the current version of the custom attribute definition. If this is not important for your application, version can be set to -1.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.custom_attribute_definitions.delete(...)

📝 Description

Deletes a location-related custom attribute definition from a Square seller account. Deleting a custom attribute definition also deletes the corresponding custom attribute from all locations. Only the definition owner can delete a custom attribute definition.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.custom_attribute_definitions.delete(
    key="key",
)

⚙️ Parameters

key: str — The key of the custom attribute definition to delete.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Locations CustomAttributes

client.locations.custom_attributes.batch_delete(...)

📝 Description

Deletes custom attributes for locations as a bulk operation. To delete a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.custom_attributes.batch_delete(
    values={
        "id1": {"key": "bestseller"},
        "id2": {"key": "bestseller"},
        "id3": {"key": "phone-number"},
    },
)

⚙️ Parameters

values: typing.Dict[ str, BulkDeleteLocationCustomAttributesRequestLocationCustomAttributeDeleteRequestParams, ]

The data used to update the CustomAttribute objects. The keys must be unique and are used to map to the corresponding response.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.custom_attributes.batch_upsert(...)

📝 Description

Creates or updates custom attributes for locations as a bulk operation. Use this endpoint to set the value of one or more custom attributes for one or more locations. A custom attribute is based on a custom attribute definition in a Square seller account, which is created using the CreateLocationCustomAttributeDefinition endpoint. This BulkUpsertLocationCustomAttributes endpoint accepts a map of 1 to 25 individual upsert requests and returns a map of individual upsert responses. Each upsert request has a unique ID and provides a location ID and custom attribute. Each upsert response is returned with the ID of the corresponding request. To create or update a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.custom_attributes.batch_upsert(
    values={
        "id1": {
            "location_id": "L0TBCBTB7P8RQ",
            "custom_attribute": {"key": "bestseller", "value": "hot cocoa"},
        },
        "id2": {
            "location_id": "L9XMD04V3STJX",
            "custom_attribute": {
                "key": "bestseller",
                "value": "berry smoothie",
            },
        },
        "id3": {
            "location_id": "L0TBCBTB7P8RQ",
            "custom_attribute": {
                "key": "phone-number",
                "value": "+12223334444",
            },
        },
    },
)

⚙️ Parameters

values: typing.Dict[ str, BulkUpsertLocationCustomAttributesRequestLocationCustomAttributeUpsertRequestParams, ]

A map containing 1 to 25 individual upsert requests. For each request, provide an arbitrary ID that is unique for this BulkUpsertLocationCustomAttributes request and the information needed to create or update a custom attribute.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.custom_attributes.list(...)

📝 Description

Lists the custom attributes associated with a location. You can use the with_definitions query parameter to also retrieve custom attribute definitions in the same call. When all response pages are retrieved, the results include all custom attributes that are visible to the requesting application, including those that are owned by other applications and set to VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.locations.custom_attributes.list(
    location_id="location_id",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

location_id: str — The ID of the target location.

visibility_filter: typing.Optional[VisibilityFilter] — Filters the CustomAttributeDefinition results by their visibility values.

limit: typing.Optional[int]

The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.

cursor: typing.Optional[str]

The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.

with_definitions: typing.Optional[bool]

Indicates whether to return the custom attribute definition in the definition field of each custom attribute. Set this parameter to true to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is false.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.custom_attributes.get(...)

📝 Description

Retrieves a custom attribute associated with a location. You can use the with_definition query parameter to also retrieve the custom attribute definition in the same call. To retrieve a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.custom_attributes.get(
    location_id="location_id",
    key="key",
)

⚙️ Parameters

location_id: str — The ID of the target location.

key: str

The key of the custom attribute to retrieve. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.

with_definition: typing.Optional[bool]

Indicates whether to return the custom attribute definition in the definition field of the custom attribute. Set this parameter to true to get the name and description of the custom attribute, information about the data type, or other definition details. The default value is false.

version: typing.Optional[int]

The current version of the custom attribute, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.custom_attributes.upsert(...)

📝 Description

Creates or updates a custom attribute for a location. Use this endpoint to set the value of a custom attribute for a specified location. A custom attribute is based on a custom attribute definition in a Square seller account, which is created using the CreateLocationCustomAttributeDefinition endpoint. To create or update a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.custom_attributes.upsert(
    location_id="location_id",
    key="key",
    custom_attribute={"value": "hot cocoa"},
)

⚙️ Parameters

location_id: str — The ID of the target location.

key: str

The key of the custom attribute to create or update. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.

custom_attribute: CustomAttributeParams

The custom attribute to create or update, with the following fields:

  • value. This value must conform to the schema specified by the definition. For more information, see Supported data types.
  • version. To enable optimistic concurrency control for an update operation, include the current version of the custom attribute. If this is not important for your application, version can be set to -1.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.custom_attributes.delete(...)

📝 Description

Deletes a custom attribute associated with a location. To delete a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.custom_attributes.delete(
    location_id="location_id",
    key="key",
)

⚙️ Parameters

location_id: str — The ID of the target location.

key: str

The key of the custom attribute to delete. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Locations Transactions

client.locations.transactions.list(...)

📝 Description

Lists transactions for a particular location.

Transactions include payment information from sales and exchanges and refund information from returns and exchanges.

Max results per page: 50

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.transactions.list(
    location_id="location_id",
)

⚙️ Parameters

location_id: str — The ID of the location to list transactions for.

begin_time: typing.Optional[str]

The beginning of the requested reporting period, in RFC 3339 format.

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time minus one year.

end_time: typing.Optional[str]

The end of the requested reporting period, in RFC 3339 format.

See Date ranges for details on date inclusivity/exclusivity.

Default value: The current time.

sort_order: typing.Optional[SortOrder]

The order in which results are listed in the response (ASC for oldest first, DESC for newest first).

Default value: DESC

cursor: typing.Optional[str]

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 Paginating results for more information.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.transactions.get(...)

📝 Description

Retrieves details for a single transaction.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.transactions.get(
    location_id="location_id",
    transaction_id="transaction_id",
)

⚙️ Parameters

location_id: str — The ID of the transaction's associated location.

transaction_id: str — The ID of the transaction to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.transactions.capture(...)

📝 Description

Captures a transaction that was created with the Charge endpoint with a delay_capture value of true.

See Delayed capture transactions for more information.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.transactions.capture(
    location_id="location_id",
    transaction_id="transaction_id",
)

⚙️ Parameters

location_id: str

transaction_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.locations.transactions.void(...)

📝 Description

Cancels a transaction that was created with the Charge endpoint with a delay_capture value of true.

See Delayed capture transactions for more information.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.locations.transactions.void(
    location_id="location_id",
    transaction_id="transaction_id",
)

⚙️ Parameters

location_id: str

transaction_id: str

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Loyalty Accounts

client.loyalty.accounts.create(...)

📝 Description

Creates a loyalty account. To create a loyalty account, you must provide the program_id and a mapping with the phone_number of the buyer.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.accounts.create(
    loyalty_account={
        "program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd",
        "mapping": {"phone_number": "+14155551234"},
    },
    idempotency_key="ec78c477-b1c3-4899-a209-a4e71337c996",
)

⚙️ Parameters

loyalty_account: LoyaltyAccountParams — The loyalty account to create.

idempotency_key: str

A unique string that identifies this CreateLoyaltyAccount request. Keys can be any valid string, but must be unique for every request.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.loyalty.accounts.search(...)

📝 Description

Searches for loyalty accounts in a loyalty program.

You can search for a loyalty account using the phone number or customer ID associated with the account. To return all loyalty accounts, specify an empty query object or omit it entirely.

Search results are sorted by created_at in ascending order.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.accounts.search(
    query={"mappings": [{"phone_number": "+14155551234"}]},
    limit=10,
)

⚙️ Parameters

query: typing.Optional[SearchLoyaltyAccountsRequestLoyaltyAccountQueryParams] — The search criteria for the request.

limit: typing.Optional[int] — The maximum number of results to include in the response. The default value is 30.

cursor: typing.Optional[str]

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

For more information, see Pagination.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.loyalty.accounts.get(...)

📝 Description

Retrieves a loyalty account.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.accounts.get(
    account_id="account_id",
)

⚙️ Parameters

account_id: str — The ID of the loyalty account to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.loyalty.accounts.accumulate_points(...)

📝 Description

Adds points earned from a purchase to a loyalty account.

  • If you are using the Orders API to manage orders, provide the order_id. Square reads the order to compute the points earned from both the base loyalty program and an associated loyalty promotion. For purchases that qualify for multiple accrual rules, Square computes points based on the accrual rule that grants the most points. For purchases that qualify for multiple promotions, Square computes points based on the most recently created promotion. A purchase must first qualify for program points to be eligible for promotion points.

  • If you are not using the Orders API to manage orders, provide points with the number of points to add. You must first perform a client-side computation of the points earned from the loyalty program and loyalty promotion. For spend-based and visit-based programs, you can call CalculateLoyaltyPoints to compute the points earned from the base loyalty program. For information about computing points earned from a loyalty promotion, see Calculating promotion points.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.accounts.accumulate_points(
    account_id="account_id",
    accumulate_points={"order_id": "RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY"},
    idempotency_key="58b90739-c3e8-4b11-85f7-e636d48d72cb",
    location_id="P034NEENMD09F",
)

⚙️ Parameters

account_id: str — The ID of the target loyalty account.

accumulate_points: LoyaltyEventAccumulatePointsParams

The points to add to the account. If you are using the Orders API to manage orders, specify the order ID. Otherwise, specify the points to add.

idempotency_key: str

A unique string that identifies the AccumulateLoyaltyPoints request. Keys can be any valid string but must be unique for every request.

location_id: str — The location where the purchase was made.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.loyalty.accounts.adjust(...)

📝 Description

Adds points to or subtracts points from a buyer's account.

Use this endpoint only when you need to manually adjust points. Otherwise, in your application flow, you call AccumulateLoyaltyPoints to add points when a buyer pays for the purchase.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.accounts.adjust(
    account_id="account_id",
    idempotency_key="bc29a517-3dc9-450e-aa76-fae39ee849d1",
    adjust_points={"points": 10, "reason": "Complimentary points"},
)

⚙️ Parameters

account_id: str — The ID of the target loyalty account.

idempotency_key: str

A unique string that identifies this AdjustLoyaltyPoints request. Keys can be any valid string, but must be unique for every request.

adjust_points: LoyaltyEventAdjustPointsParams

The points to add or subtract and the reason for the adjustment. To add points, specify a positive integer. To subtract points, specify a negative integer.

allow_negative_balance: typing.Optional[bool]

Indicates whether to allow a negative adjustment to result in a negative balance. If true, a negative balance is allowed when subtracting points. If false, Square returns a BAD_REQUEST error when subtracting the specified number of points would result in a negative balance. The default value is false.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Loyalty Programs

client.loyalty.programs.list()

📝 Description

Returns a list of loyalty programs in the seller's account. Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see Loyalty Program Overview.

Replaced with RetrieveLoyaltyProgram when used with the keyword main.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.programs.list()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.loyalty.programs.get(...)

📝 Description

Retrieves the loyalty program in a seller's account, specified by the program ID or the keyword main.

Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see Loyalty Program Overview.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.programs.get(
    program_id="program_id",
)

⚙️ Parameters

program_id: str — The ID of the loyalty program or the keyword main. Either value can be used to retrieve the single loyalty program that belongs to the seller.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.loyalty.programs.calculate(...)

📝 Description

Calculates the number of points a buyer can earn from a purchase. Applications might call this endpoint to display the points to the buyer.

  • If you are using the Orders API to manage orders, provide the order_id and (optional) loyalty_account_id. Square reads the order to compute the points earned from the base loyalty program and an associated loyalty promotion.

  • If you are not using the Orders API to manage orders, provide transaction_amount_money with the purchase amount. Square uses this amount to calculate the points earned from the base loyalty program, but not points earned from a loyalty promotion. For spend-based and visit-based programs, the tax_mode setting of the accrual rule indicates how taxes should be treated for loyalty points accrual. If the purchase qualifies for program points, call ListLoyaltyPromotions and perform a client-side computation to calculate whether the purchase also qualifies for promotion points. For more information, see Calculating promotion points.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.programs.calculate(
    program_id="program_id",
    order_id="RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY",
    loyalty_account_id="79b807d2-d786-46a9-933b-918028d7a8c5",
)

⚙️ Parameters

program_id: str — The ID of the loyalty program, which defines the rules for accruing points.

order_id: typing.Optional[str]

The order ID for which to calculate the points. Specify this field if your application uses the Orders API to process orders. Otherwise, specify the transaction_amount_money.

transaction_amount_money: typing.Optional[MoneyParams]

The purchase amount for which to calculate the points. Specify this field if your application does not use the Orders API to process orders. Otherwise, specify the order_id.

loyalty_account_id: typing.Optional[str]

The ID of the target loyalty account. Optionally specify this field if your application uses the Orders API to process orders.

If specified, the promotion_points field in the response shows the number of points the buyer would earn from the purchase. In this case, Square uses the account ID to determine whether the promotion's trigger_limit (the maximum number of times that a buyer can trigger the promotion) has been reached. If not specified, the promotion_points field shows the number of points the purchase qualifies for regardless of the trigger limit.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Loyalty Rewards

client.loyalty.rewards.create(...)

📝 Description

Creates a loyalty reward. In the process, the endpoint does following:

  • Uses the reward_tier_id in the request to determine the number of points to lock for this reward.
  • If the request includes order_id, it adds the reward and related discount to the order.

After a reward is created, the points are locked and not available for the buyer to redeem another reward.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.rewards.create(
    reward={
        "loyalty_account_id": "5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd",
        "reward_tier_id": "e1b39225-9da5-43d1-a5db-782cdd8ad94f",
        "order_id": "RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY",
    },
    idempotency_key="18c2e5ea-a620-4b1f-ad60-7b167285e451",
)

⚙️ Parameters

reward: LoyaltyRewardParams — The reward to create.

idempotency_key: str

A unique string that identifies this CreateLoyaltyReward request. Keys can be any valid string, but must be unique for every request.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.loyalty.rewards.search(...)

📝 Description

Searches for loyalty rewards. This endpoint accepts a request with no query filters and returns results for all loyalty accounts. If you include a query object, loyalty_account_id is required and status is optional.

If you know a reward ID, use the RetrieveLoyaltyReward endpoint.

Search results are sorted by updated_at in descending order.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.rewards.search(
    query={"loyalty_account_id": "5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd"},
    limit=10,
)

⚙️ Parameters

query: typing.Optional[SearchLoyaltyRewardsRequestLoyaltyRewardQueryParams]

The search criteria for the request. If empty, the endpoint retrieves all loyalty rewards in the loyalty program.

limit: typing.Optional[int] — The maximum number of results to return in the response. The default value is 30.

cursor: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.loyalty.rewards.get(...)

📝 Description

Retrieves a loyalty reward.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.rewards.get(
    reward_id="reward_id",
)

⚙️ Parameters

reward_id: str — The ID of the loyalty reward to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.loyalty.rewards.delete(...)

📝 Description

Deletes a loyalty reward by doing the following:

  • Returns the loyalty points back to the loyalty account.
  • If an order ID was specified when the reward was created (see CreateLoyaltyReward), it updates the order by removing the reward and related discounts.

You cannot delete a reward that has reached the terminal state (REDEEMED).

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.rewards.delete(
    reward_id="reward_id",
)

⚙️ Parameters

reward_id: str — The ID of the loyalty reward to delete.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.loyalty.rewards.redeem(...)

📝 Description

Redeems a loyalty reward.

The endpoint sets the reward to the REDEEMED terminal state.

If you are using your own order processing system (not using the Orders API), you call this endpoint after the buyer paid for the purchase.

After the reward reaches the terminal state, it cannot be deleted. In other words, points used for the reward cannot be returned to the account.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.rewards.redeem(
    reward_id="reward_id",
    idempotency_key="98adc7f7-6963-473b-b29c-f3c9cdd7d994",
    location_id="P034NEENMD09F",
)

⚙️ Parameters

reward_id: str — The ID of the loyalty reward to redeem.

idempotency_key: str

A unique string that identifies this RedeemLoyaltyReward request. Keys can be any valid string, but must be unique for every request.

location_id: str — The ID of the location where the reward is redeemed.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Loyalty Programs Promotions

client.loyalty.programs.promotions.list(...)

📝 Description

Lists the loyalty promotions associated with a loyalty program. Results are sorted by the created_at date in descending order (newest to oldest).

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.loyalty.programs.promotions.list(
    program_id="program_id",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

program_id: str

The ID of the base loyalty program. To get the program ID, call RetrieveLoyaltyProgram using the main keyword.

status: typing.Optional[LoyaltyPromotionStatus]

The status to filter the results by. If a status is provided, only loyalty promotions with the specified status are returned. Otherwise, all loyalty promotions associated with the loyalty program are returned.

cursor: typing.Optional[str]

The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.

limit: typing.Optional[int]

The maximum number of results to return in a single paged response. The minimum value is 1 and the maximum value is 30. The default value is 30. For more information, see Pagination.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.loyalty.programs.promotions.create(...)

📝 Description

Creates a loyalty promotion for a loyalty program. A loyalty promotion enables buyers to earn points in addition to those earned from the base loyalty program.

This endpoint sets the loyalty promotion to the ACTIVE or SCHEDULED status, depending on the available_time setting. A loyalty program can have a maximum of 10 loyalty promotions with an ACTIVE or SCHEDULED status.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.programs.promotions.create(
    program_id="program_id",
    loyalty_promotion={
        "name": "Tuesday Happy Hour Promo",
        "incentive": {
            "type": "POINTS_MULTIPLIER",
            "points_multiplier_data": {"multiplier": "3.0"},
        },
        "available_time": {
            "time_periods": [
                "BEGIN:VEVENT\nDTSTART:20220816T160000\nDURATION:PT2H\nRRULE:FREQ=WEEKLY;BYDAY=TU\nEND:VEVENT"
            ]
        },
        "trigger_limit": {"times": 1, "interval": "DAY"},
        "minimum_spend_amount_money": {"amount": 2000, "currency": "USD"},
        "qualifying_category_ids": ["XTQPYLR3IIU9C44VRCB3XD12"],
    },
    idempotency_key="ec78c477-b1c3-4899-a209-a4e71337c996",
)

⚙️ Parameters

program_id: str

The ID of the loyalty program to associate with the promotion. To get the program ID, call RetrieveLoyaltyProgram using the main keyword.

loyalty_promotion: LoyaltyPromotionParams — The loyalty promotion to create.

idempotency_key: str

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.loyalty.programs.promotions.get(...)

📝 Description

Retrieves a loyalty promotion.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.programs.promotions.get(
    promotion_id="promotion_id",
    program_id="program_id",
)

⚙️ Parameters

promotion_id: str — The ID of the loyalty promotion to retrieve.

program_id: str

The ID of the base loyalty program. To get the program ID, call RetrieveLoyaltyProgram using the main keyword.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.loyalty.programs.promotions.cancel(...)

📝 Description

Cancels a loyalty promotion. Use this endpoint to cancel an ACTIVE promotion earlier than the end date, cancel an ACTIVE promotion when an end date is not specified, or cancel a SCHEDULED promotion. Because updating a promotion is not supported, you can also use this endpoint to cancel a promotion before you create a new one.

This endpoint sets the loyalty promotion to the CANCELED state

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.loyalty.programs.promotions.cancel(
    promotion_id="promotion_id",
    program_id="program_id",
)

⚙️ Parameters

promotion_id: str

The ID of the loyalty promotion to cancel. You can cancel a promotion that has an ACTIVE or SCHEDULED status.

program_id: str — The ID of the base loyalty program.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Merchants CustomAttributeDefinitions

client.merchants.custom_attribute_definitions.list(...)

📝 Description

Lists the merchant-related custom attribute definitions that belong to a Square seller account. When all response pages are retrieved, the results include all custom attribute definitions that are visible to the requesting application, including those that are created by other applications and set to VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.merchants.custom_attribute_definitions.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

visibility_filter: typing.Optional[VisibilityFilter] — Filters the CustomAttributeDefinition results by their visibility values.

limit: typing.Optional[int]

The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.

cursor: typing.Optional[str]

The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.merchants.custom_attribute_definitions.create(...)

📝 Description

Creates a merchant-related custom attribute definition for a Square seller account. Use this endpoint to define a custom attribute that can be associated with a merchant connecting to your application. A custom attribute definition specifies the key, visibility, schema, and other properties for a custom attribute. After the definition is created, you can call UpsertMerchantCustomAttribute or BulkUpsertMerchantCustomAttributes to set the custom attribute for a merchant.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.merchants.custom_attribute_definitions.create(
    custom_attribute_definition={
        "key": "alternative_seller_name",
        "schema": {
            "ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.String"
        },
        "name": "Alternative Merchant Name",
        "description": "This is the other name this merchant goes by.",
        "visibility": "VISIBILITY_READ_ONLY",
    },
)

⚙️ Parameters

custom_attribute_definition: CustomAttributeDefinitionParams

The custom attribute definition to create. Note the following:

  • With the exception of the Selection data type, the schema is specified as a simple URL to the JSON schema definition hosted on the Square CDN. For more information, including supported values and constraints, see Supported data types.
  • name is required unless visibility is set to VISIBILITY_HIDDEN.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.merchants.custom_attribute_definitions.get(...)

📝 Description

Retrieves a merchant-related custom attribute definition from a Square seller account. To retrieve a custom attribute definition created by another application, the visibility setting must be VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.merchants.custom_attribute_definitions.get(
    key="key",
)

⚙️ Parameters

key: str

The key of the custom attribute definition to retrieve. If the requesting application is not the definition owner, you must use the qualified key.

version: typing.Optional[int]

The current version of the custom attribute definition, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.merchants.custom_attribute_definitions.update(...)

📝 Description

Updates a merchant-related custom attribute definition for a Square seller account. Use this endpoint to update the following fields: name, description, visibility, or the schema for a Selection data type. Only the definition owner can update a custom attribute definition.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.merchants.custom_attribute_definitions.update(
    key="key",
    custom_attribute_definition={
        "description": "Update the description as desired.",
        "visibility": "VISIBILITY_READ_ONLY",
    },
)

⚙️ Parameters

key: str — The key of the custom attribute definition to update.

custom_attribute_definition: CustomAttributeDefinitionParams

The custom attribute definition that contains the fields to update. This endpoint supports sparse updates, so only new or changed fields need to be included in the request. Only the following fields can be updated:

  • name
  • description
  • visibility
  • schema for a Selection data type. Only changes to the named options or the maximum number of allowed selections are supported. For more information, see Update a merchant custom attribute definition. The version field must match the current version of the custom attribute definition to enable optimistic concurrency If this is not important for your application, version can be set to -1. For any other values, the request fails with a BAD_REQUEST error.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.merchants.custom_attribute_definitions.delete(...)

📝 Description

Deletes a merchant-related custom attribute definition from a Square seller account. Deleting a custom attribute definition also deletes the corresponding custom attribute from the merchant. Only the definition owner can delete a custom attribute definition.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.merchants.custom_attribute_definitions.delete(
    key="key",
)

⚙️ Parameters

key: str — The key of the custom attribute definition to delete.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Merchants CustomAttributes

client.merchants.custom_attributes.batch_delete(...)

📝 Description

Deletes custom attributes for a merchant as a bulk operation. To delete a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.merchants.custom_attributes.batch_delete(
    values={
        "id1": {"key": "alternative_seller_name"},
        "id2": {"key": "has_seen_tutorial"},
    },
)

⚙️ Parameters

values: typing.Dict[ str, BulkDeleteMerchantCustomAttributesRequestMerchantCustomAttributeDeleteRequestParams, ]

The data used to update the CustomAttribute objects. The keys must be unique and are used to map to the corresponding response.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.merchants.custom_attributes.batch_upsert(...)

📝 Description

Creates or updates custom attributes for a merchant as a bulk operation. Use this endpoint to set the value of one or more custom attributes for a merchant. A custom attribute is based on a custom attribute definition in a Square seller account, which is created using the CreateMerchantCustomAttributeDefinition endpoint. This BulkUpsertMerchantCustomAttributes endpoint accepts a map of 1 to 25 individual upsert requests and returns a map of individual upsert responses. Each upsert request has a unique ID and provides a merchant ID and custom attribute. Each upsert response is returned with the ID of the corresponding request. To create or update a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.merchants.custom_attributes.batch_upsert(
    values={
        "id1": {
            "merchant_id": "DM7VKY8Q63GNP",
            "custom_attribute": {
                "key": "alternative_seller_name",
                "value": "Ultimate Sneaker Store",
            },
        },
        "id2": {
            "merchant_id": "DM7VKY8Q63GNP",
            "custom_attribute": {"key": "has_seen_tutorial", "value": True},
        },
    },
)

⚙️ Parameters

values: typing.Dict[ str, BulkUpsertMerchantCustomAttributesRequestMerchantCustomAttributeUpsertRequestParams, ]

A map containing 1 to 25 individual upsert requests. For each request, provide an arbitrary ID that is unique for this BulkUpsertMerchantCustomAttributes request and the information needed to create or update a custom attribute.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.merchants.custom_attributes.list(...)

📝 Description

Lists the custom attributes associated with a merchant. You can use the with_definitions query parameter to also retrieve custom attribute definitions in the same call. When all response pages are retrieved, the results include all custom attributes that are visible to the requesting application, including those that are owned by other applications and set to VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.merchants.custom_attributes.list(
    merchant_id="merchant_id",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

merchant_id: str — The ID of the target merchant.

visibility_filter: typing.Optional[VisibilityFilter] — Filters the CustomAttributeDefinition results by their visibility values.

limit: typing.Optional[int]

The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.

cursor: typing.Optional[str]

The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.

with_definitions: typing.Optional[bool]

Indicates whether to return the custom attribute definition in the definition field of each custom attribute. Set this parameter to true to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is false.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.merchants.custom_attributes.get(...)

📝 Description

Retrieves a custom attribute associated with a merchant. You can use the with_definition query parameter to also retrieve the custom attribute definition in the same call. To retrieve a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.merchants.custom_attributes.get(
    merchant_id="merchant_id",
    key="key",
)

⚙️ Parameters

merchant_id: str — The ID of the target merchant.

key: str

The key of the custom attribute to retrieve. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.

with_definition: typing.Optional[bool]

Indicates whether to return the custom attribute definition in the definition field of the custom attribute. Set this parameter to true to get the name and description of the custom attribute, information about the data type, or other definition details. The default value is false.

version: typing.Optional[int]

The current version of the custom attribute, which is used for strongly consistent reads to guarantee that you receive the most up-to-date data. When included in the request, Square returns the specified version or a higher version if one exists. If the specified version is higher than the current version, Square returns a BAD_REQUEST error.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.merchants.custom_attributes.upsert(...)

📝 Description

Creates or updates a custom attribute for a merchant. Use this endpoint to set the value of a custom attribute for a specified merchant. A custom attribute is based on a custom attribute definition in a Square seller account, which is created using the CreateMerchantCustomAttributeDefinition endpoint. To create or update a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.merchants.custom_attributes.upsert(
    merchant_id="merchant_id",
    key="key",
    custom_attribute={"value": "Ultimate Sneaker Store"},
)

⚙️ Parameters

merchant_id: str — The ID of the target merchant.

key: str

The key of the custom attribute to create or update. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.

custom_attribute: CustomAttributeParams

The custom attribute to create or update, with the following fields:

  • value. This value must conform to the schema specified by the definition. For more information, see Supported data types.
  • The version field must match the current version of the custom attribute definition to enable optimistic concurrency If this is not important for your application, version can be set to -1. For any other values, the request fails with a BAD_REQUEST error.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.merchants.custom_attributes.delete(...)

📝 Description

Deletes a custom attribute associated with a merchant. To delete a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.merchants.custom_attributes.delete(
    merchant_id="merchant_id",
    key="key",
)

⚙️ Parameters

merchant_id: str — The ID of the target merchant.

key: str

The key of the custom attribute to delete. This key must match the key of a custom attribute definition in the Square seller account. If the requesting application is not the definition owner, you must use the qualified key.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Orders CustomAttributeDefinitions

client.orders.custom_attribute_definitions.list(...)

📝 Description

Lists the order-related custom attribute definitions that belong to a Square seller account.

When all response pages are retrieved, the results include all custom attribute definitions that are visible to the requesting application, including those that are created by other applications and set to VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.orders.custom_attribute_definitions.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

visibility_filter: typing.Optional[VisibilityFilter] — Requests that all of the custom attributes be returned, or only those that are read-only or read-write.

cursor: typing.Optional[str]

The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.

limit: typing.Optional[int]

The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.custom_attribute_definitions.create(...)

📝 Description

Creates an order-related custom attribute definition. Use this endpoint to define a custom attribute that can be associated with orders.

After creating a custom attribute definition, you can set the custom attribute for orders in the Square seller account.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.custom_attribute_definitions.create(
    custom_attribute_definition={
        "key": "cover-count",
        "schema": {
            "ref": "https://developer-production-s.squarecdn.com/schemas/v1/common.json#squareup.common.Number"
        },
        "name": "Cover count",
        "description": "The number of people seated at a table",
        "visibility": "VISIBILITY_READ_WRITE_VALUES",
    },
    idempotency_key="IDEMPOTENCY_KEY",
)

⚙️ Parameters

custom_attribute_definition: CustomAttributeDefinitionParams

The custom attribute definition to create. Note the following:

  • With the exception of the Selection data type, the schema is specified as a simple URL to the JSON schema definition hosted on the Square CDN. For more information, including supported values and constraints, see Specifying the schema.
  • If provided, name must be unique (case-sensitive) across all visible customer-related custom attribute definitions for the seller.
  • All custom attributes are visible in exported customer data, including those set to VISIBILITY_HIDDEN.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.custom_attribute_definitions.get(...)

📝 Description

Retrieves an order-related custom attribute definition from a Square seller account.

To retrieve a custom attribute definition created by another application, the visibility setting must be VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.custom_attribute_definitions.get(
    key="key",
)

⚙️ Parameters

key: str — The key of the custom attribute definition to retrieve.

version: typing.Optional[int]

To enable optimistic concurrency control, include this optional field and specify the current version of the custom attribute.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.custom_attribute_definitions.update(...)

📝 Description

Updates an order-related custom attribute definition for a Square seller account.

Only the definition owner can update a custom attribute definition. Note that sellers can view all custom attributes in exported customer data, including those set to VISIBILITY_HIDDEN.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.custom_attribute_definitions.update(
    key="key",
    custom_attribute_definition={
        "key": "cover-count",
        "visibility": "VISIBILITY_READ_ONLY",
        "version": 1,
    },
    idempotency_key="IDEMPOTENCY_KEY",
)

⚙️ Parameters

key: str — The key of the custom attribute definition to update.

custom_attribute_definition: CustomAttributeDefinitionParams

The custom attribute definition that contains the fields to update. This endpoint supports sparse updates, so only new or changed fields need to be included in the request. For more information, see Updatable definition fields.

To enable optimistic concurrency control, include the optional version field and specify the current version of the custom attribute definition.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.custom_attribute_definitions.delete(...)

📝 Description

Deletes an order-related custom attribute definition from a Square seller account.

Only the definition owner can delete a custom attribute definition.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.custom_attribute_definitions.delete(
    key="key",
)

⚙️ Parameters

key: str — The key of the custom attribute definition to delete.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Orders CustomAttributes

client.orders.custom_attributes.batch_delete(...)

📝 Description

Deletes order custom attributes as a bulk operation.

Use this endpoint to delete one or more custom attributes from one or more orders. A custom attribute is based on a custom attribute definition in a Square seller account. (To create a custom attribute definition, use the CreateOrderCustomAttributeDefinition endpoint.)

This BulkDeleteOrderCustomAttributes endpoint accepts a map of 1 to 25 individual delete requests and returns a map of individual delete responses. Each delete request has a unique ID and provides an order ID and custom attribute. Each delete response is returned with the ID of the corresponding request.

To delete a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.custom_attributes.batch_delete(
    values={
        "cover-count": {
            "key": "cover-count",
            "order_id": "7BbXGEIWNldxAzrtGf9GPVZTwZ4F",
        },
        "table-number": {
            "key": "table-number",
            "order_id": "7BbXGEIWNldxAzrtGf9GPVZTwZ4F",
        },
    },
)

⚙️ Parameters

values: typing.Dict[ str, BulkDeleteOrderCustomAttributesRequestDeleteCustomAttributeParams ] — A map of requests that correspond to individual delete operations for custom attributes.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.custom_attributes.batch_upsert(...)

📝 Description

Creates or updates order custom attributes as a bulk operation.

Use this endpoint to delete one or more custom attributes from one or more orders. A custom attribute is based on a custom attribute definition in a Square seller account. (To create a custom attribute definition, use the CreateOrderCustomAttributeDefinition endpoint.)

This BulkUpsertOrderCustomAttributes endpoint accepts a map of 1 to 25 individual upsert requests and returns a map of individual upsert responses. Each upsert request has a unique ID and provides an order ID and custom attribute. Each upsert response is returned with the ID of the corresponding request.

To create or update a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.custom_attributes.batch_upsert(
    values={
        "cover-count": {
            "custom_attribute": {
                "key": "cover-count",
                "value": "6",
                "version": 2,
            },
            "order_id": "7BbXGEIWNldxAzrtGf9GPVZTwZ4F",
        },
        "table-number": {
            "custom_attribute": {
                "key": "table-number",
                "value": "11",
                "version": 4,
            },
            "order_id": "7BbXGEIWNldxAzrtGf9GPVZTwZ4F",
        },
    },
)

⚙️ Parameters

values: typing.Dict[ str, BulkUpsertOrderCustomAttributesRequestUpsertCustomAttributeParams ] — A map of requests that correspond to individual upsert operations for custom attributes.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.custom_attributes.list(...)

📝 Description

Lists the custom attributes associated with an order.

You can use the with_definitions query parameter to also retrieve custom attribute definitions in the same call.

When all response pages are retrieved, the results include all custom attributes that are visible to the requesting application, including those that are owned by other applications and set to VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.orders.custom_attributes.list(
    order_id="order_id",
)
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

order_id: str — The ID of the target order.

visibility_filter: typing.Optional[VisibilityFilter] — Requests that all of the custom attributes be returned, or only those that are read-only or read-write.

cursor: typing.Optional[str]

The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.

limit: typing.Optional[int]

The maximum number of results to return in a single paged response. This limit is advisory. The response might contain more or fewer results. The minimum value is 1 and the maximum value is 100. The default value is 20. For more information, see Pagination.

with_definitions: typing.Optional[bool]

Indicates whether to return the custom attribute definition in the definition field of each custom attribute. Set this parameter to true to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is false.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.custom_attributes.get(...)

📝 Description

Retrieves a custom attribute associated with an order.

You can use the with_definition query parameter to also retrieve the custom attribute definition in the same call.

To retrieve a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_ONLY or VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.custom_attributes.get(
    order_id="order_id",
    custom_attribute_key="custom_attribute_key",
)

⚙️ Parameters

order_id: str — The ID of the target order.

custom_attribute_key: str

The key of the custom attribute to retrieve. This key must match the key of an existing custom attribute definition.

version: typing.Optional[int]

To enable optimistic concurrency control, include this optional field and specify the current version of the custom attribute.

with_definition: typing.Optional[bool]

Indicates whether to return the custom attribute definition in the definition field of each custom attribute. Set this parameter to true to get the name and description of each custom attribute, information about the data type, or other definition details. The default value is false.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.custom_attributes.upsert(...)

📝 Description

Creates or updates a custom attribute for an order.

Use this endpoint to set the value of a custom attribute for a specific order. A custom attribute is based on a custom attribute definition in a Square seller account. (To create a custom attribute definition, use the CreateOrderCustomAttributeDefinition endpoint.)

To create or update a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.custom_attributes.upsert(
    order_id="order_id",
    custom_attribute_key="custom_attribute_key",
    custom_attribute={"key": "table-number", "value": "42", "version": 1},
)

⚙️ Parameters

order_id: str — The ID of the target order.

custom_attribute_key: str

The key of the custom attribute to create or update. This key must match the key of an existing custom attribute definition.

custom_attribute: CustomAttributeParams

The custom attribute to create or update, with the following fields:

  • value. This value must conform to the schema specified by the definition. For more information, see Value data types.

  • version. To enable optimistic concurrency control, include this optional field and specify the current version of the custom attribute.

idempotency_key: typing.Optional[str]

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

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.orders.custom_attributes.delete(...)

📝 Description

Deletes a custom attribute associated with a customer profile.

To delete a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES. Note that seller-defined custom attributes (also known as custom fields) are always set to VISIBILITY_READ_WRITE_VALUES.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.orders.custom_attributes.delete(
    order_id="order_id",
    custom_attribute_key="custom_attribute_key",
)

⚙️ Parameters

order_id: str — The ID of the target order.

custom_attribute_key: str

The key of the custom attribute to delete. This key must match the key of an existing custom attribute definition.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

TeamMembers WageSetting

client.team_members.wage_setting.get(...)

📝 Description

Retrieves a WageSetting object for a team member specified by TeamMember.id. For more information, see Troubleshooting the Team API.

Square recommends using RetrieveTeamMember or SearchTeamMembers to get this information directly from the TeamMember.wage_setting field.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.team_members.wage_setting.get(
    team_member_id="team_member_id",
)

⚙️ Parameters

team_member_id: str — The ID of the team member for which to retrieve the wage setting.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.team_members.wage_setting.update(...)

📝 Description

Creates or updates a WageSetting object. The object is created if a WageSetting with the specified team_member_id doesn't exist. Otherwise, it fully replaces the WageSetting object for the team member. The WageSetting is returned on a successful update. For more information, see Troubleshooting the Team API.

Square recommends using CreateTeamMember or UpdateTeamMember to manage the TeamMember.wage_setting field directly.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.team_members.wage_setting.update(
    team_member_id="team_member_id",
    wage_setting={
        "job_assignments": [
            {
                "job_title": "Manager",
                "pay_type": "SALARY",
                "annual_rate": {"amount": 3000000, "currency": "USD"},
                "weekly_hours": 40,
            },
            {
                "job_title": "Cashier",
                "pay_type": "HOURLY",
                "hourly_rate": {"amount": 2000, "currency": "USD"},
            },
        ],
        "is_overtime_exempt": True,
    },
)

⚙️ Parameters

team_member_id: str — The ID of the team member for which to update the WageSetting object.

wage_setting: WageSettingParams

The complete WageSetting object. For all job assignments, specify one of the following:

  • job_id (recommended) - If needed, call ListJobs to get a list of all jobs. Requires Square API version 2024-12-18 or later.
  • job_title - Use the exact, case-sensitive spelling of an existing title unless you want to create a new job. This value is ignored if job_id is also provided.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Terminal Actions

client.terminal.actions.create(...)

📝 Description

Creates a Terminal action request and sends it to the specified device.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.actions.create(
    idempotency_key="thahn-70e75c10-47f7-4ab6-88cc-aaa4076d065e",
    action={
        "device_id": "{{DEVICE_ID}}",
        "deadline_duration": "PT5M",
        "type": "SAVE_CARD",
        "save_card_options": {
            "customer_id": "{{CUSTOMER_ID}}",
            "reference_id": "user-id-1",
        },
    },
)

⚙️ Parameters

idempotency_key: str

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

See Idempotency keys for more information.

action: TerminalActionParams — The Action to create.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.terminal.actions.search(...)

📝 Description

Retrieves a filtered list of Terminal action requests created by the account making the request. Terminal action requests are available for 30 days.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.actions.search(
    query={
        "filter": {"created_at": {"start_at": "2022-04-01T00:00:00.000Z"}},
        "sort": {"sort_order": "DESC"},
    },
    limit=2,
)

⚙️ Parameters

query: typing.Optional[TerminalActionQueryParams]

Queries terminal actions based on given conditions and sort order. Leaving this unset will return all actions with the default sort order.

cursor: typing.Optional[str]

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 Pagination for more information.

limit: typing.Optional[int] — Limit the number of results returned for a single request.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.terminal.actions.get(...)

📝 Description

Retrieves a Terminal action request by action_id. Terminal action requests are available for 30 days.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.actions.get(
    action_id="action_id",
)

⚙️ Parameters

action_id: str — Unique ID for the desired TerminalAction.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.terminal.actions.cancel(...)

📝 Description

Cancels a Terminal action request if the status of the request permits it.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.actions.cancel(
    action_id="action_id",
)

⚙️ Parameters

action_id: str — Unique ID for the desired TerminalAction.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Terminal Checkouts

client.terminal.checkouts.create(...)

📝 Description

Creates a Terminal checkout request and sends it to the specified device to take a payment for the requested amount.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.checkouts.create(
    idempotency_key="28a0c3bc-7839-11ea-bc55-0242ac130003",
    checkout={
        "amount_money": {"amount": 2610, "currency": "USD"},
        "reference_id": "id11572",
        "note": "A brief note",
        "device_options": {"device_id": "dbb5d83a-7838-11ea-bc55-0242ac130003"},
    },
)

⚙️ Parameters

idempotency_key: str

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

See Idempotency keys for more information.

checkout: TerminalCheckoutParams — The checkout to create.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.terminal.checkouts.search(...)

📝 Description

Returns a filtered list of Terminal checkout requests created by the application making the request. Only Terminal checkout requests created for the merchant scoped to the OAuth token are returned. Terminal checkout requests are available for 30 days.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.checkouts.search(
    query={"filter": {"status": "COMPLETED"}},
    limit=2,
)

⚙️ Parameters

query: typing.Optional[TerminalCheckoutQueryParams]

Queries Terminal checkouts based on given conditions and the sort order. Leaving these unset returns all checkouts with the default sort order.

cursor: typing.Optional[str]

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.

limit: typing.Optional[int] — Limits the number of results returned for a single request.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.terminal.checkouts.get(...)

📝 Description

Retrieves a Terminal checkout request by checkout_id. Terminal checkout requests are available for 30 days.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.checkouts.get(
    checkout_id="checkout_id",
)

⚙️ Parameters

checkout_id: str — The unique ID for the desired TerminalCheckout.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.terminal.checkouts.cancel(...)

📝 Description

Cancels a Terminal checkout request if the status of the request permits it.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.checkouts.cancel(
    checkout_id="checkout_id",
)

⚙️ Parameters

checkout_id: str — The unique ID for the desired TerminalCheckout.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Terminal Refunds

client.terminal.refunds.create(...)

📝 Description

Creates a request to refund an Interac payment completed on a Square Terminal. Refunds for Interac payments on a Square Terminal are supported only for Interac debit cards in Canada. Other refunds for Terminal payments should use the Refunds API. For more information, see Refunds API.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.refunds.create(
    idempotency_key="402a640b-b26f-401f-b406-46f839590c04",
    refund={
        "payment_id": "5O5OvgkcNUhl7JBuINflcjKqUzXZY",
        "amount_money": {"amount": 111, "currency": "CAD"},
        "reason": "Returning items",
        "device_id": "f72dfb8e-4d65-4e56-aade-ec3fb8d33291",
    },
)

⚙️ Parameters

idempotency_key: str

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

See Idempotency keys for more information.

refund: typing.Optional[TerminalRefundParams] — The refund to create.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.terminal.refunds.search(...)

📝 Description

Retrieves a filtered list of Interac Terminal refund requests created by the seller making the request. Terminal refund requests are available for 30 days.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.refunds.search(
    query={"filter": {"status": "COMPLETED"}},
    limit=1,
)

⚙️ Parameters

query: typing.Optional[TerminalRefundQueryParams]

Queries the Terminal refunds based on given conditions and the sort order. Calling SearchTerminalRefunds without an explicit query parameter returns all available refunds with the default sort order.

cursor: typing.Optional[str]

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.

limit: typing.Optional[int] — Limits the number of results returned for a single request.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.terminal.refunds.get(...)

📝 Description

Retrieves an Interac Terminal refund object by ID. Terminal refund objects are available for 30 days.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.refunds.get(
    terminal_refund_id="terminal_refund_id",
)

⚙️ Parameters

terminal_refund_id: str — The unique ID for the desired TerminalRefund.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.terminal.refunds.cancel(...)

📝 Description

Cancels an Interac Terminal refund request by refund request ID if the status of the request permits it.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.terminal.refunds.cancel(
    terminal_refund_id="terminal_refund_id",
)

⚙️ Parameters

terminal_refund_id: str — The unique ID for the desired TerminalRefund.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Webhooks EventTypes

client.webhooks.event_types.list(...)

📝 Description

Lists all webhook event types that can be subscribed to.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.webhooks.event_types.list()

⚙️ Parameters

api_version: typing.Optional[str] — The API version for which to list event types. Setting this field overrides the default version used by the application.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Webhooks Subscriptions

client.webhooks.subscriptions.list(...)

📝 Description

Lists all webhook subscriptions owned by your application.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
response = client.webhooks.subscriptions.list()
for item in response:
    yield item
# alternatively, you can paginate page-by-page
for page in response.iter_pages():
    yield page

⚙️ Parameters

cursor: typing.Optional[str]

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

For more information, see Pagination.

include_disabled: typing.Optional[bool]

Includes disabled Subscriptions. By default, all enabled Subscriptions are returned.

sort_order: typing.Optional[SortOrder]

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

limit: typing.Optional[int]

The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value.

Default: 100

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.subscriptions.create(...)

📝 Description

Creates a webhook subscription.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.webhooks.subscriptions.create(
    idempotency_key="63f84c6c-2200-4c99-846c-2670a1311fbf",
    subscription={
        "name": "Example Webhook Subscription",
        "event_types": ["payment.created", "payment.updated"],
        "notification_url": "https://example-webhook-url.com",
        "api_version": "2021-12-15",
    },
)

⚙️ Parameters

subscription: WebhookSubscriptionParams — The Subscription to create.

idempotency_key: typing.Optional[str] — A unique string that identifies the CreateWebhookSubscription request.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.subscriptions.get(...)

📝 Description

Retrieves a webhook subscription identified by its ID.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.webhooks.subscriptions.get(
    subscription_id="subscription_id",
)

⚙️ Parameters

subscription_id: str — [REQUIRED] The ID of the Subscription to retrieve.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.subscriptions.update(...)

📝 Description

Updates a webhook subscription.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.webhooks.subscriptions.update(
    subscription_id="subscription_id",
    subscription={
        "name": "Updated Example Webhook Subscription",
        "enabled": False,
    },
)

⚙️ Parameters

subscription_id: str — [REQUIRED] The ID of the Subscription to update.

subscription: typing.Optional[WebhookSubscriptionParams] — The Subscription to update.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.subscriptions.delete(...)

📝 Description

Deletes a webhook subscription.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.webhooks.subscriptions.delete(
    subscription_id="subscription_id",
)

⚙️ Parameters

subscription_id: str — [REQUIRED] The ID of the Subscription to delete.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.subscriptions.update_signature_key(...)

📝 Description

Updates a webhook subscription by replacing the existing signature key with a new one.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.webhooks.subscriptions.update_signature_key(
    subscription_id="subscription_id",
    idempotency_key="ed80ae6b-0654-473b-bbab-a39aee89a60d",
)

⚙️ Parameters

subscription_id: str — [REQUIRED] The ID of the Subscription to update.

idempotency_key: typing.Optional[str] — A unique string that identifies the UpdateWebhookSubscriptionSignatureKey request.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.webhooks.subscriptions.test(...)

📝 Description

Tests a webhook subscription by sending a test event to the notification URL.

🔌 Usage

from square import Square

client = Square(
    token="YOUR_TOKEN",
)
client.webhooks.subscriptions.test(
    subscription_id="subscription_id",
    event_type="payment.created",
)

⚙️ Parameters

subscription_id: str — [REQUIRED] The ID of the Subscription to test.

event_type: typing.Optional[str]

The event type that will be used to test the Subscription. The event type must be contained in the list of event types in the Subscription.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.