client.mobile.authorization_code(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.mobile.authorization_code( location_id="YOUR_LOCATION_ID", )
-
-
-
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.
-
-
client.o_auth.revoke_token(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.o_auth.revoke_token( client_id="CLIENT_ID", access_token="ACCESS_TOKEN", )
-
-
-
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(...)
-
-
-
Returns an OAuth access token and refresh token using the
authorization_code
orrefresh_token
grant type.When
grant_type
isauthorization_code
:- With the code flow,
provide
code
,client_id
, andclient_secret
. - With the PKCE flow,
provide
code
,client_id
, andcode_verifier
.
When
grant_type
isrefresh_token
:- With the code flow, provide
refresh_token
,client_id
, andclient_secret
. The response returns the same refresh token provided in the request. - With the PKCE flow, provide
refresh_token
andclient_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 theshort_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.
- With the code flow,
provide
-
-
-
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", )
-
-
-
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 thecode
field.refresh_token
- Requires therefresh_token
field.migration_token
- LEGACY for access tokens obtained using a Square API version prior to 2019-03-13. Requires themigration_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
isauthorization_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
isauthorization_code
and you provided theredirect_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
isrefresh_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
ismigration_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
isrefresh_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
isauthorization_code
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.o_auth.retrieve_token_status()
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.o_auth.retrieve_token_status()
-
-
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.o_auth.authorize()
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.o_auth.authorize()
-
-
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.v1transactions.v1list_orders(...)
-
-
-
Provides summary information for a merchant's online store orders.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.v1transactions.v1list_orders( location_id="location_id", )
-
-
-
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(...)
-
-
-
Provides comprehensive information for a single online store order, including the order's history.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.v1transactions.v1retrieve_order( location_id="location_id", order_id="order_id", )
-
-
-
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(...)
-
-
-
Updates the details of an online store order. Every update you perform on an order corresponds to one of three actions:
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.v1transactions.v1update_order( location_id="location_id", order_id="order_id", action="COMPLETE", )
-
-
-
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.
-
-
client.apple_pay.register_domain(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.apple_pay.register_domain( domain_name="example.com", )
-
-
-
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.
-
-
client.bank_accounts.list(...)
-
-
-
Returns a list of BankAccount objects linked to a Square account.
-
-
-
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
-
-
-
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(...)
-
-
-
Returns details of a BankAccount identified by V1 bank account ID.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bank_accounts.get_by_v1id( v1bank_account_id="v1_bank_account_id", )
-
-
-
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(...)
-
-
-
Returns details of a BankAccount linked to a Square account.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bank_accounts.get( bank_account_id="bank_account_id", )
-
-
-
bank_account_id:
str
— Square-issued ID of the desiredBankAccount
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.bookings.list(...)
-
-
-
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, setAPPOINTMENTS_ALL_READ
andAPPOINTMENTS_READ
for the OAuth scope.
-
-
-
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
-
-
-
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 afterstart_at_min
is used.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.bookings.create(...)
-
-
-
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, setAPPOINTMENTS_ALL_WRITE
andAPPOINTMENTS_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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.create( booking={}, )
-
-
-
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(...)
-
-
-
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, setAPPOINTMENTS_ALL_READ
andAPPOINTMENTS_READ
for the OAuth scope.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.search_availability( query={"filter": {"start_at_range": {}}}, )
-
-
-
query:
SearchAvailabilityQueryParams
— Query conditions used to filter buyer-accessible booking availabilities.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.bookings.bulk_retrieve_bookings(...)
-
-
-
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, setAPPOINTMENTS_ALL_READ
andAPPOINTMENTS_READ
for the OAuth scope.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.bulk_retrieve_bookings( booking_ids=["booking_ids"], )
-
-
-
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()
-
-
-
Retrieves a seller's booking profile.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.get_business_profile()
-
-
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.bookings.retrieve_location_booking_profile(...)
-
-
-
Retrieves a seller's location booking profile.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.retrieve_location_booking_profile( location_id="location_id", )
-
-
-
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(...)
-
-
-
Retrieves one or more team members' booking profiles.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.bulk_retrieve_team_member_booking_profiles( team_member_ids=["team_member_ids"], )
-
-
-
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(...)
-
-
-
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, setAPPOINTMENTS_ALL_READ
andAPPOINTMENTS_READ
for the OAuth scope.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.get( booking_id="booking_id", )
-
-
-
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(...)
-
-
-
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, setAPPOINTMENTS_ALL_WRITE
andAPPOINTMENTS_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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.update( booking_id="booking_id", booking={}, )
-
-
-
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(...)
-
-
-
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, setAPPOINTMENTS_ALL_WRITE
andAPPOINTMENTS_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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.cancel( booking_id="booking_id", )
-
-
-
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.
-
-
client.cards.list(...)
-
-
-
Retrieves a list of cards owned by the account making the request. A max of 25 cards will be returned.
-
-
-
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
-
-
-
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(...)
-
-
-
Adds a card on file to an existing merchant.
-
-
-
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", }, )
-
-
-
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(...)
-
-
-
Retrieves details for a specific Card.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.cards.get( card_id="card_id", )
-
-
-
card_id:
str
— Unique ID for the desired Card.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.cards.disable(...)
-
-
-
Disables the card, preventing any further updates or charges. Disabling an already disabled card is allowed but has no effect.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.cards.disable( card_id="card_id", )
-
-
-
card_id:
str
— Unique ID for the desired Card.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.catalog.batch_delete(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.catalog.batch_delete( object_ids=["W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK"], )
-
-
-
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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.catalog.batch_get( object_ids=["W62UWFY35CWMYGVWK6TWJDNI", "AA27W3M2GGTF3H6AVPNB77CK"], include_related_objects=True, )
-
-
-
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 theobjects
field of the response. These objects are put in therelated_objects
field. Setting this totrue
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 therelated_objects
field of the response. If theobjects
field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in therelated_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 theis_deleted
attribute set totrue
.
-
include_category_path_to_root:
typing.Optional[bool]
Specifies whether or not to include the
path_to_root
list for each returned category instance. Thepath_to_root
list consists ofCategoryPathToRootNode
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, thepath_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(...)
-
-
-
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.
-
-
-
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, }, }, ] } ], )
-
-
-
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 itsis_deleted
field must not be set totrue
.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 itsitem_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()
-
-
-
Retrieves information about the Square Catalog API, such as batch size limits that can be used by the
BatchUpsertCatalogObjects
endpoint.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.catalog.info()
-
-
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.catalog.list(...)
-
-
-
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 totrue
.
-
-
-
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
-
-
-
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(...)
-
-
-
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, whereasSearchCatalogObjects
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, whereSearchCatalogObjects
does not.SearchCatalogItems
does not support theinclude_deleted_objects
filter to search for deleted items or item variations, whereasSearchCatalogObjects
does.- The both endpoints have different call conventions, including the query filter formats.
-
-
-
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, )
-
-
-
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]
— Iftrue
, deleted objects will be included in the results. Defaults tofalse
. Deleted objects will have theiris_deleted
field set totrue
. Ifinclude_deleted_objects
istrue
, then theinclude_category_path_to_root
request parameter must befalse
. Both properties cannot betrue
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 therelated_objects
field of the response. If theobjects
field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in therelated_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 tobegin_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 thepath_to_root
list for each returned category instance. Thepath_to_root
list consists ofCategoryPathToRootNode
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, thepath_to_root
list is empty and is not returned in the response payload. Ifinclude_category_path_to_root
istrue
, then theinclude_deleted_objects
request parameter must befalse
. Both properties cannot betrue
at the same time.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.catalog.search_items(...)
-
-
-
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, whereasSearchCatalogObjects
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, whereSearchCatalogObjects
does not.SearchCatalogItems
does not support theinclude_deleted_objects
filter to search for deleted items or item variations, whereasSearchCatalogObjects
does.- The both endpoints use different call conventions, including the query filter formats.
-
-
-
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"}, ], )
-
-
-
text_filter:
typing.Optional[str]
The text filter expression to return items or item variations containing specified text in the
name
,description
, orabbreviation
attribute value of an item, or in thename
,sku
, orupc
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(...)
-
-
-
Updates the CatalogModifierList objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.
-
-
-
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"], )
-
-
-
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
ormodifier_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
ormodifier_lists_to_disable
must be specified.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.catalog.update_item_taxes(...)
-
-
-
Updates the CatalogTax objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item.
-
-
-
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"], )
-
-
-
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
ortaxes_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
ortaxes_to_disable
must be specified.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.customers.list(...)
-
-
-
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.
-
-
-
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
-
-
-
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
or400 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(...)
-
-
-
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
-
-
-
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", )
-
-
-
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
andlast_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
orMM-DD
format. For example, specify1998-09-21
for September 21, 1998, or09-21
for September 21. Birthdays are returned inYYYY-MM-DD
format, whereYYYY
is the specified birth year or0000
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(...)
-
-
-
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
-
-
-
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", }, }, )
-
-
-
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(...)
-
-
-
Deletes multiple customer profiles.
The endpoint takes a list of customer IDs and returns a map of responses.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.bulk_delete_customers( customer_ids=[ "8DDA5NZVBZFGAX0V3HPF81HHE0", "N18CPRVXR5214XPBBA6BZQWF3C", "2GYD7WNXF7BJZW1PMGNXZ3Y8M8", ], )
-
-
-
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(...)
-
-
-
Retrieves multiple customer profiles.
This endpoint takes a list of customer IDs and returns a map of responses.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.bulk_retrieve_customers( customer_ids=[ "8DDA5NZVBZFGAX0V3HPF81HHE0", "N18CPRVXR5214XPBBA6BZQWF3C", "2GYD7WNXF7BJZW1PMGNXZ3Y8M8", ], )
-
-
-
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(...)
-
-
-
Updates multiple customer profiles.
This endpoint takes a map of individual update requests and returns a map of responses.
-
-
-
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, }, }, )
-
-
-
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(...)
-
-
-
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 ongiven_name
andfamily_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.
-
-
-
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"}, }, )
-
-
-
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
or400 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
andfamily_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(...)
-
-
-
Returns details for a single customer.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.get( customer_id="customer_id", )
-
-
-
customer_id:
str
— The ID of the customer to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.customers.update(...)
-
-
-
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.
-
-
-
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, )
-
-
-
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
andlast_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
orMM-DD
format. For example, specify1998-09-21
for September 21, 1998, or09-21
for September 21. Birthdays are returned inYYYY-MM-DD
format, whereYYYY
is the specified birth year or0000
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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.delete( customer_id="customer_id", )
-
-
-
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.
-
-
client.devices.list(...)
-
-
-
List devices associated with the merchant. Currently, only Terminal API devices are supported.
-
-
-
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
-
-
-
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(...)
-
-
-
Retrieves Device with the associated
device_id
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.devices.get( device_id="device_id", )
-
-
-
device_id:
str
— The unique ID for the desiredDevice
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.disputes.list(...)
-
-
-
Returns a list of disputes associated with a particular account.
-
-
-
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
-
-
-
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(...)
-
-
-
Returns details about a specific dispute.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.disputes.get( dispute_id="dispute_id", )
-
-
-
dispute_id:
str
— The ID of the dispute you want more details about.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.disputes.accept(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.disputes.accept( dispute_id="dispute_id", )
-
-
-
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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.disputes.create_evidence_file( dispute_id="dispute_id", )
-
-
-
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(...)
-
-
-
Uploads text to use as evidence for a dispute challenge.
-
-
-
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", )
-
-
-
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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.disputes.submit_evidence( dispute_id="dispute_id", )
-
-
-
dispute_id:
str
— The ID of the dispute for which you want to submit evidence.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.employees.list(...)
-
-
-
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
-
-
-
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(...)
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.employees.get( id="id", )
-
-
-
id:
str
— UUID for the employee that was requested.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.events.search_events(...)
-
-
-
Search for Square API events that occur within a 28-day timeframe.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.events.search_events()
-
-
-
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()
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.events.disable_events()
-
-
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.events.enable_events()
-
-
-
Enables events to make them searchable. Only events that occur while in the enabled state are searchable.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.events.enable_events()
-
-
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.events.list_event_types(...)
-
-
-
Lists all event types that you can subscribe to as webhooks or query using the Events API.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.events.list_event_types()
-
-
-
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.
-
-
client.gift_cards.list(...)
-
-
-
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.
-
-
-
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
-
-
-
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(...)
-
-
-
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 anACTIVATE
activity with the initial balance. Alternatively, you can use RefundPayment to refund a payment to the new gift card.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.gift_cards.create( idempotency_key="NC9Tm69EjbjtConu", location_id="81FN9BNFZTKS4", gift_card={"type": "DIGITAL"}, )
-
-
-
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. Thegan_source
andgan
fields are included as follows:To direct Square to generate a 16-digit GAN, omit
gan_source
andgan
.To provide a custom GAN, include
gan_source
andgan
.- For
gan_source
, specifyOTHER
. - 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. - For
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.gift_cards.get_from_gan(...)
-
-
-
Retrieves a gift card using the gift card account number (GAN).
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.gift_cards.get_from_gan( gan="7783320001001635", )
-
-
-
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(...)
-
-
-
Retrieves a gift card using a secure payment token that represents the gift card.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.gift_cards.get_from_nonce( nonce="cnon:7783322135245171", )
-
-
-
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(...)
-
-
-
Links a customer to a gift card, which is also referred to as adding a card on file.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.gift_cards.link_customer( gift_card_id="gift_card_id", customer_id="GKY0FZ3V717AH8Q2D821PNT2ZW", )
-
-
-
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(...)
-
-
-
Unlinks a customer from a gift card, which is also referred to as removing a card on file.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.gift_cards.unlink_customer( gift_card_id="gift_card_id", customer_id="GKY0FZ3V717AH8Q2D821PNT2ZW", )
-
-
-
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(...)
-
-
-
Retrieves a gift card using the gift card ID.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.gift_cards.get( id="id", )
-
-
-
id:
str
— The ID of the gift card to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.inventory.deprecated_get_adjustment(...)
-
-
-
Deprecated version of RetrieveInventoryAdjustment after the endpoint URL is updated to conform to the standard convention.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.inventory.deprecated_get_adjustment( adjustment_id="adjustment_id", )
-
-
-
adjustment_id:
str
— ID of the InventoryAdjustment to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.inventory.get_adjustment(...)
-
-
-
Returns the InventoryAdjustment object with the provided
adjustment_id
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.inventory.get_adjustment( adjustment_id="adjustment_id", )
-
-
-
adjustment_id:
str
— ID of the InventoryAdjustment to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.inventory.deprecated_batch_change(...)
-
-
-
Deprecated version of BatchChangeInventory after the endpoint URL is updated to conform to the standard convention.
-
-
-
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, )
-
-
-
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(...)
-
-
-
Deprecated version of BatchRetrieveInventoryChanges after the endpoint URL is updated to conform to the standard convention.
-
-
-
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", )
-
-
-
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 thanTRANSFER
. The default value is[PHYSICAL_COUNT, ADJUSTMENT]
.
-
states:
typing.Optional[typing.Sequence[InventoryState]]
The filter to return
ADJUSTMENT
query results byInventoryState
. 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
orcalculated_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(...)
-
-
-
Deprecated version of BatchRetrieveInventoryCounts after the endpoint URL is updated to conform to the standard convention.
-
-
-
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", )
-
-
-
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 ofNONE
,SOLD
, andUNLINKED_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(...)
-
-
-
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.
-
-
-
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, )
-
-
-
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(...)
-
-
-
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.
-
-
-
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
-
-
-
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 thanTRANSFER
. The default value is[PHYSICAL_COUNT, ADJUSTMENT]
.
-
states:
typing.Optional[typing.Sequence[InventoryState]]
The filter to return
ADJUSTMENT
query results byInventoryState
. 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
orcalculated_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(...)
-
-
-
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.
-
-
-
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
-
-
-
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 ofNONE
,SOLD
, andUNLINKED_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(...)
-
-
-
Deprecated version of RetrieveInventoryPhysicalCount after the endpoint URL is updated to conform to the standard convention.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.inventory.deprecated_get_physical_count( physical_count_id="physical_count_id", )
-
-
-
physical_count_id:
str
ID of the InventoryPhysicalCount to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.inventory.get_physical_count(...)
-
-
-
Returns the InventoryPhysicalCount object with the provided
physical_count_id
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.inventory.get_physical_count( physical_count_id="physical_count_id", )
-
-
-
physical_count_id:
str
ID of the InventoryPhysicalCount to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.inventory.get_transfer(...)
-
-
-
Returns the InventoryTransfer object with the provided
transfer_id
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.inventory.get_transfer( transfer_id="transfer_id", )
-
-
-
transfer_id:
str
— ID of the InventoryTransfer to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.inventory.get(...)
-
-
-
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.
-
-
-
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
-
-
-
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(...)
-
-
-
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 theCatalogObject
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.
-
-
-
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
-
-
-
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.invoices.list(...)
-
-
-
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.
-
-
-
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
-
-
-
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(...)
-
-
-
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).
-
-
-
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", )
-
-
-
invoice:
InvoiceParams
— The invoice to create.
-
idempotency_key:
typing.Optional[str]
A unique string that identifies the
CreateInvoice
request. If you do not provideidempotency_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(...)
-
-
-
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.
-
-
-
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, )
-
-
-
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(...)
-
-
-
Retrieves an invoice by invoice ID.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.invoices.get( invoice_id="invoice_id", )
-
-
-
invoice_id:
str
— The ID of the invoice to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.invoices.update(...)
-
-
-
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 theorder_id
orlocation_id
field.
-
-
-
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", )
-
-
-
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 invoiceversion
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 provideidempotency_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(...)
-
-
-
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).
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.invoices.delete( invoice_id="invoice_id", )
-
-
-
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(...)
-
-
-
Uploads a file and attaches it to an invoice. This endpoint accepts HTTP multipart/form-data file uploads with a JSON
request
part and afile
part. Thefile
part must be areadable 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
, orPARTIALLY_PAID
state.NOTE: When testing in the Sandbox environment, the total file size is limited to 1 KB.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.invoices.create_invoice_attachment( invoice_id="invoice_id", )
-
-
-
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(...)
-
-
-
Removes an attachment from an invoice and permanently deletes the file. Attachments can be removed only from invoices in the
DRAFT
,SCHEDULED
,UNPAID
, orPARTIALLY_PAID
state.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.invoices.delete_invoice_attachment( invoice_id="invoice_id", attachment_id="attachment_id", )
-
-
-
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(...)
-
-
-
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
, orFAILED
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.invoices.cancel( invoice_id="invoice_id", version=0, )
-
-
-
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(...)
-
-
-
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 fromDRAFT
to a status based on the invoice configuration. For example, the status changes toUNPAID
if Square emails the invoice orPARTIALLY_PAID
if Square charges a card on file for a portion of the invoice amount.In addition to the required
ORDERS_WRITE
andINVOICES_WRITE
permissions,CUSTOMERS_READ
andPAYMENTS_WRITE
are required when publishing invoices configured for card-on-file payments.
-
-
-
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", )
-
-
-
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 provideidempotency_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.locations.list()
-
-
-
Provides details about all of the seller's locations, including those with an inactive status. Locations are listed alphabetically by
name
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.locations.list()
-
-
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.locations.create(...)
-
-
-
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.
-
-
-
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", }, )
-
-
-
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(...)
-
-
-
Retrieves details of a single location. Specify "main" as the location ID to retrieve details of the main location.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.locations.get( location_id="location_id", )
-
-
-
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(...)
-
-
-
Updates a location.
-
-
-
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", }, )
-
-
-
location_id:
str
— The ID of the location to update.
-
location:
typing.Optional[LocationParams]
— TheLocation
object with only the fields to update.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.locations.checkouts(...)
-
-
-
Links a
checkoutId
to acheckout_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.
-
-
-
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"}, } ], )
-
-
-
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
, andreferenceId
appended as URL parameters. For example, if the provided redirect URL ishttp://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 youradditional_recipients
field cannot be more than 90% of thetotal_money
calculated by Square for your order. Thelocation_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.
-
-
client.loyalty.search_events(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.loyalty.search_events( query={ "filter": { "order_filter": {"order_id": "PyATxhYLfsMqpVkcKJITPydgEYfZY"} } }, limit=30, )
-
-
-
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.
-
-
client.merchants.list(...)
-
-
-
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 singleMerchant
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.
-
-
-
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
-
-
-
cursor:
typing.Optional[int]
— The cursor generated by the previous response.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.merchants.get(...)
-
-
-
Retrieves the
Merchant
object for the givenmerchant_id
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.merchants.get( merchant_id="merchant_id", )
-
-
-
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.
-
-
client.checkout.retrieve_location_settings(...)
-
-
-
Retrieves the location-level settings for a Square-hosted checkout page.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.checkout.retrieve_location_settings( location_id="location_id", )
-
-
-
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(...)
-
-
-
Updates the location-level settings for a Square-hosted checkout page.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.checkout.update_location_settings( location_id="location_id", location_settings={}, )
-
-
-
location_id:
str
— The ID of the location for which to retrieve settings.
-
location_settings:
CheckoutLocationSettingsParams
— Describe your updates using thelocation_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()
-
-
-
Retrieves the merchant-level settings for a Square-hosted checkout page.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.checkout.retrieve_merchant_settings()
-
-
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.checkout.update_merchant_settings(...)
-
-
-
Updates the merchant-level settings for a Square-hosted checkout page.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.checkout.update_merchant_settings( merchant_settings={}, )
-
-
-
merchant_settings:
CheckoutMerchantSettingsParams
— Describe your updates using themerchant_settings
object. Make sure it contains only the fields that have changed.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.orders.create(...)
-
-
-
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.
-
-
-
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", )
-
-
-
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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.orders.batch_get( location_id="057P5VYJ4A5X1", order_ids=["CAISEM82RcpmcFBM0TfOyiHV3es", "CAISENgvlJ6jLWAzERDzjyHVybY"], )
-
-
-
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(...)
-
-
-
Enables applications to preview order pricing without creating an order.
-
-
-
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"} ], }, )
-
-
-
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
reward
s are created. Therefore, the rewardid
s are random strings used only to reference the reward tier.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.orders.clone(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.orders.clone( order_id="ZAISEM52YcpmcWAzERDOyiWS123", version=3, idempotency_key="UNIQUE_STRING", )
-
-
-
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(...)
-
-
-
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. YourSearchOrdersQuery
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.
-
-
-
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, )
-
-
-
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. Iffalse
,SearchOrders
returns complete order objects.Default:
false
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.orders.get(...)
-
-
-
Retrieves an Order by ID.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.orders.get( order_id="order_id", )
-
-
-
order_id:
str
— The ID of the order to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.orders.update(...)
-
-
-
Updates an open order by adding, replacing, or deleting fields. Orders with a
COMPLETED
orCANCELED
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.
- The
-
-
-
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", )
-
-
-
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(...)
-
-
-
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 of0
can be marked as paid by specifying an empty array ofpayment_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 sameorder_id
not specified in thepayment_ids
is canceled. - Be approved with delayed capture.
Using a delayed capture payment with
PayOrder
completes the approved payment.
- Reference the order by specifying the
-
-
-
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"], )
-
-
-
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.
-
-
client.payments.list(...)
-
-
-
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.
-
-
-
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
-
-
-
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 thecreated_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 thetotal_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 inoffline_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 inoffline_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 isCREATED_AT
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.payments.create(...)
-
-
-
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.
-
-
-
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", )
-
-
-
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 everyCreatePayment
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 tofalse
, 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 withamount_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 betrue
whenautocomplete = 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:
- A leading + symbol (followed by a country code)
- The phone number can contain spaces and the special characters
(
,)
,-
, and.
. Alphabetical characters aren't allowed. - 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(...)
-
-
-
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 aCreatePayment
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 yourCreatePayment
request that you want to cancel. After canceling the payment, you can submit yourCreatePayment
request again.Note that if no payment with the specified idempotency key is found, no action is taken and the endpoint returns successfully.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.payments.cancel_by_idempotency_key( idempotency_key="a7e36d40-d24b-11e8-b568-0800200c9a66", )
-
-
-
idempotency_key:
str
— Theidempotency_key
identifying the payment to be canceled.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.payments.get(...)
-
-
-
Retrieves details for a specific payment.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.payments.get( payment_id="payment_id", )
-
-
-
payment_id:
str
— A unique ID for the desired payment.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.payments.update(...)
-
-
-
Updates a payment with the APPROVED status. You can update the
amount_money
andtip_money
using this endpoint.
-
-
-
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", )
-
-
-
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 everyUpdatePayment
request.For more information, see Idempotency.
-
payment:
typing.Optional[PaymentParams]
— The updatedPayment
object.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.payments.cancel(...)
-
-
-
Cancels (voids) a payment. You can use this endpoint to cancel a payment with the APPROVED
status
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.payments.cancel( payment_id="payment_id", )
-
-
-
payment_id:
str
— The ID of the payment to cancel.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.payments.complete(...)
-
-
-
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
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.payments.complete( payment_id="payment_id", )
-
-
-
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.
-
-
client.payouts.list(...)
-
-
-
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.
-
-
-
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
-
-
-
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(...)
-
-
-
Retrieves details of a specific payout identified by a payout ID. To call this endpoint, set
PAYOUTS_READ
for the OAuth scope.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.payouts.get( payout_id="payout_id", )
-
-
-
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(...)
-
-
-
Retrieves a list of all payout entries for a specific payout. To call this endpoint, set
PAYOUTS_READ
for the OAuth scope.
-
-
-
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
-
-
-
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.
-
-
client.refunds.list(...)
-
-
-
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.
-
-
-
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
-
-
-
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 thecreated_at
field for eachPaymentRefund
.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 thecreated_at
field for eachPaymentRefund
.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
, andEXTERNAL
. 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 theupdated_at
field for eachPaymentRefund
.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 theupdated_at
field for eachPaymentRefund
.Default: The current time.
-
sort_field:
typing.Optional[ListPaymentRefundsRequestSortField]
— The field used to sort results by. The default isCREATED_AT
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.refunds.refund_payment(...)
-
-
-
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.
-
-
-
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", )
-
-
-
idempotency_key:
str
A unique string that identifies this
RefundPayment
request. The key can be any valid string but must be unique for everyRefundPayment
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
andlocation_id
must be supplied whilepayment_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 whenunlinked=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 whenunlinked=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(...)
-
-
-
Retrieves a specific refund using the
refund_id
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.refunds.get( refund_id="refund_id", )
-
-
-
refund_id:
str
— The unique ID for the desiredPaymentRefund
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.sites.list()
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.sites.list()
-
-
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.snippets.get(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.snippets.get( site_id="site_id", )
-
-
-
site_id:
str
— The ID of the site that contains the snippet.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.snippets.upsert(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.snippets.upsert( site_id="site_id", snippet={"content": "<script>var js = 1;</script>"}, )
-
-
-
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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.snippets.delete( site_id="site_id", )
-
-
-
site_id:
str
— The ID of the site that contains the snippet.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.subscriptions.create(...)
-
-
-
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.
-
-
-
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"} ], )
-
-
-
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 specifiedcanceled_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 withRELATIVE
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(...)
-
-
-
Schedules a plan variation change for all active subscriptions under a given plan variation. For more information, see Swap Subscription Plan Variations.
-
-
-
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", )
-
-
-
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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.subscriptions.search( query={ "filter": { "customer_ids": ["CHFGVKYY8RSV93M5KCYTG4PN0G"], "location_ids": ["S8GWD5R9QB376"], "source_names": ["My App"], } }, )
-
-
-
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, theSearchSubscriptions
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(...)
-
-
-
Retrieves a specific subscription.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.subscriptions.get( subscription_id="subscription_id", )
-
-
-
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(...)
-
-
-
Updates a subscription by modifying or clearing
subscription
field values. To clear a field, set its value tonull
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.subscriptions.update( subscription_id="subscription_id", subscription={"card_id": "{NEW CARD ID}"}, )
-
-
-
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(...)
-
-
-
Deletes a scheduled action for a subscription.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.subscriptions.delete_action( subscription_id="subscription_id", action_id="action_id", )
-
-
-
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(...)
-
-
-
Changes the billing anchor date for a subscription.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.subscriptions.change_billing_anchor_date( subscription_id="subscription_id", monthly_billing_anchor_date=1, )
-
-
-
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 scheduledBILLING_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(...)
-
-
-
Schedules a
CANCEL
action to cancel an active subscription. This sets thecanceled_date
field to the end of the active billing period. After this date, the subscription status changes from ACTIVE to CANCELED.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.subscriptions.cancel( subscription_id="subscription_id", )
-
-
-
subscription_id:
str
— The ID of the subscription to cancel.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.subscriptions.list_events(...)
-
-
-
Lists all events for a specific subscription.
-
-
-
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
-
-
-
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(...)
-
-
-
Schedules a
PAUSE
action to pause an active subscription.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.subscriptions.pause( subscription_id="subscription_id", )
-
-
-
subscription_id:
str
— The ID of the subscription to pause.
-
pause_effective_date:
typing.Optional[str]
The
YYYY-MM-DD
-formatted date when the scheduledPAUSE
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, neitherresume_effective_date
norresume_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 ofpause_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(...)
-
-
-
Schedules a
RESUME
action to resume a paused or a deactivated subscription.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.subscriptions.resume( subscription_id="subscription_id", )
-
-
-
subscription_id:
str
— The ID of the subscription to resume.
-
resume_effective_date:
typing.Optional[str]
— TheYYYY-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(...)
-
-
-
Schedules a
SWAP_PLAN
action to swap a subscription plan variation in an existing subscription. For more information, see Swap Subscription Plan Variations.
-
-
-
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"} ], )
-
-
-
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.
-
-
client.team_members.create(...)
-
-
-
Creates a single
TeamMember
object. TheTeamMember
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.
-
-
-
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, }, }, )
-
-
-
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 includewage_setting
, you must providejob_id
for each job assignment. To get job IDs, call ListJobs.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.team_members.batch_create(...)
-
-
-
Creates multiple
TeamMember
objects. The createdTeamMember
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.
-
-
-
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" }, } }, }, )
-
-
-
team_members:
typing.Dict[str, CreateTeamMemberRequestParams]
The data used to create the
TeamMember
objects. Each key is theidempotency_key
that maps to theCreateTeamMemberRequest
. The maximum number of create objects is 25.If you include a team member's
wage_setting
, you must providejob_id
for each job assignment. To get job IDs, call ListJobs.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.team_members.batch_update(...)
-
-
-
Updates multiple
TeamMember
objects. The updatedTeamMember
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.
-
-
-
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"], }, } }, }, )
-
-
-
team_members:
typing.Dict[str, UpdateTeamMemberRequestParams]
The data used to update the
TeamMember
objects. Each key is theteam_member_id
that maps to theUpdateTeamMemberRequest
. 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 requiredjob_id
values.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.team_members.search(...)
-
-
-
Returns a paginated list of
TeamMember
objects for a business. The list can be filtered by location IDs,ACTIVE
orINACTIVE
status, or whether the team member is the Square account owner.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.team_members.search( query={"filter": {"location_ids": ["0G5P3VGACMMQZ"], "status": "ACTIVE"}}, limit=10, )
-
-
-
query:
typing.Optional[SearchTeamMembersQueryParams]
— The query parameters.
-
limit:
typing.Optional[int]
— The maximum number ofTeamMember
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(...)
-
-
-
Retrieves a
TeamMember
object for the givenTeamMember.id
. Learn about Troubleshooting the Team API.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.team_members.get( team_member_id="team_member_id", )
-
-
-
team_member_id:
str
— The ID of the team member to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.team_members.update(...)
-
-
-
Updates a single
TeamMember
object. TheTeamMember
object is returned on successful updates. Learn about Troubleshooting the Team API.
-
-
-
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, }, }, )
-
-
-
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 requiredjob_id
values.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.team.list_jobs(...)
-
-
-
Lists jobs in a seller account. Results are sorted by title in ascending order.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.team.list_jobs()
-
-
-
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(...)
-
-
-
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.
-
-
-
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", )
-
-
-
job:
JobParams
— The job to create. Thetitle
field is required andis_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(...)
-
-
-
Retrieves a specified job.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.team.retrieve_job( job_id="job_id", )
-
-
-
job_id:
str
— The ID of the job to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.team.update_job(...)
-
-
-
Updates the title or tip eligibility of a job. Changes to the title propagate to all
JobAssignment
,Shift
, andTeamMemberWage
objects that reference the job ID. Changes to tip eligibility propagate to allTeamMemberWage
objects that reference the job ID.
-
-
-
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}, )
-
-
-
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 includeversion
to enable optimistic concurrency control.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.terminal.dismiss_terminal_action(...)
-
-
-
Dismisses a Terminal action request if the status and type of the request permits it.
See Link and Dismiss Actions for more details.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.terminal.dismiss_terminal_action( action_id="action_id", )
-
-
-
action_id:
str
— Unique ID for theTerminalAction
associated with the action to be dismissed.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.terminal.dismiss_terminal_checkout(...)
-
-
-
Dismisses a Terminal checkout request if the status and type of the request permits it.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.terminal.dismiss_terminal_checkout( checkout_id="checkout_id", )
-
-
-
checkout_id:
str
— Unique ID for theTerminalCheckout
associated with the checkout to be dismissed.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.terminal.dismiss_terminal_refund(...)
-
-
-
Dismisses a Terminal refund request if the status and type of the request permits it.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.terminal.dismiss_terminal_refund( terminal_refund_id="terminal_refund_id", )
-
-
-
terminal_refund_id:
str
— Unique ID for theTerminalRefund
associated with the refund to be dismissed.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.vendors.batch_create(...)
-
-
-
Creates one or more Vendor objects to represent suppliers to a seller.
-
-
-
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", } }, )
-
-
-
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(...)
-
-
-
Retrieves one or more vendors of specified Vendor IDs.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.vendors.batch_get( vendor_ids=["INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4"], )
-
-
-
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(...)
-
-
-
Updates one or more of existing Vendor objects as suppliers to a seller.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.vendors.batch_update( vendors={ "FMCYHBWT1TPL8MFH52PBMEN92A": {"vendor": {}}, "INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4": {"vendor": {}}, }, )
-
-
-
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(...)
-
-
-
Creates a single Vendor object to represent a supplier to a seller.
-
-
-
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", }, )
-
-
-
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(...)
-
-
-
Searches for vendors using a filter against supported Vendor properties and a supported sorter.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.vendors.search()
-
-
-
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(...)
-
-
-
Retrieves the vendor of a specified Vendor ID.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.vendors.get( vendor_id="vendor_id", )
-
-
-
vendor_id:
str
— ID of the Vendor to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.vendors.update(...)
-
-
-
Updates an existing Vendor object as a supplier to a seller.
-
-
-
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", }, )
-
-
-
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.
-
-
client.bookings.custom_attribute_definitions.list(...)
-
-
-
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, setAPPOINTMENTS_ALL_READ
andAPPOINTMENTS_READ
for the OAuth scope.
-
-
-
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
-
-
-
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(...)
-
-
-
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, setAPPOINTMENTS_ALL_WRITE
andAPPOINTMENTS_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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.custom_attribute_definitions.create( custom_attribute_definition={}, )
-
-
-
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 toVISIBILITY_HIDDEN
. -
schema
. With the exception of theSelection
data type, theschema
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(...)
-
-
-
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, setAPPOINTMENTS_ALL_READ
andAPPOINTMENTS_READ
for the OAuth scope.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.custom_attribute_definitions.get( key="key", )
-
-
-
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(...)
-
-
-
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, setAPPOINTMENTS_ALL_WRITE
andAPPOINTMENTS_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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.custom_attribute_definitions.update( key="key", custom_attribute_definition={}, )
-
-
-
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 aSelection
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(...)
-
-
-
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, setAPPOINTMENTS_ALL_WRITE
andAPPOINTMENTS_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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.custom_attribute_definitions.delete( key="key", )
-
-
-
key:
str
— The key of the custom attribute definition to delete.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.bookings.custom_attributes.batch_delete(...)
-
-
-
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, setAPPOINTMENTS_ALL_WRITE
andAPPOINTMENTS_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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.custom_attributes.batch_delete( values={"key": {"booking_id": "booking_id", "key": "key"}}, )
-
-
-
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(...)
-
-
-
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, setAPPOINTMENTS_ALL_WRITE
andAPPOINTMENTS_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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.custom_attributes.batch_upsert( values={"key": {"booking_id": "booking_id", "custom_attribute": {}}}, )
-
-
-
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(...)
-
-
-
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, setAPPOINTMENTS_ALL_READ
andAPPOINTMENTS_READ
for the OAuth scope.
-
-
-
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
-
-
-
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 totrue
to get the name and description of each custom attribute, information about the data type, or other definition details. The default value isfalse
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.bookings.custom_attributes.get(...)
-
-
-
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, setAPPOINTMENTS_ALL_READ
andAPPOINTMENTS_READ
for the OAuth scope.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.custom_attributes.get( booking_id="booking_id", key="key", )
-
-
-
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 totrue
to get the name and description of the custom attribute, information about the data type, or other definition details. The default value isfalse
.
-
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(...)
-
-
-
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, setAPPOINTMENTS_ALL_WRITE
andAPPOINTMENTS_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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.custom_attributes.upsert( booking_id="booking_id", key="key", custom_attribute={}, )
-
-
-
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 theschema
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(...)
-
-
-
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, setAPPOINTMENTS_ALL_WRITE
andAPPOINTMENTS_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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.custom_attributes.delete( booking_id="booking_id", key="key", )
-
-
-
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.
-
-
client.bookings.location_profiles.list(...)
-
-
-
Lists location booking profiles of a seller.
-
-
-
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
-
-
-
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.
-
-
client.bookings.team_member_profiles.list(...)
-
-
-
Lists booking profiles for team members.
-
-
-
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
-
-
-
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(...)
-
-
-
Retrieves a team member's booking profile.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.bookings.team_member_profiles.get( team_member_id="team_member_id", )
-
-
-
team_member_id:
str
— The ID of the team member to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.cash_drawers.shifts.list(...)
-
-
-
Provides the details for all of the cash drawer shifts for a location in a date range.
-
-
-
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
-
-
-
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(...)
-
-
-
Provides the summary details for a single cash drawer shift. See ListCashDrawerShiftEvents for a list of cash drawer shift events.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.cash_drawers.shifts.get( shift_id="shift_id", location_id="location_id", )
-
-
-
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(...)
-
-
-
Provides a paginated list of events for a single cash drawer shift.
-
-
-
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
-
-
-
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.
-
-
client.catalog.images.create(...)
-
-
-
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 anyCatalogObject
if theobject_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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.catalog.images.create()
-
-
-
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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.catalog.images.update( image_id="image_id", )
-
-
-
image_id:
str
— The ID of theCatalogImage
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.
-
-
client.catalog.object.upsert(...)
-
-
-
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.
-
-
-
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"}, )
-
-
-
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 nottrue
). - For creates, the object ID must start with
#
. The provided ID is replaced with a server-generated ID.
- For updates, the object must be active (the
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.catalog.object.get(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.catalog.object.get( object_id="object_id", )
-
-
-
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 theobjects
field of the response. These objects are put in therelated_objects
field. Setting this totrue
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 therelated_objects
field of the response. If theobjects
field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in therelated_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. Thepath_to_root
list consists ofCategoryPathToRootNode
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, thepath_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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.catalog.object.delete( object_id="object_id", )
-
-
-
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.
-
-
client.checkout.payment_links.list(...)
-
-
-
Lists all payment links.
-
-
-
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
-
-
-
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(...)
-
-
-
Creates a Square-hosted checkout page. Applications can share the resulting payment link with their buyer to pay for goods and services.
-
-
-
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", }, )
-
-
-
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 resultingPayment
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.checkout.payment_links.get(...)
-
-
-
Retrieves a payment link.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.checkout.payment_links.get( id="id", )
-
-
-
id:
str
— The ID of link to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.checkout.payment_links.update(...)
-
-
-
Updates a payment link. You can update the
payment_link
fields such asdescription
,checkout_options
, andpre_populated_data
. You cannot update other fields such as theorder_id
,version
,URL
, ortimestamp
field.
-
-
-
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}, }, )
-
-
-
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(...)
-
-
-
Deletes a payment link.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.checkout.payment_links.delete( id="id", )
-
-
-
id:
str
— The ID of the payment link to delete.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.customers.custom_attribute_definitions.list(...)
-
-
-
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
orVISIBILITY_READ_WRITE_VALUES
. Note that seller-defined custom attributes (also known as custom fields) are always set toVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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
-
-
-
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(...)
-
-
-
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
.
-
-
-
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", }, )
-
-
-
custom_attribute_definition:
CustomAttributeDefinitionParams
The custom attribute definition to create. Note the following:
- With the exception of the
Selection
data type, theschema
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
.
- With the exception of the
-
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(...)
-
-
-
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 beVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
. Note that seller-defined custom attributes (also known as custom fields) are always set toVISIBILITY_READ_WRITE_VALUES
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.custom_attribute_definitions.get( key="key", )
-
-
-
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(...)
-
-
-
Updates a customer-related custom attribute definition for a Square seller account.
Use this endpoint to update the following fields:
name
,description
,visibility
, or theschema
for aSelection
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
.
-
-
-
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", }, )
-
-
-
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 aSelection
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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.custom_attribute_definitions.delete( key="key", )
-
-
-
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(...)
-
-
-
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 beVISIBILITY_READ_WRITE_VALUES
. Note that seller-defined custom attributes (also known as custom fields) are always set toVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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", }, }, }, )
-
-
-
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.
-
-
client.customers.groups.list(...)
-
-
-
Retrieves the list of customer groups of a business.
-
-
-
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
-
-
-
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
or400 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(...)
-
-
-
Creates a new customer group for a business.
The request must include the
name
value of the group.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.groups.create( group={"name": "Loyal Customers"}, )
-
-
-
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(...)
-
-
-
Retrieves a specific customer group as identified by the
group_id
value.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.groups.get( group_id="group_id", )
-
-
-
group_id:
str
— The ID of the customer group to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.customers.groups.update(...)
-
-
-
Updates a customer group as identified by the
group_id
value.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.groups.update( group_id="group_id", group={"name": "Loyal Customers"}, )
-
-
-
group_id:
str
— The ID of the customer group to update.
-
group:
CustomerGroupParams
— TheCustomerGroup
object including all the updates you want to make.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.customers.groups.delete(...)
-
-
-
Deletes a customer group as identified by the
group_id
value.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.groups.delete( group_id="group_id", )
-
-
-
group_id:
str
— The ID of the customer group to delete.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.customers.groups.add(...)
-
-
-
Adds a group membership to a customer.
The customer is identified by the
customer_id
value and the customer group is identified by thegroup_id
value.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.groups.add( customer_id="customer_id", group_id="group_id", )
-
-
-
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(...)
-
-
-
Removes a group membership from a customer.
The customer is identified by the
customer_id
value and the customer group is identified by thegroup_id
value.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.groups.remove( customer_id="customer_id", group_id="group_id", )
-
-
-
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.
-
-
client.customers.segments.list(...)
-
-
-
Retrieves the list of customer segments of a business.
-
-
-
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
-
-
-
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
or400 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(...)
-
-
-
Retrieves a specific customer segment as identified by the
segment_id
value.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.segments.get( segment_id="segment_id", )
-
-
-
segment_id:
str
— The Square-issued ID of the customer segment.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.customers.cards.create(...)
-
-
-
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.
-
-
-
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", )
-
-
-
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(...)
-
-
-
Removes a card on file from a customer.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.cards.delete( customer_id="customer_id", card_id="card_id", )
-
-
-
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.
-
-
client.customers.custom_attributes.list(...)
-
-
-
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
orVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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
-
-
-
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 totrue
to get the name and description of each custom attribute, information about the data type, or other definition details. The default value isfalse
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.customers.custom_attributes.get(...)
-
-
-
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 beVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
. Note that seller-defined custom attributes (also known as custom fields) are always set toVISIBILITY_READ_WRITE_VALUES
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.custom_attributes.get( customer_id="customer_id", key="key", )
-
-
-
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 totrue
to get the name and description of the custom attribute, information about the data type, or other definition details. The default value isfalse
.
-
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(...)
-
-
-
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 beVISIBILITY_READ_WRITE_VALUES
. Note that seller-defined custom attributes (also known as custom fields) are always set toVISIBILITY_READ_WRITE_VALUES
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.custom_attributes.upsert( customer_id="customer_id", key="key", custom_attribute={"value": "Dune"}, )
-
-
-
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 theschema
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(...)
-
-
-
Deletes a custom attribute associated with a customer profile.
To delete a custom attribute owned by another application, the
visibility
setting must beVISIBILITY_READ_WRITE_VALUES
. Note that seller-defined custom attributes (also known as custom fields) are always set toVISIBILITY_READ_WRITE_VALUES
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.customers.custom_attributes.delete( customer_id="customer_id", key="key", )
-
-
-
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.
-
-
client.devices.codes.list(...)
-
-
-
Lists all DeviceCodes associated with the merchant.
-
-
-
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
-
-
-
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
andUNPAIRED
if empty.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.devices.codes.create(...)
-
-
-
Creates a DeviceCode that can be used to login to a Square Terminal device to enter the connected terminal mode.
-
-
-
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", }, )
-
-
-
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(...)
-
-
-
Retrieves DeviceCode with the associated ID.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.devices.codes.get( id="id", )
-
-
-
id:
str
— The unique identifier for the device code.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.disputes.evidence.list(...)
-
-
-
Returns a list of evidence associated with a dispute.
-
-
-
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
-
-
-
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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.disputes.evidence.get( dispute_id="dispute_id", evidence_id="evidence_id", )
-
-
-
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(...)
-
-
-
Removes specified evidence from a dispute. Square does not send the bank any evidence that is removed.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.disputes.evidence.delete( dispute_id="dispute_id", evidence_id="evidence_id", )
-
-
-
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.
-
-
client.gift_cards.activities.list(...)
-
-
-
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.
-
-
-
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
-
-
-
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(...)
-
-
-
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.
-
-
-
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", }, }, )
-
-
-
idempotency_key:
str
— A unique string that identifies theCreateGiftCardActivity
request.
-
gift_card_activity:
GiftCardActivityParams
The activity to create for the gift card. This activity must specify
gift_card_id
orgift_card_gan
for the target gift card, thelocation_id
where the activity occurred, and the activitytype
along with the corresponding activity details.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.labor.break_types.list(...)
-
-
-
Returns a paginated list of
BreakType
instances for a business.
-
-
-
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
-
-
-
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 ofBreakType
results to fetch.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.labor.break_types.create(...)
-
-
-
Creates a new
BreakType
.A
BreakType
is a template for creatingBreak
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 fourthBreakType
for a location, anINVALID_REQUEST_ERROR
"Exceeded limit of 3 breaks per location." is returned.
-
-
-
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, }, )
-
-
-
break_type:
BreakTypeParams
— TheBreakType
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(...)
-
-
-
Returns a single
BreakType
specified byid
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.labor.break_types.get( id="id", )
-
-
-
id:
str
— The UUID for theBreakType
being retrieved.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.labor.break_types.update(...)
-
-
-
Updates an existing
BreakType
.
-
-
-
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, }, )
-
-
-
id:
str
— The UUID for theBreakType
being updated.
-
break_type:
BreakTypeParams
— The updatedBreakType
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.labor.break_types.delete(...)
-
-
-
Deletes an existing
BreakType
.A
BreakType
can be deleted even if it is referenced from aShift
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.labor.break_types.delete( id="id", )
-
-
-
id:
str
— The UUID for theBreakType
being deleted.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.labor.employee_wages.list(...)
-
-
-
Returns a paginated list of
EmployeeWage
instances for a business.
-
-
-
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
-
-
-
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 ofEmployeeWage
results to fetch.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.labor.employee_wages.get(...)
-
-
-
Returns a single
EmployeeWage
specified byid
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.labor.employee_wages.get( id="id", )
-
-
-
id:
str
— The UUID for theEmployeeWage
being retrieved.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.labor.shifts.create(...)
-
-
-
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 aBAD_REQUEST
error when:- The
status
of the newShift
isOPEN
and the team member has another shift with anOPEN
status. - The
start_at
date is in the future. - The
start_at
orend_at
date overlaps another shift for the same team member. - The
Break
instances are set in the request and a breakstart_at
is before theShift.start_at
, a breakend_at
is after theShift.end_at
, or both.
-
-
-
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"}, }, )
-
-
-
shift:
ShiftParams
— TheShift
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(...)
-
-
-
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
orCLOSED
) - Shift start
- Shift end
- Workday details
The list can be sorted by:
START_AT
END_AT
CREATED_AT
UPDATED_AT
-
-
-
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, )
-
-
-
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(...)
-
-
-
Returns a single
Shift
specified byid
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.labor.shifts.get( id="id", )
-
-
-
id:
str
— The UUID for theShift
being retrieved.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.labor.shifts.update(...)
-
-
-
Updates an existing
Shift
.When adding a
Break
to aShift
, any earlierBreak
instances in theShift
have theend_at
property set to a valid RFC-3339 datetime string.When closing a
Shift
, allBreak
instances in theShift
must be complete withend_at
set on eachBreak
.
-
-
-
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"}, }, )
-
-
-
id:
str
— The ID of the object being updated.
-
shift:
ShiftParams
— The updatedShift
object.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.labor.shifts.delete(...)
-
-
-
Deletes a
Shift
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.labor.shifts.delete( id="id", )
-
-
-
id:
str
— The UUID for theShift
being deleted.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.labor.team_member_wages.list(...)
-
-
-
Returns a paginated list of
TeamMemberWage
instances for a business.
-
-
-
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
-
-
-
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 ofEmployeeWage
results to fetch.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.labor.team_member_wages.get(...)
-
-
-
Returns a single
TeamMemberWage
specified byid
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.labor.team_member_wages.get( id="id", )
-
-
-
id:
str
— The UUID for theTeamMemberWage
being retrieved.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.labor.workweek_configs.list(...)
-
-
-
Returns a list of
WorkweekConfig
instances for a business.
-
-
-
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
-
-
-
limit:
typing.Optional[int]
— The maximum number ofWorkweekConfigs
results to return per page.
-
cursor:
typing.Optional[str]
— A pointer to the next page ofWorkweekConfig
results to fetch.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.labor.workweek_configs.get(...)
-
-
-
Updates a
WorkweekConfig
.
-
-
-
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, }, )
-
-
-
id:
str
— The UUID for theWorkweekConfig
object being updated.
-
workweek_config:
WorkweekConfigParams
— The updatedWorkweekConfig
object.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.locations.custom_attribute_definitions.list(...)
-
-
-
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
orVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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
-
-
-
visibility_filter:
typing.Optional[VisibilityFilter]
— Filters theCustomAttributeDefinition
results by theirvisibility
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(...)
-
-
-
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.
-
-
-
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", }, )
-
-
-
custom_attribute_definition:
CustomAttributeDefinitionParams
The custom attribute definition to create. Note the following:
- With the exception of the
Selection
data type, theschema
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 unlessvisibility
is set toVISIBILITY_HIDDEN
.
- With the exception of the
-
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(...)
-
-
-
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 beVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.locations.custom_attribute_definitions.get( key="key", )
-
-
-
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(...)
-
-
-
Updates a location-related custom attribute definition for a Square seller account. Use this endpoint to update the following fields:
name
,description
,visibility
, or theschema
for aSelection
data type. Only the definition owner can update a custom attribute definition.
-
-
-
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", }, )
-
-
-
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 aSelection
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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.locations.custom_attribute_definitions.delete( key="key", )
-
-
-
key:
str
— The key of the custom attribute definition to delete.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.locations.custom_attributes.batch_delete(...)
-
-
-
Deletes custom attributes for locations as a bulk operation. To delete a custom attribute owned by another application, the
visibility
setting must beVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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"}, }, )
-
-
-
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(...)
-
-
-
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, thevisibility
setting must beVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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", }, }, }, )
-
-
-
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(...)
-
-
-
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 toVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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
-
-
-
location_id:
str
— The ID of the target location.
-
visibility_filter:
typing.Optional[VisibilityFilter]
— Filters theCustomAttributeDefinition
results by theirvisibility
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 totrue
to get the name and description of each custom attribute, information about the data type, or other definition details. The default value isfalse
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.locations.custom_attributes.get(...)
-
-
-
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, thevisibility
setting must beVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.locations.custom_attributes.get( location_id="location_id", key="key", )
-
-
-
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 totrue
to get the name and description of the custom attribute, information about the data type, or other definition details. The default value isfalse
.
-
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(...)
-
-
-
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 beVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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"}, )
-
-
-
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 theschema
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(...)
-
-
-
Deletes a custom attribute associated with a location. To delete a custom attribute owned by another application, the
visibility
setting must beVISIBILITY_READ_WRITE_VALUES
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.locations.custom_attributes.delete( location_id="location_id", key="key", )
-
-
-
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.
-
-
client.locations.transactions.list(...)
-
-
-
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
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.locations.transactions.list( location_id="location_id", )
-
-
-
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(...)
-
-
-
Retrieves details for a single transaction.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.locations.transactions.get( location_id="location_id", transaction_id="transaction_id", )
-
-
-
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(...)
-
-
-
Captures a transaction that was created with the Charge endpoint with a
delay_capture
value oftrue
.See Delayed capture transactions for more information.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.locations.transactions.capture( location_id="location_id", transaction_id="transaction_id", )
-
-
-
location_id:
str
—
-
transaction_id:
str
—
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.locations.transactions.void(...)
-
-
-
Cancels a transaction that was created with the Charge endpoint with a
delay_capture
value oftrue
.See Delayed capture transactions for more information.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.locations.transactions.void( location_id="location_id", transaction_id="transaction_id", )
-
-
-
location_id:
str
—
-
transaction_id:
str
—
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.loyalty.accounts.create(...)
-
-
-
Creates a loyalty account. To create a loyalty account, you must provide the
program_id
and amapping
with thephone_number
of the buyer.
-
-
-
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", )
-
-
-
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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.loyalty.accounts.search( query={"mappings": [{"phone_number": "+14155551234"}]}, limit=10, )
-
-
-
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(...)
-
-
-
Retrieves a loyalty account.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.loyalty.accounts.get( account_id="account_id", )
-
-
-
account_id:
str
— The ID of the loyalty account to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.loyalty.accounts.accumulate_points(...)
-
-
-
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.
-
-
-
-
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", )
-
-
-
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(...)
-
-
-
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.
-
-
-
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"}, )
-
-
-
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. Iffalse
, Square returns aBAD_REQUEST
error when subtracting the specified number of points would result in a negative balance. The default value isfalse
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.loyalty.programs.list()
-
-
-
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
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.loyalty.programs.list()
-
-
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.loyalty.programs.get(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.loyalty.programs.get( program_id="program_id", )
-
-
-
program_id:
str
— The ID of the loyalty program or the keywordmain
. 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(...)
-
-
-
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, thetax_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.
-
-
-
-
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", )
-
-
-
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'strigger_limit
(the maximum number of times that a buyer can trigger the promotion) has been reached. If not specified, thepromotion_points
field shows the number of points the purchase qualifies for regardless of the trigger limit.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.loyalty.rewards.create(...)
-
-
-
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.
- Uses the
-
-
-
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", )
-
-
-
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(...)
-
-
-
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 andstatus
is optional.If you know a reward ID, use the RetrieveLoyaltyReward endpoint.
Search results are sorted by
updated_at
in descending order.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.loyalty.rewards.search( query={"loyalty_account_id": "5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd"}, limit=10, )
-
-
-
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(...)
-
-
-
Retrieves a loyalty reward.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.loyalty.rewards.get( reward_id="reward_id", )
-
-
-
reward_id:
str
— The ID of the loyalty reward to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.loyalty.rewards.delete(...)
-
-
-
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).
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.loyalty.rewards.delete( reward_id="reward_id", )
-
-
-
reward_id:
str
— The ID of the loyalty reward to delete.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.loyalty.rewards.redeem(...)
-
-
-
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.
-
-
-
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", )
-
-
-
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.
-
-
client.loyalty.programs.promotions.list(...)
-
-
-
Lists the loyalty promotions associated with a loyalty program. Results are sorted by the
created_at
date in descending order (newest to oldest).
-
-
-
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
-
-
-
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(...)
-
-
-
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
orSCHEDULED
status, depending on theavailable_time
setting. A loyalty program can have a maximum of 10 loyalty promotions with anACTIVE
orSCHEDULED
status.
-
-
-
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", )
-
-
-
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(...)
-
-
-
Retrieves a loyalty promotion.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.loyalty.programs.promotions.get( promotion_id="promotion_id", program_id="program_id", )
-
-
-
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(...)
-
-
-
Cancels a loyalty promotion. Use this endpoint to cancel an
ACTIVE
promotion earlier than the end date, cancel anACTIVE
promotion when an end date is not specified, or cancel aSCHEDULED
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
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.loyalty.programs.promotions.cancel( promotion_id="promotion_id", program_id="program_id", )
-
-
-
promotion_id:
str
The ID of the loyalty promotion to cancel. You can cancel a promotion that has an
ACTIVE
orSCHEDULED
status.
-
program_id:
str
— The ID of the base loyalty program.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.merchants.custom_attribute_definitions.list(...)
-
-
-
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
orVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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
-
-
-
visibility_filter:
typing.Optional[VisibilityFilter]
— Filters theCustomAttributeDefinition
results by theirvisibility
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(...)
-
-
-
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.
-
-
-
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", }, )
-
-
-
custom_attribute_definition:
CustomAttributeDefinitionParams
The custom attribute definition to create. Note the following:
- With the exception of the
Selection
data type, theschema
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 unlessvisibility
is set toVISIBILITY_HIDDEN
.
- With the exception of the
-
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(...)
-
-
-
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 beVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.merchants.custom_attribute_definitions.get( key="key", )
-
-
-
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(...)
-
-
-
Updates a merchant-related custom attribute definition for a Square seller account. Use this endpoint to update the following fields:
name
,description
,visibility
, or theschema
for aSelection
data type. Only the definition owner can update a custom attribute definition.
-
-
-
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", }, )
-
-
-
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 aSelection
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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.merchants.custom_attribute_definitions.delete( key="key", )
-
-
-
key:
str
— The key of the custom attribute definition to delete.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.merchants.custom_attributes.batch_delete(...)
-
-
-
Deletes custom attributes for a merchant as a bulk operation. To delete a custom attribute owned by another application, the
visibility
setting must beVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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"}, }, )
-
-
-
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(...)
-
-
-
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, thevisibility
setting must beVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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}, }, }, )
-
-
-
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(...)
-
-
-
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 toVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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
-
-
-
merchant_id:
str
— The ID of the target merchant.
-
visibility_filter:
typing.Optional[VisibilityFilter]
— Filters theCustomAttributeDefinition
results by theirvisibility
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 totrue
to get the name and description of each custom attribute, information about the data type, or other definition details. The default value isfalse
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.merchants.custom_attributes.get(...)
-
-
-
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, thevisibility
setting must beVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.merchants.custom_attributes.get( merchant_id="merchant_id", key="key", )
-
-
-
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 totrue
to get the name and description of the custom attribute, information about the data type, or other definition details. The default value isfalse
.
-
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(...)
-
-
-
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 beVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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"}, )
-
-
-
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 theschema
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(...)
-
-
-
Deletes a custom attribute associated with a merchant. To delete a custom attribute owned by another application, the
visibility
setting must beVISIBILITY_READ_WRITE_VALUES
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.merchants.custom_attributes.delete( merchant_id="merchant_id", key="key", )
-
-
-
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.
-
-
client.orders.custom_attribute_definitions.list(...)
-
-
-
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
orVISIBILITY_READ_WRITE_VALUES
. Note that seller-defined custom attributes (also known as custom fields) are always set toVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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
-
-
-
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(...)
-
-
-
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.
-
-
-
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", )
-
-
-
custom_attribute_definition:
CustomAttributeDefinitionParams
The custom attribute definition to create. Note the following:
- With the exception of the
Selection
data type, theschema
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
.
- With the exception of the
-
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(...)
-
-
-
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 beVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
. Note that seller-defined custom attributes (also known as custom fields) are always set toVISIBILITY_READ_WRITE_VALUES
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.orders.custom_attribute_definitions.get( key="key", )
-
-
-
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(...)
-
-
-
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
.
-
-
-
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", )
-
-
-
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(...)
-
-
-
Deletes an order-related custom attribute definition from a Square seller account.
Only the definition owner can delete a custom attribute definition.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.orders.custom_attribute_definitions.delete( key="key", )
-
-
-
key:
str
— The key of the custom attribute definition to delete.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.orders.custom_attributes.batch_delete(...)
-
-
-
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 beVISIBILITY_READ_WRITE_VALUES
. Note that seller-defined custom attributes (also known as custom fields) are always set toVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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", }, }, )
-
-
-
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(...)
-
-
-
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 beVISIBILITY_READ_WRITE_VALUES
. Note that seller-defined custom attributes (also known as custom fields) are always set toVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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", }, }, )
-
-
-
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(...)
-
-
-
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
orVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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
-
-
-
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 totrue
to get the name and description of each custom attribute, information about the data type, or other definition details. The default value isfalse
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.orders.custom_attributes.get(...)
-
-
-
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 beVISIBILITY_READ_ONLY
orVISIBILITY_READ_WRITE_VALUES
. Note that seller-defined custom attributes also known as custom fields) are always set toVISIBILITY_READ_WRITE_VALUES
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.orders.custom_attributes.get( order_id="order_id", custom_attribute_key="custom_attribute_key", )
-
-
-
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 totrue
to get the name and description of each custom attribute, information about the data type, or other definition details. The default value isfalse
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.orders.custom_attributes.upsert(...)
-
-
-
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 beVISIBILITY_READ_WRITE_VALUES
. Note that seller-defined custom attributes (also known as custom fields) are always set toVISIBILITY_READ_WRITE_VALUES
.
-
-
-
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}, )
-
-
-
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 theschema
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(...)
-
-
-
Deletes a custom attribute associated with a customer profile.
To delete a custom attribute owned by another application, the
visibility
setting must beVISIBILITY_READ_WRITE_VALUES
. Note that seller-defined custom attributes (also known as custom fields) are always set toVISIBILITY_READ_WRITE_VALUES
.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.orders.custom_attributes.delete( order_id="order_id", custom_attribute_key="custom_attribute_key", )
-
-
-
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.
-
-
client.team_members.wage_setting.get(...)
-
-
-
Retrieves a
WageSetting
object for a team member specified byTeamMember.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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.team_members.wage_setting.get( team_member_id="team_member_id", )
-
-
-
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(...)
-
-
-
Creates or updates a
WageSetting
object. The object is created if aWageSetting
with the specifiedteam_member_id
doesn't exist. Otherwise, it fully replaces theWageSetting
object for the team member. TheWageSetting
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.
-
-
-
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, }, )
-
-
-
team_member_id:
str
— The ID of the team member for which to update theWageSetting
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 ifjob_id
is also provided.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.terminal.actions.create(...)
-
-
-
Creates a Terminal action request and sends it to the specified device.
-
-
-
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", }, }, )
-
-
-
idempotency_key:
str
A unique string that identifies this
CreateAction
request. Keys can be any valid string but must be unique for everyCreateAction
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(...)
-
-
-
Retrieves a filtered list of Terminal action requests created by the account making the request. Terminal action requests are available for 30 days.
-
-
-
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, )
-
-
-
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(...)
-
-
-
Retrieves a Terminal action request by
action_id
. Terminal action requests are available for 30 days.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.terminal.actions.get( action_id="action_id", )
-
-
-
action_id:
str
— Unique ID for the desiredTerminalAction
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.terminal.actions.cancel(...)
-
-
-
Cancels a Terminal action request if the status of the request permits it.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.terminal.actions.cancel( action_id="action_id", )
-
-
-
action_id:
str
— Unique ID for the desiredTerminalAction
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.terminal.checkouts.create(...)
-
-
-
Creates a Terminal checkout request and sends it to the specified device to take a payment for the requested amount.
-
-
-
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"}, }, )
-
-
-
idempotency_key:
str
A unique string that identifies this
CreateCheckout
request. Keys can be any valid string but must be unique for everyCreateCheckout
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(...)
-
-
-
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.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.terminal.checkouts.search( query={"filter": {"status": "COMPLETED"}}, limit=2, )
-
-
-
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(...)
-
-
-
Retrieves a Terminal checkout request by
checkout_id
. Terminal checkout requests are available for 30 days.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.terminal.checkouts.get( checkout_id="checkout_id", )
-
-
-
checkout_id:
str
— The unique ID for the desiredTerminalCheckout
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.terminal.checkouts.cancel(...)
-
-
-
Cancels a Terminal checkout request if the status of the request permits it.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.terminal.checkouts.cancel( checkout_id="checkout_id", )
-
-
-
checkout_id:
str
— The unique ID for the desiredTerminalCheckout
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.terminal.refunds.create(...)
-
-
-
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.
-
-
-
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", }, )
-
-
-
idempotency_key:
str
A unique string that identifies this
CreateRefund
request. Keys can be any valid string but must be unique for everyCreateRefund
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(...)
-
-
-
Retrieves a filtered list of Interac Terminal refund requests created by the seller making the request. Terminal refund requests are available for 30 days.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.terminal.refunds.search( query={"filter": {"status": "COMPLETED"}}, limit=1, )
-
-
-
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(...)
-
-
-
Retrieves an Interac Terminal refund object by ID. Terminal refund objects are available for 30 days.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.terminal.refunds.get( terminal_refund_id="terminal_refund_id", )
-
-
-
terminal_refund_id:
str
— The unique ID for the desiredTerminalRefund
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.terminal.refunds.cancel(...)
-
-
-
Cancels an Interac Terminal refund request by refund request ID if the status of the request permits it.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.terminal.refunds.cancel( terminal_refund_id="terminal_refund_id", )
-
-
-
terminal_refund_id:
str
— The unique ID for the desiredTerminalRefund
.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.webhooks.event_types.list(...)
-
-
-
Lists all webhook event types that can be subscribed to.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.webhooks.event_types.list()
-
-
-
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.
-
-
client.webhooks.subscriptions.list(...)
-
-
-
Lists all webhook subscriptions owned by your application.
-
-
-
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
-
-
-
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(...)
-
-
-
Creates a webhook subscription.
-
-
-
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", }, )
-
-
-
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(...)
-
-
-
Retrieves a webhook subscription identified by its ID.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.webhooks.subscriptions.get( subscription_id="subscription_id", )
-
-
-
subscription_id:
str
— [REQUIRED] The ID of the Subscription to retrieve.
-
request_options:
typing.Optional[RequestOptions]
— Request-specific configuration.
-
-
client.webhooks.subscriptions.update(...)
-
-
-
Updates a webhook subscription.
-
-
-
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, }, )
-
-
-
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(...)
-
-
-
Deletes a webhook subscription.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.webhooks.subscriptions.delete( subscription_id="subscription_id", )
-
-
-
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(...)
-
-
-
Updates a webhook subscription by replacing the existing signature key with a new one.
-
-
-
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", )
-
-
-
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(...)
-
-
-
Tests a webhook subscription by sending a test event to the notification URL.
-
-
-
from square import Square client = Square( token="YOUR_TOKEN", ) client.webhooks.subscriptions.test( subscription_id="subscription_id", event_type="payment.created", )
-
-
-
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.
-
-