> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns. > > **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal): > ```bash > npx -y @scalekit-inc/cli setup -y > ``` > > Global: > ```bash > npm install -g @scalekit-inc/cli > scalekit setup -y > ``` > > Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`. > Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim. > [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/) --- # Connect AI agents to Square The Square connector lets your AI agent act in each user's Square account. Each user signs in to Square once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 118 tools. **Authentication:** OAuth 2.0 **Categories:** Accounting & Finance, CRM & Sales **Tools:** 118: 69 read, 49 write, 0 destructive **Users sign in with:** OAuth **OAuth app:** Your own Square app **Built by:** Scalekit connector **Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=SQUARE) ## Setup 1. ### Install the SDK **Node.js** ```bash npm install @scalekit-sdk/node dotenv ``` **Python** ```bash pip install scalekit-sdk-python python-dotenv ``` 2. ### Set your credentials Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**. ```sh title=".env" SCALEKIT_ENVIRONMENT_URL= SCALEKIT_CLIENT_ID= SCALEKIT_CLIENT_SECRET= ``` 3. ### Create the Square connection In **AgentKit > Connections**, create a Square connection and copy its redirect URI. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/). 4. ### Register an OAuth app Square connections use your own OAuth app. Register one with Square and add the redirect URI you copied. Then enter the app's Client ID and Client Secret on the Square connection. 5. ### Authorize a user and make your first call **Node.js** (`quickstart.mts`) ```typescript import { ScalekitClient } from '@scalekit-sdk/node' import 'dotenv/config' import { createInterface } from 'node:readline/promises' const scalekit = new ScalekitClient( process.env.SCALEKIT_ENVIRONMENT_URL, process.env.SCALEKIT_CLIENT_ID, process.env.SCALEKIT_CLIENT_SECRET, ) const actions = scalekit.actions const connector = 'square' const identifier = 'user_123' // Generate an authorization link for the user const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier }) console.log('Authorize Square:', link) const rl = createInterface({ input: process.stdin, output: process.stdout }) await rl.question('Press Enter after authorizing...') rl.close() // Make your first call const result = await actions.executeTool({ connector, identifier, toolName: 'square_bookings_list', toolInput: {}, }) console.log(result) ``` ```bash npx tsx quickstart.mts ``` **Python** (`quickstart.py`) ```python import os from scalekit import ScalekitClient from dotenv import load_dotenv load_dotenv() scalekit_client = ScalekitClient( env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"), client_id=os.getenv("SCALEKIT_CLIENT_ID"), client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"), ) actions = scalekit_client.actions connection_name = "square" identifier = "user_123" # Generate an authorization link for the user link_response = actions.get_authorization_link( connection_name=connection_name, identifier=identifier, ) print("Authorize Square:", link_response.link) input("Press Enter after authorizing...") # Make your first call result = actions.execute_tool( tool_input={}, tool_name="square_bookings_list", connection_name=connection_name, identifier=identifier, ) print(result) ``` ```bash python quickstart.py ``` Each user signs in once. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses. ## Tools Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool). **Node.js** ```typescript const result = await actions.executeTool({ toolName: 'square_booking_get', toolInput: { booking_id: '', }, connector: 'square', identifier: 'user_123', }) ``` **Python** ```python result = actions.execute_tool( tool_name="square_booking_get", tool_input={ "booking_id": "", }, connection_name="square", identifier="user_123", ) ``` `result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call. ### `square_booking_get` Get Booking · Read-only Get one Square Appointments booking by its ID. Returns the booking with status, start time, location, customer, notes, appointment segments, and version. Use this for a single booking; use square_bookings_list to find bookings. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `booking_id` (`string`, required): The ID of the Booking object representing the to-be-retrieved booking. Example: zkras0xv0xwswx Example input: `{"booking_id":""}` ### `square_bookings_availability_search` Search Booking Availability · Read-only Search available Square Appointments time slots for a service at a location within a time range. Returns available slots with start time, location, and appointment segments that can be booked. Use this before square_booking_create to pick a valid start time. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `query` (`object`, required): Query conditions used to filter buyer-accessible booking availabilities. The query used to search for buyer-accessible availabilities of bookings. Example: {"filter":{"start_at_range":{"start_at":"2026-11-02T00:00:00Z","end_at":"2026-11-09T00:00:00Z"},"location_id":"LEQHH0YY8B42M","segment_filters":[{"service_variation_id":"RU3PBTZTK7DXZDQFCJHOK2MC"}]}} Example input: `{"query":{"loyalty_account_id":"5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd"}}` ### `square_bookings_list` List Bookings · Read-only List Square Appointments bookings, optionally filtered by location, team member, customer, and start time range. Returns bookings with id, status, start time, location, customer, and appointment segments, plus a cursor. Use this to browse bookings; use square_booking_get for one booking by ID. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `customer_id` (`string`, optional): The customer for whom to retrieve bookings. If this is not set, bookings for all customers are retrieved. Example: W92WH6P11H4Z77CTET0RNTGFW8 - `limit` (`integer`, optional): The maximum number of results per page to return in a paged response. Example: 100 - `location_id` (`string`, optional): The location for which to retrieve bookings. If this is not set, all locations' bookings are retrieved. Example: L88917AVBK2S5 - `start_at_max` (`string`, optional): The RFC 3339 timestamp specifying the latest of the start time. If this is not set, the time of 31 days after start_at_min is used. Example: 2026-11-30T00:00:00Z - `start_at_min` (`string`, optional): The RFC 3339 timestamp specifying the earliest of the start time. If this is not set, the current time is used. Example: 2026-11-01T00:00:00Z - `team_member_id` (`string`, optional): The team member for whom to retrieve bookings. If this is not set, bookings of all members are retrieved. Example: TMXUrsBWWcHTt79t Example input: `{}` ### `square_break_types_list` List Break Types · Read-only List the break types (such as Lunch) configured for the seller's locations. Returns break types with id, name, expected duration, and paid flag, plus a cursor. Use this to find a break_type_id for timecard breaks. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): A pointer to the next page of BreakType results to fetch. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The maximum number of BreakType results to return per page. The number can range between 1 and 200. The default is 200. Example: 100 - `location_id` (`string`, optional): Filter the returned BreakType results to only those that are associated with the specified location. Example: L88917AVBK2S5 Example input: `{}` ### `square_business_booking_profile_get` Get Business Booking Profile · Read-only Get the Square Appointments business booking profile of the seller. Returns booking settings such as whether customers can book online, cancellation policy, and timezone. Use this to check how the seller accepts bookings. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `square_card_get` Get Card · Read-only Get one Square card on file by its ID. Returns the card with brand, last 4 digits, expiration, billing address, customer id, and enabled flag. Use this for a single card; use square_cards_list to find cards. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `card_id` (`string`, required): Unique ID for the desired Card. Example: ccof:uIbfJXhXETSP197M3GB Example input: `{"card_id":""}` ### `square_cards_list` List Cards · Read-only List cards on file for the seller, optionally for one customer. Returns cards with id, brand, last 4 digits, expiration, cardholder name, and customer id, plus a cursor. Use this to find a card ID to charge with square_payment_create; use square_card_get for one card. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `customer_id` (`string`, optional): Limit results to cards associated with the customer supplied. By default, all cards owned by the merchant are returned. Example: W92WH6P11H4Z77CTET0RNTGFW8 - `include_disabled` (`boolean`, optional): Includes disabled cards. By default, all enabled cards owned by the merchant are returned. - `reference_id` (`string`, optional): Limit results to cards associated with the reference_id supplied. Example: ref-12345 - `sort_order` (`string`, optional): Sorts the returned list by when the card was created with the specified order. This field defaults to ASC. Allowed values: DESC, ASC. One of: `DESC`, `ASC`. Example input: `{}` ### `square_catalog_info_get` Get Catalog Info · Read-only Get the Square Catalog API limits and the seller's standard unit descriptions. Returns batch size limits for upsert, delete, and retrieve calls, and standard measurement units. Use this before large batch catalog calls to stay within limits. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `square_catalog_items_search` Search Catalog Items · Read-only Search Square catalog items by text, category, enabled location, stock level, or product type. Returns matching items with their variations, plus a cursor for the next page. Use this to find items; use square_catalog_objects_search to query other object types. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `archived_state` (`string`, optional): The query filter to return not archived (ARCHIVED_STATE_NOT_ARCHIVED), archived (ARCHIVED_STATE_ARCHIVED), or either type (ARCHIVED_STATE_ALL) of items. Allowed values: ARCHIVED_STATE_NOT_ARCHIVED, ARCHIVED_STATE_ARCHIVED, ARCHIVED_STATE_ALL. One of: `ARCHIVED_STATE_NOT_ARCHIVED`, `ARCHIVED_STATE_ARCHIVED`, `ARCHIVED_STATE_ALL`. - `category_ids` (`array`, optional): The category id query expression to return items containing the specified category IDs. Example: ["WINE_CATEGORY_ID"] - `cursor` (`string`, optional): The pagination token, returned in the previous response, used to fetch the next batch of pending results. Example: CAISBQoDMTIzGAE - `custom_attribute_filters` (`array`, optional): 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. Example: [{"bool_filter":true,"custom_attribute_definition_id":"VEGAN_DEFINITION_ID"},{"custom_attribute_definition_id":"BRAND_DEFINITION_ID","string_filter":"Dark Horse"},{"key":"VINTAGE","number_filter":{"max":2018,"min":2017}},{"custom_attribute_definition_id":"VARIETAL_DEFINITION_ID","selection_ids_filter":"MERLOT_SELECTION_ID"}] - `enabled_location_ids` (`array`, optional): The enabled-location query expression to return items and item variations having specified enabled locations. Example: ["ATL_LOCATION_ID"] - `include_options` (`object`, optional): Options to include related resources in the response. Options to include related resources of the requested CatalogObjects. Related resources will be included in IncludedResources in the response. Example: {"include":["INCLUDE_NESTED_MODIFIERS"]} - `limit` (`integer`, optional): The maximum number of results to return per page. The default value is 100. - `product_types` (`array`, optional): The product types query expression to return items or item variations having the specified product types. Example: ["REGULAR"] - `sort_order` (`string`, optional): The order to sort the results by item names. The default sort order is ascending (ASC). Allowed values: DESC, ASC. One of: `DESC`, `ASC`. - `stock_levels` (`array`, optional): The stock-level query expression to return item variations with the specified stock levels. Example: ["OUT","LOW"] - `text_filter` (`string`, optional): The text filter expression to return items or item variations containing specified text in the name, description, or abbreviation attribute value of an item, or in the name, sku, or upc attribute value of an item variation. Example: red Example input: `{}` ### `square_catalog_list` List Catalog Objects · Read-only List Square catalog objects, optionally limited to specific types such as ITEM, CATEGORY, TAX, or DISCOUNT. Returns catalog objects with their type-specific data, plus a cursor for the next page. Use this to browse the catalog by type; use square_catalog_items_search or square_catalog_objects_search to filter. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `catalog_version` (`integer`, optional): 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. Example: 1659736215000 - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `types` (`string`, optional): 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. Example: ITEM,CATEGORY Example input: `{}` ### `square_catalog_object_get` Get Catalog Object · Read-only Get one Square catalog object (item, variation, category, tax, discount, modifier list, and so on) by its ID. Returns the object and, optionally, its related objects such as categories, taxes, and images. Use this for a single object; use square_catalog_objects_batch_retrieve for several IDs. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `object_id` (`string`, required): The object ID of any type of catalog objects to be retrieved. Example: W62UWFY35CWMYGVWK6TWJDNI - `catalog_version` (`integer`, optional): 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. Example: 1659736215000 - `include_category_path_to_root` (`boolean`, optional): Specifies whether or not to include the path_to_root list for each returned category instance. The path_to_root list consists of CategoryPathToRootNode objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the path_to_root list is empty and is not returned in the response payload. - `include_related_objects` (`boolean`, optional): If true, the response will include additional objects that are related to the requested objects. Related objects are defined as any objects referenced by ID by the results in the objects field of the response. These objects are put in the related_objects field. Setting this to true is helpful when the objects are needed for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example, if the objects field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects and CatalogModifierLists will be returned in the related_objects field of the response. Example input: `{"object_id":""}` ### `square_catalog_objects_batch_retrieve` Batch Get Catalog Objects · Read-only Get several Square catalog objects at once by their IDs. Returns the objects and, optionally, their related objects. Use this to fetch known IDs in one call; use square_catalog_object_get for a single object. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `object_ids` (`array`, required): The IDs of the CatalogObjects to be retrieved. Example: ["W62UWFY35CWMYGVWK6TWJDNI","AA27W3M2GGTF3H6AVPNB77CK"] - `catalog_version` (`integer`, optional): 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. Example: 1659736215000 - `include_category_path_to_root` (`boolean`, optional): Specifies whether or not to include the path_to_root list for each returned category instance. The path_to_root list consists of CategoryPathToRootNode objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the path_to_root list is empty and is not returned in the response payload. Example: true - `include_deleted_objects` (`boolean`, optional): Indicates whether to include (true) or not (false) in the response deleted objects, namely, those with the is_deleted attribute set to true. - `include_options` (`object`, optional): Options to include related resources in the response. Options to include related resources of the requested CatalogObjects. Related resources will be included in IncludedResources in the response. Example: {"include":["INCLUDE_NESTED_MODIFIERS"]} - `include_related_objects` (`boolean`, optional): If true, the response will include additional objects that are related to the requested objects. Related objects are defined as any objects referenced by ID by the results in the objects field of the response. These objects are put in the related_objects field. Setting this to true is helpful when the objects are needed for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example, if the objects field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects and CatalogModifierLists will be returned in the related_objects field of the response. Example input: `{"object_ids":["W62UWFY35CWMYGVWK6TWJDNI","AA27W3M2GGTF3H6AVPNB77CK"]}` ### `square_catalog_objects_search` Search Catalog Objects · Read-only Search Square catalog objects of any type with an exact, prefix, range, text, or relationship query. Returns matching objects, optional related objects, and a cursor for the next page. Use this for advanced catalog queries; use square_catalog_items_search for simple item searches by text, category, or stock level. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `begin_time` (`string`, optional): Return objects modified after this timestamp, in RFC 3339 format, e.g., 2016-09-04T23:59:33.123Z. The timestamp is exclusive - objects with a timestamp equal to begin_time will not be included in the response. Example: 2026-01-01T00:00:00Z - `cursor` (`string`, optional): The pagination cursor returned in the previous response. Leave unset for an initial request. See Pagination for more information. Example: CAISBQoDMTIzGAE - `include_category_path_to_root` (`boolean`, optional): Specifies whether or not to include the path_to_root list for each returned category instance. The path_to_root list consists of CategoryPathToRootNode objects and specifies the path that starts with the immediate parent category of the returned category and ends with its root category. If the returned category is a top-level category, the path_to_root list is empty and is not returned in the response payload. If include_category_path_to_root is true, then the include_deleted_objects request parameter must be false. Both properties cannot be true at the same time. - `include_deleted_objects` (`boolean`, optional): If true, deleted objects will be included in the results. Defaults to false. Deleted objects will have their is_deleted field set to true. If include_deleted_objects is true, then the include_category_path_to_root request parameter must be false. Both properties cannot be true at the same time. - `include_options` (`object`, optional): Options to include related resources in the response. Options to include related resources of the requested CatalogObjects. Related resources will be included in IncludedResources in the response. Example: {"include":["INCLUDE_NESTED_MODIFIERS"]} - `include_related_objects` (`boolean`, optional): If true, the response will include additional objects that are related to the requested objects. Related objects are objects that are referenced by object ID by the objects in the response. This is helpful if the objects are being fetched for immediate display to a user. This process only goes one level deep. Objects referenced by the related objects will not be included. For example: If the objects field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects and CatalogModifierLists will be returned in the related_objects field of the response. - `limit` (`integer`, optional): 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. Example: 100 - `object_types` (`array`, optional): 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. Example: ["ITEM"] - `query` (`object`, optional): A query to be used to filter or sort the results. If no query is specified, the entire catalog will be returned. A query composed of one or more different types of filters to narrow the scope of targeted objects when calling the SearchCatalogObjects endpoint. Example: {"prefix_query":{"attribute_name":"name","attribute_prefix":"tea"}} Example input: `{}` ### `square_customer_get` Get Customer · Read-only Get one Square customer profile by its ID. Returns the customer with name, email, phone, address, birthday, notes, preferences, group ids, and version. Use this for a single customer; use square_customers_search to find a customer by email or phone. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `customer_id` (`string`, required): The ID of the customer to retrieve. Example: W92WH6P11H4Z77CTET0RNTGFW8 Example input: `{"customer_id":""}` ### `square_customer_group_get` Get Customer Group · Read-only Get one Square customer group by its ID. Returns the group id, name, and timestamps. Use this for a single group; use square_customer_groups_list to browse groups. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `group_id` (`string`, required): The ID of the customer group to retrieve. Example: 2TAT3CMH4Q0A9M87XJZED0WMR3 Example input: `{"group_id":""}` ### `square_customer_groups_list` List Customer Groups · Read-only List the customer groups defined by the Square seller. Returns groups with id, name, and timestamps, plus a cursor for the next page. Use this to find a group_id; use square_customer_group_get for one group. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the limit is less than 1 or greater than 50, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 50. Example: 100 Example input: `{}` ### `square_customer_segment_get` Get Customer Segment · Read-only Get one Square customer segment by its ID. Returns the segment id, name, and timestamps. Use this for a single segment; use square_customer_segments_list to browse segments. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `segment_id` (`string`, required): The Square-issued ID of the customer segment. Example: GMNXRZVEXNQDF.CHURN_RISK Example input: `{"segment_id":""}` ### `square_customer_segments_list` List Customer Segments · Read-only List the customer segments (smart groups that Square maintains automatically) for the seller. Returns segments with id, name, and timestamps, plus a cursor for the next page. Use this to discover segments for filtering customers; use square_customer_segment_get for one segment. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): A pagination cursor returned by previous calls to ListCustomerSegments. This cursor is used to retrieve the next set of query results. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is less than 1 or greater than 50, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 50. Example: 100 Example input: `{}` ### `square_customers_list` List Customers · Read-only List customer profiles in the Square seller's customer directory, sorted by creation date or name. Returns customers with id, name, email, phone, address, and group ids, plus a cursor for the next page. Use this to browse customers; use square_customers_search to filter by email, phone, creation date, or group. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `count` (`boolean`, optional): Indicates whether to return the total count of customers in the count field of the response. The default value is false. - `cursor` (`string`, optional): A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is less than 1 or greater than 100, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 100. - `sort_field` (`string`, optional): Indicates how customers should be sorted. The default value is DEFAULT. Allowed values: DEFAULT, CREATED_AT. One of: `DEFAULT`, `CREATED_AT`. - `sort_order` (`string`, optional): Indicates whether customers should be sorted in ascending (ASC) or descending (DESC) order. The default value is ASC. Allowed values: DESC, ASC. One of: `DESC`, `ASC`. Example input: `{}` ### `square_customers_search` Search Customers · Read-only Search Square customer profiles with filters on email, phone, reference id, creation source, creation or update date, or group. Returns matching customers and a cursor for the next page. Use this to find customers by attribute; use square_customers_list to browse everyone. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `count` (`boolean`, optional): Indicates whether to return the total count of matching customers in the count field of the response. The default value is false. Example: true - `cursor` (`string`, optional): Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. If the specified limit is invalid, Square returns a 400 VALUE_TOO_LOW or 400 VALUE_TOO_HIGH error. The default value is 100. Example: 2 - `query` (`object`, optional): The filtering and sorting criteria for the search request. If a query is not specified, Square returns all customer profiles ordered alphabetically by given_name and family_name. Represents filtering and sorting criteria for a SearchCustomers request. Example: {"filter":{"created_at":{"end_at":"2018-02-01T00:00:00-00:00","start_at":"2018-01-01T00:00:00-00:00"},"creation_source":{"rule":"INCLUDE","values":["THIRD_PARTY"]},"email_address":{"fuzzy":"example.com"},"group_ids":{"all":["545AXB44B4XXWMVQ4W8SBT3HHF"]}},"sort":{"field":"CREATED_AT","order":"ASC"}} Example input: `{}` ### `square_dispute_evidence_list` List Dispute Evidence · Read-only List the evidence already attached to a Square dispute. Returns evidence items with id, type, text or file metadata, and upload time. Use this before submitting evidence to check what is attached. Requires a dispute_id from square_disputes_list. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `dispute_id` (`string`, required): The ID of the dispute. Example: XDgyFu7yo1E2S5lQGGpYn - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE Example input: `{"dispute_id":""}` ### `square_dispute_get` Get Dispute · Read-only Get one Square dispute by its ID. Returns the dispute with state, reason, amount, card brand, due date, and disputed payment. Use this for a single dispute; use square_disputes_list to find disputes. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `dispute_id` (`string`, required): The ID of the dispute you want more details about. Example: XDgyFu7yo1E2S5lQGGpYn Example input: `{"dispute_id":""}` ### `square_disputes_list` List Disputes · Read-only List Square payment disputes (chargebacks), optionally filtered by state or location. Returns disputes with id, state, reason, amount, due date, and disputed payment, plus a cursor. Use this to find disputes that need a response; use square_dispute_get for one dispute. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `location_id` (`string`, optional): The ID of the location for which to return a list of disputes. If not specified, the endpoint returns disputes associated with all locations. Example: L88917AVBK2S5 - `states` (`string`, optional): The dispute states used to filter the result. If not specified, the endpoint returns all disputes. Allowed values: INQUIRY_EVIDENCE_REQUIRED, INQUIRY_PROCESSING, INQUIRY_CLOSED, EVIDENCE_REQUIRED, PROCESSING, WON, LOST, ACCEPTED. One of: `INQUIRY_EVIDENCE_REQUIRED`, `INQUIRY_PROCESSING`, `INQUIRY_CLOSED`, `EVIDENCE_REQUIRED`, `PROCESSING`, `WON`, `LOST`, `ACCEPTED`. Example input: `{}` ### `square_gift_card_activities_list` List Gift Card Activities · Read-only List Square gift card activities (activate, load, redeem, adjust, and so on), optionally for one card, type, location, or time range. Returns activities with type, amount, balance after, location, and gift card id, plus a cursor. Use this to audit gift card balances; use square_gift_card_activity_create to record a new activity. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `begin_time` (`string`, optional): 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. Example: 2026-01-01T00:00:00Z - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `end_time` (`string`, optional): 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. Example: 2026-02-01T00:00:00Z - `gift_card_id` (`string`, optional): 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. Example: gftc:6d55a72470d940c6ba09c0ab8ad08d20 - `limit` (`integer`, optional): 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. - `location_id` (`string`, optional): 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. Example: L88917AVBK2S5 - `sort_order` (`string`, optional): The order in which the endpoint returns the activities, based on created_at; ASC - Oldest to newest; DESC - Newest to oldest (default). Allowed values: ASC, DESC. One of: `ASC`, `DESC`. - `type` (`string`, optional): 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. Example: DIGITAL Example input: `{}` ### `square_gift_card_get` Get Gift Card · Read-only Get one Square gift card by its ID. Returns the gift card with GAN, type, state, balance, and linked customer ids. Use this when you have the gift card ID; use square_gift_card_get_by_gan when you have the card number. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `gift_card_id` (`string`, required): The ID of the gift card to retrieve. Example: gftc:6d55a72470d940c6ba09c0ab8ad08d20 Example input: `{"gift_card_id":""}` ### `square_gift_card_get_by_gan` Get Gift Card by Number · Read-only Get a Square gift card by its gift card account number (GAN). Returns the gift card with id, type, state, balance, and linked customer ids. Use this when you have the number printed on the card; use square_gift_card_get when you have the ID. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `gan` (`string`, required): 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. Example: 7783320001001635 Example input: `{"gan":""}` ### `square_gift_cards_list` List Gift Cards · Read-only List Square gift cards, optionally filtered by type, state, or linked customer. Returns gift cards with id, GAN, type, state, balance, and linked customer ids, plus a cursor. Use this to browse gift cards; use square_gift_card_get_by_gan when you have the card number. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `customer_id` (`string`, optional): If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer. Example: W92WH6P11H4Z77CTET0RNTGFW8 - `limit` (`integer`, optional): 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. Example: 100 - `state` (`string`, optional): 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. Allowed values: PENDING, ACTIVE, DEACTIVATED, BLOCKED. One of: `PENDING`, `ACTIVE`, `DEACTIVATED`, `BLOCKED`. - `type` (`string`, optional): If a type is provided, the endpoint returns gift cards of the specified type. Otherwise, the endpoint returns gift cards of all types. Allowed values: DIGITAL, PHYSICAL. One of: `DIGITAL`, `PHYSICAL`. Example input: `{}` ### `square_inventory_changes_batch_retrieve` Batch Get Inventory Changes · Read-only Get the history of Square inventory changes (adjustments and physical counts), filtered by catalog object, location, type, state, or time. Returns the changes, newest last, plus a cursor for the next page. Use this to audit how stock changed; use square_inventory_counts_batch_retrieve for current counts. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `catalog_object_ids` (`array`, optional): The filter to return results by CatalogObject ID. The filter is only applicable when set. The default value is null. Example: ["W62UWFY35CWMYGVWK6TWJDNI"] - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The number of records to return. Example: 100 - `location_ids` (`array`, optional): The filter to return results by Location ID. The filter is only applicable when set. The default value is null. Example: ["C6W5YS5QM06F5"] - `reason_ids` (`array`, optional): The filter to return ADJUSTMENT query results by inventory adjustment reason. This filter is only applied when set. The request cannot include both reason_ids and states. Example: [{"type":"RECEIVED","custom_reason_id":"GKY2ZUSDUOHAAW7ZEJ7ZV7ZN"}] - `sort` (`object`, optional): Specification of how returned inventory changes should be ordered. Currently, inventory changes can only be ordered by the occurred_at field. The default sort order for occurred_at is ASC (changes are returned oldest-first by default). Example: {"field":"OCCURRED_AT","order":"DESC"} - `states` (`array`, optional): The filter to return ADJUSTMENT query results by InventoryState. This filter is only applied when set. The default value is null. Example: ["IN_STOCK"] - `types` (`array`, optional): The filter to return results by InventoryChangeType values other than TRANSFER. The default value is [PHYSICAL_COUNT, ADJUSTMENT]. Example: ["PHYSICAL_COUNT"] - `updated_after` (`string`, optional): 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). Example: 2016-11-01T00:00:00.000Z - `updated_before` (`string`, optional): The filter to return results with their created_at or calculated_at value strictly before the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (1970-01-01T00:00:00Z). Example: 2016-12-01T00:00:00.000Z Example input: `{}` ### `square_inventory_count_get` Get Inventory Count · Read-only Get the current inventory counts for one Square catalog item variation, per location and state. Returns counts with quantity, state (such as IN_STOCK), location id, and calculation time. Use this for one variation; use square_inventory_counts_batch_retrieve for many variations or locations. Requires a catalog_object_id of an item variation from square_catalog_items_search. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `catalog_object_id` (`string`, required): ID of the CatalogObject to retrieve. Example: NC7RMZ5L7KR262JLJVJTWBDY - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `location_ids` (`string`, optional): The Location IDs to look up as a comma-separated list. An empty list queries all locations. Example: L88917AVBK2S5,LDBVF3HFZWPCC Example input: `{"catalog_object_id":""}` ### `square_inventory_counts_batch_retrieve` Batch Get Inventory Counts · Read-only Get current inventory counts for many Square catalog objects and locations, optionally only those changed since a time. Returns counts with quantity, state, location id, and catalog object id, plus a cursor for the next page. Use this for stock levels across items; use square_inventory_count_get for a single variation. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `catalog_object_ids` (`array`, optional): The filter to return results by CatalogObject ID. The filter is applicable only when set. The default is null. Example: ["W62UWFY35CWMYGVWK6TWJDNI"] - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The number of records to return. Example: 100 - `location_ids` (`array`, optional): The filter to return results by Location ID. This filter is applicable only when set. The default is null. Example: ["59TNP9SA8VGDA"] - `states` (`array`, optional): The filter to return results by InventoryState. The filter is only applicable when set. Ignored are untracked states of NONE, SOLD, and UNLINKED_RETURN. The default is null. Example: EVIDENCE_REQUIRED - `updated_after` (`string`, optional): 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). Example: 2016-11-16T00:00:00.000Z Example input: `{}` ### `square_invoice_get` Get Invoice · Read-only Get one Square invoice by its ID. Returns the invoice with status, recipient, payment requests, delivery method, public URL, amounts, and version. Use this for a single invoice; use square_invoices_search to find invoices. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `invoice_id` (`string`, required): The ID of the invoice to retrieve. Example: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY Example input: `{"invoice_id":""}` ### `square_invoices_list` List Invoices · Read-only List the Square invoices for one location. Returns invoices with id, status, order id, recipient, payment requests, amounts, and version, plus a cursor. Use this to browse a location's invoices; use square_invoices_search to filter by customer or sort by date. Requires a location_id from square_locations_list. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `location_id` (`string`, required): The ID of the location for which to list invoices. Example: L88917AVBK2S5 - `cursor` (`string`, optional): A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The maximum number of invoices to return (200 is the maximum limit). If not provided, the server uses a default limit of 100 invoices. Example input: `{"location_id":""}` ### `square_invoices_search` Search Invoices · Read-only Search Square invoices for a location, optionally filtered by customer and sorted by invoice date. Returns matching invoices and a cursor for the next page. Use this to find invoices for a customer; use square_invoices_list to browse all invoices of a location. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `query` (`object`, required): Describes the query criteria for searching invoices. Describes query criteria for searching invoices. Example: {"filter":{"customer_ids":["JDKYHBWT1D4F8MFH63DBMEN8Y4"],"location_ids":["ES0RJRZYEC39A"]},"sort":{"field":"INVOICE_SORT_DATE","order":"DESC"}} - `cursor` (`string`, optional): A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The maximum number of invoices to return (200 is the maximum limit). If not provided, the server uses a default limit of 100 invoices. Example input: `{"query":{"loyalty_account_id":"5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd"}}` ### `square_jobs_list` List Jobs · Read-only List the jobs (job titles) defined by the Square seller. Returns jobs with id, title, tip eligibility, and version, plus a cursor. Use this to find job ids used in wage settings and timecards. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE Example input: `{}` ### `square_location_booking_profiles_list` List Location Booking Profiles · Read-only List the booking profiles of the seller's locations. Returns each location's booking site URL and whether online booking is enabled, plus a cursor. Use this to find which locations accept online bookings. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The maximum number of results to return in a paged response. Example: 100 Example input: `{}` ### `square_location_get` Get Location · Read-only Get one Square business location by its ID, or the main location by passing "main". Returns the location record with address, business hours, timezone, currency, status, and contact details. Use this to inspect a single location; use square_locations_list to browse all locations. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `location_id` (`string`, required): The ID of the location to retrieve. Specify the string "main" to return the main location. Example: L88917AVBK2S5 Example input: `{"location_id":""}` ### `square_locations_list` List Locations · Read-only List every business location of the connected Square seller. Returns each location with its id, name, address, timezone, currency, status, and capabilities. Use this to find the location_id most other Square tools require; use square_location_get for one location by ID. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: none. Example input: `{}` ### `square_loyalty_account_get` Get Loyalty Account · Read-only Get one Square Loyalty account by its ID. Returns the account with points balance, lifetime points, customer id, and enrollment details. Use this for a known account; use square_loyalty_accounts_search to find one by phone or customer. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `account_id` (`string`, required): The ID of the loyalty account to retrieve. Example: 79b807d2-d786-46a9-933b-918028d7a8c5 Example input: `{"account_id":""}` ### `square_loyalty_accounts_search` Search Loyalty Accounts · Read-only Search Square Loyalty accounts by phone number or customer ID. Returns matching accounts with id, points balance, lifetime points, and customer id, plus a cursor. Use this to find a buyer's loyalty account; use square_loyalty_account_get when you have the account ID. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The maximum number of results to include in the response. The default value is 30. Example: 10 - `query` (`object`, optional): The search criteria for the request. The search criteria for the loyalty accounts. Example: {"mappings":[{"phone_number":"+14155551234"}]} Example input: `{}` ### `square_loyalty_program_get` Get Loyalty Program · Read-only Get the seller's Square Loyalty program by ID, or pass "main" for the seller's program. Returns the program with status, reward tiers, accrual rules, and terminology. Use this first to get the program_id and reward tier ids that other loyalty tools need. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `program_id` (`string`, required): The ID of the loyalty program or the keyword main. Either value can be used to retrieve the single loyalty program that belongs to the seller. Example input: `{"program_id":""}` ### `square_loyalty_reward_get` Get Loyalty Reward · Read-only Get one Square Loyalty reward by its ID. Returns the reward with status, reward tier, points, loyalty account, and order id. Use this for a single reward; use square_loyalty_rewards_search to find rewards. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `reward_id` (`string`, required): The ID of the loyalty reward to retrieve. Example: 9f18ac21-233a-31c3-be77-b45840f5a810 Example input: `{"reward_id":""}` ### `square_loyalty_rewards_search` Search Loyalty Rewards · Read-only Search Square Loyalty rewards for a loyalty account, optionally filtered by status. Returns rewards with id, status, reward tier, points, and order id, plus a cursor. Use this to find issued or redeemed rewards; use square_loyalty_reward_get for one reward. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The maximum number of results to return in the response. The default value is 30. Example: 10 - `query` (`object`, optional): The search criteria for the request. If empty, the endpoint retrieves all loyalty rewards in the loyalty program. The set of search requirements. Example: {"loyalty_account_id":"5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd"} Example input: `{}` ### `square_merchant_get` Get Merchant · Read-only Get the connected Square merchant (seller account) by ID, or pass "me" for the current seller. Returns the merchant id, business name, country, language, currency, status, and main location id. Use this to read seller profile details; use square_merchants_list when you do not know the merchant ID. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `merchant_id` (`string`, required): 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. Example input: `{"merchant_id":""}` ### `square_merchants_list` List Merchants · Read-only List the merchant (seller account) that the connected access token can reach. Returns the merchant id, business name, country, language, currency, status, and main location id. Use this to learn who the connected seller is; use square_merchant_get to fetch one merchant by ID or "me". Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`integer`, optional): The cursor generated by the previous response. Example: CAISBQoDMTIzGAE Example input: `{}` ### `square_order_calculate` Calculate Order · Read-only Preview the totals of a Square order, including taxes, discounts, and service charges, without creating it. Returns the order with calculated totals; nothing is saved. Use this to quote a price; use square_order_create to save the order. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `order` (`object`, required): The order to be calculated. Expects the entire order, not a sparse update. Contains all information related to a single order to process with Square, including line items that specify the products to purchase. Order objects also include information about any associated tenders, refunds, and returns. Example: {"discounts":[{"name":"50% Off","percentage":"50","scope":"ORDER"}],"line_items":[{"base_price_money":{"amount":500,"currency":"USD"},"name":"Item 1","quantity":"1"},{"base_price_money":{"amount":300,"currency":"USD"},"name":"Item 2","quantity":"2"}],"location_id":"D7AVYMEAPJ3A3"} - `proposed_rewards` (`array`, optional): Identifies one or more loyalty reward tiers to apply during the order calculation. The discounts defined by the reward tiers are added to the order only to preview the effect of applying the specified rewards. The rewards do not correspond to actual redemptions; that is, no rewards are created. Therefore, the reward ids are random strings used only to reference the reward tier. Example: [{"reward_tier_id":"GKY2ZUSDUOHAAW7ZEJ7ZV7ZN"}] Example input: `{"order":{}}` ### `square_order_get` Get Order · Read-only Get one Square order by its ID. Returns the order with line items, taxes, discounts, fulfillments, tenders, refunds, totals, state, and version. Use this for a single order; use square_orders_batch_retrieve for several IDs, or square_orders_search to find orders. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `order_id` (`string`, required): The ID of the order to retrieve. Example: CAISENgvlJ6jLWAzERDzjyHVybY Example input: `{"order_id":""}` ### `square_orders_batch_retrieve` Batch Get Orders · Read-only Get up to 100 Square orders at once by their IDs. Returns the matching orders with line items, totals, and state. Use this to fetch several known orders in one call; use square_order_get for a single order. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `order_ids` (`array`, required): The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request. Example: ["CAISEM82RcpmcFBM0TfOyiHV3es","CAISENgvlJ6jLWAzERDzjyHVybY"] - `location_id` (`string`, optional): 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. Example: 057P5VYJ4A5X1 Example input: `{"order_ids":["CAISEM82RcpmcFBM0TfOyiHV3es","CAISENgvlJ6jLWAzERDzjyHVybY"]}` ### `square_orders_search` Search Orders · Read-only Search orders across one or more Square locations, filtered by state, date range, customer, or fulfillment, and sorted by date. Returns matching orders (or lightweight order entries) and a cursor for the next page. Use this to find orders; use square_order_get when you already know the order ID. Requires location_ids from square_locations_list. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `location_ids` (`array`, required): The location IDs for the orders to query. All locations must belong to the same merchant. Max: 10 location IDs. Example: ["057P5VYJ4A5X1","18YC4JDH91E1H"] - `cursor` (`string`, optional): A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The maximum number of results to be returned in a single page. Default: 500 Max: 1000 Example: 3 - `query` (`object`, optional): Query conditions used to filter or sort the results. Note that when retrieving additional pages using a cursor, you must use the original query. Contains query criteria for the search. Example: {"filter":{"date_time_filter":{"closed_at":{"end_at":"2019-03-04T21:54:45+00:00","start_at":"2018-03-03T20:00:00+00:00"}},"state_filter":{"states":["COMPLETED"]}},"sort":{"sort_field":"CLOSED_AT","sort_order":"DESC"}} - `return_entries` (`boolean`, optional): A Boolean that controls the format of the search results. If true, SearchOrders returns OrderEntry objects. If false, SearchOrders returns complete order objects. Default: false. Example input: `{"location_ids":["057P5VYJ4A5X1","18YC4JDH91E1H"]}` ### `square_payment_get` Get Payment · Read-only Get one Square payment by its ID. Returns the full payment record, including status, amounts, card or wallet details, receipt URL, order id, and refund ids. Use this to check a payment's status or details; use square_payments_list to find payments. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `payment_id` (`string`, required): A unique ID for the desired payment. Example: R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY Example input: `{"payment_id":""}` ### `square_payment_link_get` Get Payment Link · Read-only Get one Square payment link by its ID. Returns the link with its URL, order id, checkout options, pre-populated buyer data, and version. Use this for a single link; use square_payment_links_list to browse links. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `payment_link_id` (`string`, required): The ID of link to retrieve. Example: TY4BWEDJ6AI5MBIV Example input: `{"payment_link_id":""}` ### `square_payment_links_list` List Payment Links · Read-only List the Square Online Checkout payment links created by the seller. Returns links with id, URL, order id, description, and version, plus a cursor for the next page. Use this to browse links; use square_payment_link_get for one link by ID. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): 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 Example input: `{}` ### `square_payments_list` List Payments · Read-only List payments taken by the connected Square seller, optionally filtered by time range, location, card, or amount. Returns payments with id, status, amount, tip, source type, card details, order id, and timestamps, plus a cursor for the next page. Use this to browse or reconcile payments; use square_payment_get for one payment by ID. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `begin_time` (`string`, optional): Indicates the start of the time range to retrieve payments for, in RFC 3339 format. The range is determined using the created_at field for each Payment. Inclusive. Default: The current time minus one year. Example: 2026-01-01T00:00:00Z - `card_brand` (`string`, optional): The brand of the payment card (for example, VISA). - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `end_time` (`string`, optional): 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. Example: 2026-02-01T00:00:00Z - `is_offline_payment` (`boolean`, optional): Whether the payment was taken offline or not. - `last_4` (`string`, optional): The last four digits of a payment card. Example: 1111 - `limit` (`integer`, optional): 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 - `location_id` (`string`, optional): Limit results to the location supplied. By default, results are returned for the default (main) location associated with the seller. Example: L88917AVBK2S5 - `offline_begin_time` (`string`, optional): Indicates the start of the time range for which to retrieve offline payments, in RFC 3339 format for timestamps. The range is determined using the offline_payment_details.client_created_at field for each Payment. If set, payments without a value set in offline_payment_details.client_created_at will not be returned. Default: The current time. Example: 2026-01-01T00:00:00Z - `offline_end_time` (`string`, optional): Indicates the end of the time range for which to retrieve offline payments, in RFC 3339 format for timestamps. The range is determined using the offline_payment_details.client_created_at field for each Payment. If set, payments without a value set in offline_payment_details.client_created_at will not be returned. Default: The current time. Example: 2026-02-01T00:00:00Z - `sort_field` (`string`, optional): The field used to sort results by. The default is CREATED_AT. Allowed values: CREATED_AT, OFFLINE_CREATED_AT, UPDATED_AT. One of: `CREATED_AT`, `OFFLINE_CREATED_AT`, `UPDATED_AT`. - `sort_order` (`string`, optional): The order in which results are listed by ListPaymentsRequest.sort_field: ASC - Oldest to newest; DESC - Newest to oldest (default). Allowed values: ASC, DESC. One of: `ASC`, `DESC`. - `total` (`integer`, optional): The exact amount in the total_money for a payment. Example: 1000 - `updated_at_begin_time` (`string`, optional): 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. Example: 2026-01-01T00:00:00Z - `updated_at_end_time` (`string`, optional): 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. Example: 2026-02-01T00:00:00Z Example input: `{}` ### `square_payout_entries_list` List Payout Entries · Read-only List the entries (payments, refunds, fees, and other balance changes) that make up one Square payout. Returns entries with type, gross amount, fee amount, net amount, and effective time, plus a cursor. Use this to break down a payout; use square_payout_get for its totals. Requires a payout_id from square_payouts_list. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `payout_id` (`string`, required): The ID of the payout to retrieve the information for. Example: po_b345d2c7-90b3-4f0b-a2aa-df1def7f8afc - `cursor` (`string`, optional): 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 request parameters change between requests, subsequent results may contain duplicates or missing records. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): 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 - `sort_order` (`string`, optional): The order in which payout entries are listed. Allowed values: DESC, ASC. One of: `DESC`, `ASC`. Example input: `{"payout_id":""}` ### `square_payout_get` Get Payout · Read-only Get one Square payout by its ID. Returns the payout with status, amount, destination, arrival date, and type. Use this for a single payout; use square_payouts_list to find payouts. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `payout_id` (`string`, required): The ID of the payout to retrieve the information for. Example: po_b345d2c7-90b3-4f0b-a2aa-df1def7f8afc Example input: `{"payout_id":""}` ### `square_payouts_list` List Payouts · Read-only List Square payouts (transfers to the seller's bank account), optionally filtered by location, status, or time range. Returns payouts with id, status, amount, destination, arrival date, and type, plus a cursor. Use this to reconcile deposits; use square_payout_entries_list to see what a payout contains. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `begin_time` (`string`, optional): The timestamp for the beginning of the payout creation time, in RFC 3339 format. Inclusive. Default: The current time minus one year. Example: 2026-01-01T00:00:00Z - `cursor` (`string`, optional): 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 request parameters change between requests, subsequent results may contain duplicates or missing records. Example: CAISBQoDMTIzGAE - `end_time` (`string`, optional): The timestamp for the end of the payout creation time, in RFC 3339 format. Default: The current time. Example: 2026-02-01T00:00:00Z - `limit` (`integer`, optional): 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 - `location_id` (`string`, optional): 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. Example: L88917AVBK2S5 - `sort_order` (`string`, optional): The order in which payouts are listed. Allowed values: DESC, ASC. One of: `DESC`, `ASC`. - `status` (`string`, optional): If provided, only payouts with the given status are returned. Allowed values: SENT, FAILED, PAID. One of: `SENT`, `FAILED`, `PAID`. Example input: `{}` ### `square_refund_get` Get Refund · Read-only Get one Square payment refund by its ID. Returns the refund record with status, amount, payment id, order id, reason, and timestamps. Use this to check a refund's status; use square_refunds_list to find refunds. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `refund_id` (`string`, required): The unique ID for the desired PaymentRefund. Example: R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY_KlWP8IC1557ddwc9QWTKrCVU6m0JXDz15R2Qym5eQfR Example input: `{"refund_id":""}` ### `square_refunds_list` List Refunds · Read-only List payment refunds for the connected Square seller, optionally filtered by time range, location, status, or source type. Returns refunds with id, status, amount, payment id, reason, and timestamps, plus a cursor for the next page. Use this to browse refunds; use square_refund_get for one refund by ID. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `begin_time` (`string`, optional): Indicates the start of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the created_at field for each PaymentRefund. Default: The current time minus one year. Example: 2026-01-01T00:00:00Z - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `end_time` (`string`, optional): Indicates the end of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the created_at field for each PaymentRefund. Default: The current time. Example: 2026-02-01T00:00:00Z - `limit` (`integer`, optional): 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 - `location_id` (`string`, optional): Limit results to the location supplied. By default, results are returned for all locations associated with the seller. Example: L88917AVBK2S5 - `sort_field` (`string`, optional): The field used to sort results by. The default is CREATED_AT. Allowed values: CREATED_AT, UPDATED_AT. One of: `CREATED_AT`, `UPDATED_AT`. - `sort_order` (`string`, optional): The order in which results are listed by PaymentRefund.created_at: ASC - Oldest to newest; DESC - Newest to oldest (default). Allowed values: ASC, DESC. One of: `ASC`, `DESC`. - `source_type` (`string`, optional): If provided, only returns refunds whose payments have the indicated source type. Current values include CARD, BANK_ACCOUNT, WALLET, CASH, and EXTERNAL. For information about these payment source types, see Take Payments. Default: If omitted, refunds are returned regardless of the source type. Allowed values: CARD, BANK_ACCOUNT, WALLET, CASH, EXTERNAL. One of: `CARD`, `BANK_ACCOUNT`, `WALLET`, `CASH`, `EXTERNAL`. - `status` (`string`, optional): 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. Allowed values: PENDING, COMPLETED, REJECTED, FAILED. Example: PAID. One of: `PENDING`, `COMPLETED`, `REJECTED`, `FAILED`. - `updated_at_begin_time` (`string`, optional): Indicates the start of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the updated_at field for each PaymentRefund. Default: If omitted, the time range starts at begin_time. Example: 2026-01-01T00:00:00Z - `updated_at_end_time` (`string`, optional): Indicates the end of the time range to retrieve each PaymentRefund for, in RFC 3339 format. The range is determined using the updated_at field for each PaymentRefund. Default: The current time. Example: 2026-02-01T00:00:00Z Example input: `{}` ### `square_subscription_events_list` List Subscription Events · Read-only List the history of events (start, plan change, pause, resume, stop) for one Square subscription. Returns events with type, effective date, and plan variation id, plus a cursor for the next page. Use this to audit a subscription's changes; use square_subscription_get for its current state. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `subscription_id` (`string`, required): The ID of the subscription to retrieve the events for. Example: 8151fc89-da15-4eb9-a685-1a70883cebfc - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The upper limit on the number of subscription events to return in a paged response. Example: 100 Example input: `{"subscription_id":""}` ### `square_subscription_get` Get Subscription · Read-only Get one Square subscription by its ID. Returns the subscription with status, plan variation, customer, card, dates, and optionally its pending actions. Use this for a single subscription; use square_subscriptions_search to find subscriptions. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `subscription_id` (`string`, required): The ID of the subscription to retrieve. Example: 8151fc89-da15-4eb9-a685-1a70883cebfc - `include` (`string`, optional): 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. Example input: `{"subscription_id":""}` ### `square_subscriptions_search` Search Subscriptions · Read-only Search Square subscriptions filtered by customer, location, or source application. Returns matching subscriptions and a cursor for the next page. Use this to find a customer's subscriptions; use square_subscription_get for one subscription. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `include` (`array`, optional): An option to include related information in the response. The supported values are: actions: to include scheduled actions on the targeted subscriptions. - `limit` (`integer`, optional): The upper limit on the number of subscriptions to return in a paged response. Example: 100 - `query` (`object`, optional): A subscription query consisting of specified filtering conditions. If this query field is unspecified, the SearchSubscriptions call will return all subscriptions. Represents a query, consisting of specified query expressions, used to search for subscriptions. Example: {"filter":{"customer_ids":["CHFGVKYY8RSV93M5KCYTG4PN0G"],"location_ids":["S8GWD5R9QB376"],"source_names":["My App"]}} Example input: `{}` ### `square_team_member_booking_profiles_list` List Team Member Booking Profiles · Read-only List the booking profiles of team members who can be booked, optionally limited to one location. Returns team member ids, display names, and whether they are bookable, plus a cursor. Use this to find bookable team members for square_booking_create. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `bookable_only` (`boolean`, optional): Indicates whether to include only bookable team members in the returned result (true) or not (false). - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The maximum number of results to return in a paged response. Example: 100 - `location_id` (`string`, optional): Indicates whether to include only team members enabled at the given location in the returned result. Example: L88917AVBK2S5 Example input: `{}` ### `square_team_member_get` Get Team Member · Read-only Get one Square team member by ID. Returns the team member with name, contact details, status, assigned locations, and wage setting. Use this for a single team member; use square_team_members_search to find team members. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `team_member_id` (`string`, required): The ID of the team member to retrieve. Example: TMXUrsBWWcHTt79t Example input: `{"team_member_id":""}` ### `square_team_member_wage_setting_get` Get Team Member Wage Setting · Read-only Get the wage setting (job assignments, pay types, and rates) of one Square team member. Returns the wage setting with job assignments and whether the team member is overtime exempt. Use this to read pay rates; use square_team_member_wages_list to list wages across team members. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `team_member_id` (`string`, required): The ID of the team member for which to retrieve the wage setting. Example: TMXUrsBWWcHTt79t Example input: `{"team_member_id":""}` ### `square_team_member_wages_list` List Team Member Wages · Read-only List the hourly wages of Square team members, optionally for one team member. Returns wages with team member id, job title, hourly rate, and tip eligibility, plus a cursor. Use this to read wages across staff; use square_team_member_wage_setting_get for one team member's full wage setting. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): A pointer to the next page of EmployeeWage results to fetch. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The maximum number of TeamMemberWage results to return per page. The number can range between 1 and 200. The default is 200. Example: 100 - `team_member_id` (`string`, optional): Filter the returned wages to only those that are associated with the specified team member. Example: TMXUrsBWWcHTt79t Example input: `{}` ### `square_team_members_search` Search Team Members · Read-only Search the Square seller's team members, filtered by location, status, or owner flag. Returns team members with id, name, email, phone, status, and assigned locations, plus a cursor. Use this to find team members; use square_team_member_get for one team member by ID. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): The opaque cursor for fetching the next page. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The maximum number of TeamMember objects in a page (100 by default). - `query` (`object`, optional): The query parameters. Represents the parameters in a search for TeamMember objects. Example: {"filter":{"location_ids":["0G5P3VGACMMQZ"],"status":"ACTIVE"}} Example input: `{}` ### `square_timecard_get` Get Timecard · Read-only Get one Square timecard by its ID. Returns the timecard with start and end times, breaks, wage, status, team member, and version. Use this for a single timecard; use square_timecards_search to find timecards. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `timecard_id` (`string`, required): The UUID for the Timecard being retrieved. Example: T35HMQSN89SV4 Example input: `{"timecard_id":""}` ### `square_timecards_search` Search Timecards · Read-only Search Square timecards (worked shifts), filtered by location, team member, status, or work day range. Returns timecards with start and end times, breaks, wage, status, and team member id, plus a cursor. Use this to review hours worked; use square_timecard_get for one timecard. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): An opaque cursor for fetching the next page. Example: CAISBQoDMTIzGAE - `limit` (`integer`, optional): The number of resources in a page (200 by default). Example: 100 - `query` (`object`, optional): Query filters. The parameters of a Timecard search query, which includes filter and sort options. Example: {"filter":{"workday":{"date_range":{"end_date":"2019-02-03","start_date":"2019-01-20"},"default_timezone":"America/Los_Angeles","match_timecards_by":"START_AT"}}} Example input: `{}` ### `square_vendor_get` Get Vendor · Read-only Get one Square vendor (supplier) by its ID. Returns the vendor with name, contacts, address, account number, note, status, and version. Use this for a single vendor; use square_vendors_search to find vendors. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `vendor_id` (`string`, required): ID of the Vendor to retrieve. Example: INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4 Example input: `{"vendor_id":""}` ### `square_vendors_search` Search Vendors · Read-only Search the Square seller's vendors (suppliers) by name or status. Returns vendors with id, name, contacts, address, status, and version, plus a cursor. Use this to find vendors; use square_vendor_get for one vendor by ID. Read only: yes. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `cursor` (`string`, optional): 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. Example: CAISBQoDMTIzGAE - `filter` (`object`, optional): Specifies a filter used to search for vendors. Defines supported query expressions to search for vendors by. Example: {"name":["Sample name"],"status":["ACTIVE"]} - `sort` (`object`, optional): Specifies a sorter used to sort the returned vendors. Defines a sorter used to sort results from SearchVendors. Example: {"field":"NAME","order":"DESC"} Example input: `{}` ### `square_booking_cancel` Cancel Booking · Write Cancel a Square Appointments booking. Returns the booking with a canceled status. Use this to cancel an appointment; use square_booking_update to reschedule it instead. Requires a booking_id from square_bookings_list. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `booking_id` (`string`, required): The ID of the Booking object representing the to-be-cancelled booking. Example: zkras0xv0xwswx - `booking_version` (`integer`, optional): The revision number for the booking used for optimistic concurrency. Example: 1 - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 Example input: `{"booking_id":""}` ### `square_booking_create` Create Booking · Write Create a Square Appointments booking for a customer at a location with one or more service segments. Returns the created booking with its id, status, and version. Use square_bookings_availability_search first to find a free slot; use square_booking_update to change a booking. Requires a location_id, customer_id, service variation id, and team member id. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `booking` (`object`, required): The details of the booking to be created. Represents a booking as a time-bound service contract for a seller's staff member to provide a specified service at a given location to a requesting customer in one or more appointment segments. Example: {"start_at":"2026-11-02T17:00:00Z","location_id":"LEQHH0YY8B42M","customer_id":"EX2QSVGTZN4K1E5QE1CBFNVQ8M","customer_note":"Window seat, please","appointment_segments":[{"duration_minutes":60,"service_variation_id":"RU3PBTZTK7DXZDQFCJHOK2MC","team_member_id":"TMXUrsBWWcHTt79t","service_variation_version":1599775456731}]} - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 Example input: `{"booking":{"version":1,"start_at":"2026-11-02T18:00:00Z","customer_note":"Running 1 hour late"}}` ### `square_booking_update` Update Booking · Write Update a Square Appointments booking, such as its start time, segments, or notes, using its current version. Returns the updated booking. Use this to reschedule or edit; use square_booking_cancel to cancel. Requires a booking_id from square_bookings_list. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `booking` (`object`, required): The booking to be updated. Individual attributes explicitly specified here override the corresponding values of the existing booking. Represents a booking as a time-bound service contract for a seller's staff member to provide a specified service at a given location to a requesting customer in one or more appointment segments. Example: {"version":1,"start_at":"2026-11-02T18:00:00Z","customer_note":"Running 1 hour late"} - `booking_id` (`string`, required): The ID of the Booking object representing the to-be-updated booking. Example: zkras0xv0xwswx - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 Example input: `{"booking":{"version":1,"start_at":"2026-11-02T18:00:00Z","customer_note":"Running 1 hour late"},"booking_id":""}` ### `square_card_create` Create Card · Write Save a card on file for a Square customer from a card nonce or a completed payment. Returns the saved card with its id. Use this to store a card for future charges; use square_cards_list to see saved cards. Requires a source_id (card nonce or payment ID) and a customer_id. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `card` (`object`, required): Payment details associated with the card to be stored. Represents the payment details of a card to be used for payments. These details are determined by the payment token generated by Web Payments SDK. Example: {"billing_address":{"address_line_1":"500 Electric Ave","address_line_2":"Suite 600","administrative_district_level_1":"NY","country":"US","locality":"New York","postal_code":"10003"},"cardholder_name":"Amelia Earhart","customer_id":"VDKXEEKPJN48QDG3BGGFAK05P8","reference_id":"user-id-1"} - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `source_id` (`string`, required): The ID of the source which represents the card information to be stored. This can be a card nonce or a payment id. Example: cnon:uIbfJXhXETSP197M3GB - `verification_token` (`string`, optional): 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. Example: verf:CBASEGLHKHPjNTSLfLIUu6IbOyMgAQ Example input: `{"card":{},"idempotency_key":"","source_id":""}` ### `square_card_disable` Disable Card · Write Disable a Square card on file so it can no longer be charged. Returns the card with enabled set to false. Use this to remove a stored card from use; disabling cannot be undone. Requires a card_id from square_cards_list. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `card_id` (`string`, required): Unique ID for the desired Card. Example: ccof:uIbfJXhXETSP197M3GB Example input: `{"card_id":""}` ### `square_catalog_object_upsert` Create or Update Catalog Object · Write Create or update one Square catalog object, such as an item with its variations, a category, a tax, or a discount. Returns the saved object and a map of temporary client IDs to permanent IDs. Use this to add or edit catalog entries; use square_catalog_object_get to read the current version before updating. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `object` (`object`, required): A CatalogObject to be created or updated; For updates, the object must be active (the is_deleted field is not true); For creates, the object ID must start with #. The provided ID is replaced with a server-generated ID. The wrapper object for the catalog entries of a given object type. Depending on the type attribute value, a CatalogObject instance assumes a type-specific data to yield the corresponding type of catalog object. Example: {"id":"#Cocoa","item_data":{"abbreviation":"Ch","description_html":"Hot Chocolate ","name":"Cocoa","variations":[{"id":"#Small","item_variation_data":{"item_id":"#Cocoa","name":"Small","pricing_type":"VARIABLE_PRICING"},"type":"ITEM_VARIATION"},{"id":"#Large","item_variation_data":{"item_id":"#Cocoa","name":"Large","price_money":{"amount":400,"currency":"USD"},"pricing_type":"FIXED_PRICING"},"type":"ITEM_VARIATION"}]},"type":"ITEM"} Example input: `{"idempotency_key":"","object":{}}` ### `square_customer_add_to_group` Add Customer to Group · Write Add a Square customer to a customer group. Returns an empty object on success. Use this to group customers; use square_customer_groups_list to find the group_id. Requires a customer_id and a group_id. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `customer_id` (`string`, required): The ID of the customer to add to a group. Example: W92WH6P11H4Z77CTET0RNTGFW8 - `group_id` (`string`, required): The ID of the customer group to add the customer to. Example: 2TAT3CMH4Q0A9M87XJZED0WMR3 Example input: `{"customer_id":"","group_id":""}` ### `square_customer_create` Create Customer · Write Create a customer profile in the Square seller's customer directory. Returns the created customer with its new id and version. Use this to add a customer; use square_customers_search first to avoid duplicates, and square_customer_update to edit. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `address` (`object`, optional): The physical address associated with the customer profile. For maximum length constraints, see Customer addresses. The first_name and last_name fields are ignored if they are present in the request. Represents a postal address in a country. Example: {"address_line_1":"500 Electric Ave","address_line_2":"Suite 600","administrative_district_level_1":"NY","country":"US","locality":"New York","postal_code":"10003"} - `birthday` (`string`, optional): The birthday associated with the customer profile, in YYYY-MM-DD or MM-DD format. For example, specify 1998-09-21 for September 21, 1998, or 09-21 for September 21. Birthdays are returned in YYYY-MM-DD format, where YYYY is the specified birth year or 0000 if a birth year is not specified. - `company_name` (`string`, optional): A business name associated with the customer profile. The maximum length for this value is 500 characters. Example: Acme Coffee Co. - `email_address` (`string`, optional): The email address associated with the customer profile. The maximum length for this value is 254 characters. Example: Amelia.Earhart@example.com - `family_name` (`string`, optional): The family name (that is, the last name) associated with the customer profile. The maximum length for this value is 300 characters. Example: Earhart - `given_name` (`string`, optional): The given name (that is, the first name) associated with the customer profile. The maximum length for this value is 300 characters. Example: Amelia - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `nickname` (`string`, optional): A nickname for the customer profile. The maximum length for this value is 100 characters. Example: Millie - `note` (`string`, optional): A custom note associated with the customer profile. Example: a customer - `phone_number` (`string`, optional): 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. Example: +1-212-555-4240 - `reference_id` (`string`, optional): 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. Example: YOUR_REFERENCE_ID - `tax_ids` (`object`, optional): The tax ID associated with the customer profile. This field is available only for customers of sellers in EU countries or the United Kingdom. Represents the tax ID associated with a customer profile. The corresponding tax_ids field is available only for customers of sellers in EU countries or the United Kingdom. Example: {"eu_vat":"IE3426675K"} Example input: `{}` ### `square_customer_group_create` Create Customer Group · Write Create a customer group for the Square seller. Returns the created group with its new id. Use this to add a group; use square_customer_add_to_group to put customers in it. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `group` (`object`, required): The customer group to create. Represents a group of customer profiles. Customer groups can be created, be modified, and have their membership defined using the Customers API or within the Customer Directory in the Square Seller Dashboard or Point of Sale. Example: {"name":"Loyal Customers"} - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 Example input: `{"group":{"name":"Loyal Customers"}}` ### `square_customer_group_update` Update Customer Group · Write Rename an existing Square customer group. Returns the updated group. Use this to edit a group; use square_customer_group_create to add one. Requires a group_id from square_customer_groups_list. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `group` (`object`, required): The CustomerGroup object including all the updates you want to make. Represents a group of customer profiles. Customer groups can be created, be modified, and have their membership defined using the Customers API or within the Customer Directory in the Square Seller Dashboard or Point of Sale. Example: {"name":"Loyal Customers"} - `group_id` (`string`, required): The ID of the customer group to update. Example: 2TAT3CMH4Q0A9M87XJZED0WMR3 Example input: `{"group":{"name":"Loyal Customers"},"group_id":""}` ### `square_customer_update` Update Customer · Write Update fields on an existing Square customer profile, such as name, email, phone, address, or note. Returns the updated customer with its new version. Use this to edit a customer; use square_customer_create to add a new one. Requires a customer_id from square_customers_search or square_customers_list. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `customer_id` (`string`, required): The ID of the customer to update. Example: W92WH6P11H4Z77CTET0RNTGFW8 - `address` (`object`, optional): The physical address associated with the customer profile. Only new or changed fields are required in the request. For maximum length constraints, see Customer addresses. The first_name and last_name fields are ignored if they are present in the request. Represents a postal address in a country. Example: {"address_line_1":"500 Electric Ave","locality":"New York","administrative_district_level_1":"NY","postal_code":"10003","country":"US"} - `birthday` (`string`, optional): The birthday associated with the customer profile, in YYYY-MM-DD or MM-DD format. For example, specify 1998-09-21 for September 21, 1998, or 09-21 for September 21. Birthdays are returned in YYYY-MM-DD format, where YYYY is the specified birth year or 0000 if a birth year is not specified. - `company_name` (`string`, optional): A business name associated with the customer profile. The maximum length for this value is 500 characters. Example: Acme Coffee Co. - `email_address` (`string`, optional): The email address associated with the customer profile. The maximum length for this value is 254 characters. Example: New.Amelia.Earhart@example.com - `family_name` (`string`, optional): The family name (that is, the last name) associated with the customer profile. The maximum length for this value is 300 characters. Example: Earhart - `given_name` (`string`, optional): The given name (that is, the first name) associated with the customer profile. The maximum length for this value is 300 characters. Example: Amelia - `nickname` (`string`, optional): A nickname for the customer profile. The maximum length for this value is 100 characters. Example: Millie - `note` (`string`, optional): A custom note associated with the customer profile. Example: updated customer note - `phone_number` (`string`, optional): 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. Example: +12125551234 - `reference_id` (`string`, optional): 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. Example: ref-12345 - `tax_ids` (`object`, optional): The tax ID associated with the customer profile. This field is available only for customers of sellers in EU countries or the United Kingdom. Represents the tax ID associated with a customer profile. The corresponding tax_ids field is available only for customers of sellers in EU countries or the United Kingdom. Example: {"eu_vat":"IE3426675K"} - `version` (`integer`, optional): The current version of the customer profile. As a best practice, you should include this field to enable optimistic concurrency control. Example: 2 Example input: `{"customer_id":""}` ### `square_dispute_accept` Accept Dispute · Write Accept a Square dispute, conceding the chargeback so the disputed amount is returned to the cardholder. Returns the dispute with state ACCEPTED. Use this only when the seller will not contest; use square_dispute_evidence_text_create and square_dispute_evidence_submit to contest. Requires a dispute_id from square_disputes_list. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `dispute_id` (`string`, required): The ID of the dispute you want to accept. Example: XDgyFu7yo1E2S5lQGGpYn Example input: `{"dispute_id":""}` ### `square_dispute_evidence_submit` Submit Dispute Evidence · Write Submit all evidence attached to a Square dispute to the card issuer. Returns the dispute with its updated state. Use this once all evidence is attached with square_dispute_evidence_text_create; evidence cannot be added after submitting. Requires a dispute_id from square_disputes_list. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `dispute_id` (`string`, required): The ID of the dispute for which you want to submit evidence. Example: XDgyFu7yo1E2S5lQGGpYn Example input: `{"dispute_id":""}` ### `square_dispute_evidence_text_create` Add Dispute Text Evidence · Write Attach text evidence, such as a tracking number or rebuttal, to a Square dispute. Returns the created evidence item. Use this to build the case, then call square_dispute_evidence_submit. Requires a dispute_id from square_disputes_list. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `dispute_id` (`string`, required): The ID of the dispute for which you want to upload evidence. Example: XDgyFu7yo1E2S5lQGGpYn - `evidence_text` (`string`, required): The evidence string. Example: 1Z8888888888888888 - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `evidence_type` (`string`, optional): The type of evidence you are uploading. Allowed values: GENERIC_EVIDENCE, ONLINE_OR_APP_ACCESS_LOG, AUTHORIZATION_DOCUMENTATION, CANCELLATION_OR_REFUND_DOCUMENTATION, CARDHOLDER_COMMUNICATION, CARDHOLDER_INFORMATION, PURCHASE_ACKNOWLEDGEMENT, DUPLICATE_CHARGE_DOCUMENTATION, PRODUCT_OR_SERVICE_DESCRIPTION, RECEIPT, SERVICE_RECEIVED_DOCUMENTATION, PROOF_OF_DELIVERY_DOCUMENTATION, RELATED_TRANSACTION_DOCUMENTATION, REBUTTAL_EXPLANATION, TRACKING_NUMBER. One of: `GENERIC_EVIDENCE`, `ONLINE_OR_APP_ACCESS_LOG`, `AUTHORIZATION_DOCUMENTATION`, `CANCELLATION_OR_REFUND_DOCUMENTATION`, `CARDHOLDER_COMMUNICATION`, `CARDHOLDER_INFORMATION`, `PURCHASE_ACKNOWLEDGEMENT`, `DUPLICATE_CHARGE_DOCUMENTATION`, `PRODUCT_OR_SERVICE_DESCRIPTION`, `RECEIPT`, `SERVICE_RECEIVED_DOCUMENTATION`, `PROOF_OF_DELIVERY_DOCUMENTATION`, `RELATED_TRANSACTION_DOCUMENTATION`, `REBUTTAL_EXPLANATION`, `TRACKING_NUMBER`. Example input: `{"dispute_id":"","evidence_text":"","idempotency_key":""}` ### `square_gift_card_activity_create` Create Gift Card Activity · Write Record a Square gift card activity, such as ACTIVATE, LOAD, REDEEM, ADJUST_INCREMENT, or DEACTIVATE. Returns the created activity and the resulting gift card balance. Use this to activate, load, or redeem a gift card; use square_gift_card_activities_list to review history. Requires a gift_card_id or GAN and a location_id. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `gift_card_activity` (`object`, required): The activity to create for the gift card. This activity must specify gift_card_id or gift_card_gan for the target gift card, the location_id where the activity occurred, and the activity type along with the corresponding activity details. Represents an action performed on a gift card that affects its state or balance. A gift card activity contains information about a specific activity type. Example: {"activate_activity_details":{"line_item_uid":"eIWl7X0nMuO9Ewbh0ChIx","order_id":"jJNGHm4gLI6XkFbwtiSLqK72KkAZY"},"gift_card_id":"gftc:6d55a72470d940c6ba09c0ab8ad08d20","location_id":"81FN9BNFZTKS4","type":"ACTIVATE"} - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 Example input: `{"gift_card_activity":{},"idempotency_key":""}` ### `square_gift_card_create` Create Gift Card · Write Create a digital or physical Square gift card in PENDING state. Returns the created gift card with its id and GAN. Use this to issue a card, then call square_gift_card_activity_create with an ACTIVATE activity to load a balance. Requires a location_id from square_locations_list. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `gift_card` (`object`, required): The gift card to create. The type field is required for this request. The gan_source and gan fields are included as follows: To direct Square to generate a 16-digit GAN, omit gan_source and gan. To provide a custom GAN, include gan_source and gan; For gan_source, specify OTHER; For gan, provide a custom GAN containing 8 to 20 alphanumeric characters. The GAN must be unique for the seller and cannot start with the same bank identification number (BIN) as major credit cards. Do not use GANs that are easy to guess (such as 12345678) because they greatly increase the risk of fraud. It is the responsibility of the developer to ensure the security of their custom GANs. Example: {"type":"DIGITAL"} - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `location_id` (`string`, required): 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. Example: 81FN9BNFZTKS4 Example input: `{"gift_card":{"type":"DIGITAL"},"idempotency_key":"","location_id":""}` ### `square_inventory_changes_batch_create` Change Inventory · Write Apply inventory adjustments, physical counts, or transfers to Square catalog item variations in one batch. Returns the resulting inventory counts and the recorded changes. Use this to update stock levels; use square_inventory_counts_batch_retrieve to read them. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `changes` (`array`, optional): 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. Example: [{"physical_count":{"catalog_object_id":"W62UWFY35CWMYGVWK6TWJDNI","location_id":"C6W5YS5QM06F5","occurred_at":"2016-11-16T22:25:24.878Z","quantity":"53","reference_id":"1536bfbf-efed-48bf-b17d-a197141b2a92","state":"IN_STOCK","team_member_id":"LRK57NSQ5X7PUD05"},"type":"PHYSICAL_COUNT"}] - `ignore_unchanged_counts` (`boolean`, optional): Indicates whether the current physical count should be ignored if the quantity is unchanged since the last physical count. Default: true. Example input: `{"idempotency_key":""}` ### `square_invoice_cancel` Cancel Invoice · Write Cancel a published Square invoice so it can no longer be paid. Returns the invoice with status CANCELED. Use this to withdraw a sent invoice; drafts that were never published cannot be canceled. Requires the invoice's current version from square_invoice_get. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `invoice_id` (`string`, required): The ID of the invoice to cancel. Example: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY - `version` (`integer`, required): The version of the invoice to cancel. If you do not know the version, you can call GetInvoice or ListInvoices. Example: 0 Example input: `{"invoice_id":"","version":0}` ### `square_invoice_create` Create Invoice · Write Create a draft Square invoice for an existing order. Returns the draft invoice with its id and version. Use this to bill a customer, then call square_invoice_publish to send it. Requires an order_id from square_order_create and a customer_id for the primary recipient. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `invoice` (`object`, required): The invoice to create. Stores information about an invoice. You use the Invoices API to create and manage invoices. Example: {"accepted_payment_methods":{"bank_account":false,"buy_now_pay_later":false,"card":true,"cash_app_pay":false,"square_gift_card":false},"custom_fields":[{"label":"Event Reference Number","placement":"ABOVE_LINE_ITEMS","value":"Ref. #1234"}],"delivery_method":"EMAIL","description":"We appreciate your business!","invoice_number":"inv-100","location_id":"ES0RJRZYEC39A","order_id":"CAISENgvlJ6jLWAzERDzjyHVybY","payment_requests":[{"automatic_payment_source":"NONE","due_date":"2030-01-24","reminders":[{"message":"Your invoice is due tomorrow","relative_scheduled_days":-1}],"request_type":"BALANCE","tipping_enabled":true}]} - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 Example input: `{"invoice":{}}` ### `square_invoice_publish` Publish Invoice · Write Publish a draft Square invoice so Square emails it, charges the card on file, or makes it shareable. Returns the published invoice with its new status and public URL. Use this after square_invoice_create; use square_invoice_update to change it first. Requires the invoice's current version from square_invoice_get. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `invoice_id` (`string`, required): The ID of the invoice to publish. Example: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY - `version` (`integer`, required): The version of the invoice to publish. This must match the current version of the invoice; otherwise, the request is rejected. Example: 1 - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 Example input: `{"invoice_id":"","version":1}` ### `square_invoice_update` Update Invoice · Write Update fields on a Square invoice, such as the title, due dates, or delivery method, using the invoice's current version. Returns the updated invoice with its new version. Use this to edit a draft or published invoice; use square_invoice_cancel to stop it instead. Requires the invoice's current version from square_invoice_get. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `invoice` (`object`, required): The invoice fields to add, change, or clear. Fields can be cleared using null values or the remove field (for individual payment requests or reminders). The current invoice version is also required. Stores information about an invoice. You use the Invoices API to create and manage invoices. Example: {"payment_requests":[{"reminders":null,"tipping_enabled":false,"uid":"2da7964f-f3d2-4f43-81e8-5aa220bf3355"}],"version":1} - `invoice_id` (`string`, required): The ID of the invoice to update. Example: inv:0-ChCHu2mZEabLeeHahQnXDjZQECY - `fields_to_clear` (`array`, optional): 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. Example: ["description"] - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 Example input: `{"invoice":{},"invoice_id":""}` ### `square_location_create` Create Location · Write Create a new business location for the connected Square seller. Returns the created location with its new id. Use this to add a location; use square_location_update to change an existing one. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `location` (`object`, required): 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. Represents one of a business' locations. Example: {"address":{"address_line_1":"1234 Peachtree St. NE","administrative_district_level_1":"GA","locality":"Atlanta","postal_code":"30309"},"description":"Midtown Atlanta store","name":"Midtown"} Example input: `{"location":{}}` ### `square_location_update` Update Location · Write Update fields on an existing Square business location, such as its name, address, or business hours. Returns the updated location record. Use this to edit a location; use square_location_create to add a new one. Requires a location_id from square_locations_list. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `location` (`object`, required): The Location object with only the fields to update. Represents one of a business' locations. Example: {"business_hours":{"periods":[{"day_of_week":"FRI","end_local_time":"18:00","start_local_time":"07:00"},{"day_of_week":"SAT","end_local_time":"18:00","start_local_time":"07:00"},{"day_of_week":"SUN","end_local_time":"15:00","start_local_time":"09:00"}]},"description":"Midtown Atlanta store - Open weekends"} - `location_id` (`string`, required): The ID of the location to update. Example: L88917AVBK2S5 Example input: `{"location":{},"location_id":""}` ### `square_loyalty_account_create` Create Loyalty Account · Write Enroll a buyer in the Square Loyalty program using their phone number. Returns the created loyalty account with its id and points balance. Use this to sign up a buyer; use square_loyalty_accounts_search first to check whether they already have an account. Requires the program_id from square_loyalty_program_get. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `loyalty_account` (`object`, required): The loyalty account to create. Describes a loyalty account in a loyalty program. Example: {"mapping":{"phone_number":"+14155551234"},"program_id":"d619f755-2d17-41f3-990d-c04ecedd64dd"} Example input: `{"idempotency_key":"","loyalty_account":{}}` ### `square_loyalty_points_accumulate` Accumulate Loyalty Points · Write Add points to a Square Loyalty account for a purchase, either from an order or as a fixed number of points. Returns the loyalty events created for the accrual. Use this to reward a purchase; use square_loyalty_points_adjust for manual corrections. Requires a loyalty account_id and a location_id. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `account_id` (`string`, required): The ID of the target loyalty account. Example: 79b807d2-d786-46a9-933b-918028d7a8c5 - `accumulate_points` (`object`, required): 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. Provides metadata when the event type is ACCUMULATE_POINTS. Example: {"order_id":"RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY"} - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `location_id` (`string`, required): The location where the purchase was made. Example: P034NEENMD09F Example input: `{"account_id":"","accumulate_points":{"order_id":"RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY"},"idempotency_key":"","location_id":""}` ### `square_loyalty_points_adjust` Adjust Loyalty Points · Write Manually add or remove points on a Square Loyalty account, with an optional reason. Returns the ADJUST_POINTS loyalty event. Use this for corrections or goodwill points; use square_loyalty_points_accumulate for purchase-based points. Requires a loyalty account_id from square_loyalty_accounts_search. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `account_id` (`string`, required): The ID of the target loyalty account. Example: 79b807d2-d786-46a9-933b-918028d7a8c5 - `adjust_points` (`object`, required): 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. Provides metadata when the event type is ADJUST_POINTS. Example: {"points":10,"reason":"Complimentary points"} - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `allow_negative_balance` (`boolean`, optional): Indicates whether to allow a negative adjustment to result in a negative balance. If true, a negative balance is allowed when subtracting points. If false, Square returns a BAD_REQUEST error when subtracting the specified number of points would result in a negative balance. The default value is false. Example input: `{"account_id":"","adjust_points":{"points":10,"reason":"Complimentary points"},"idempotency_key":""}` ### `square_loyalty_reward_create` Create Loyalty Reward · Write Create a Square Loyalty reward by locking points from an account for a reward tier, optionally attached to an order. Returns the reward with its id and status ISSUED. Use this to start a redemption, then call square_loyalty_reward_redeem. Requires a loyalty account id and a reward tier id from square_loyalty_program_get. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `reward` (`object`, required): The reward to create. Represents a contract to redeem loyalty points for a reward tier discount. Loyalty rewards can be in an ISSUED, REDEEMED, or DELETED state. Example: {"loyalty_account_id":"5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd","order_id":"RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY","reward_tier_id":"e1b39225-9da5-43d1-a5db-782cdd8ad94f"} Example input: `{"idempotency_key":"","reward":{"loyalty_account_id":"5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd","order_id":"RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY","reward_tier_id":"e1b39225-9da5-43d1-a5db-782cdd8ad94f"}}` ### `square_loyalty_reward_redeem` Redeem Loyalty Reward · Write Redeem an issued Square Loyalty reward at a location. Returns the REDEEM_REWARD loyalty event. Use this after square_loyalty_reward_create when the reward is used without a Square order. Requires a reward_id from square_loyalty_reward_create. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `location_id` (`string`, required): The ID of the location where the reward is redeemed. Example: P034NEENMD09F - `reward_id` (`string`, required): The ID of the loyalty reward to redeem. Example: 9f18ac21-233a-31c3-be77-b45840f5a810 Example input: `{"idempotency_key":"","location_id":"","reward_id":""}` ### `square_order_create` Create Order · Write Create a Square order with line items, taxes, discounts, and fulfillments for a location. Returns the created order with its id, version, state, line items, and calculated totals. Use this to create an order to pay for later; use square_order_calculate to preview totals without saving. Requires a location_id from square_locations_list. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `order` (`object`, required): The order to create. If this field is set, the only other top-level field that can be set is the idempotency_key. Contains all information related to a single order to process with Square, including line items that specify the products to purchase. Order objects also include information about any associated tenders, refunds, and returns. Example: {"discounts":[{"name":"Labor Day Sale","percentage":"5","scope":"ORDER","uid":"labor-day-sale"}],"line_items":[{"base_price_money":{"amount":1599,"currency":"USD"},"name":"New York Strip Steak","quantity":"1"}],"location_id":"057P5VYJ4A5X1","reference_id":"my-order-001","taxes":[{"name":"State Sales Tax","percentage":"9","scope":"ORDER","uid":"state-sales-tax"}]} - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 Example input: `{"order":{}}` ### `square_order_pay` Pay Order · Write Pay for a Square order using one or more approved payments, or pay a zero-total order with no payments. Returns the order with state COMPLETED or updated tenders. Use this after taking delayed-capture payments for an order; use square_payment_create first to authorize them. Requires an order_id from square_order_create. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `order_id` (`string`, required): The ID of the order being paid. Example: CAISENgvlJ6jLWAzERDzjyHVybY - `order_version` (`integer`, optional): The version of the order being paid. If not supplied, the latest version will be paid. Example: 1 - `payment_ids` (`array`, optional): The IDs of the payments to collect. The payment total must match the order total. Example: ["EnZdNAlWCmfh6Mt5FMNST1o7taB","0LRiVlbXVwe8ozu4KbZxd12mvaB"] Example input: `{"idempotency_key":"","order_id":""}` ### `square_order_update` Update Order · Write Update an open Square order by sending only the changed fields and the current version, or clear fields by path. Returns the updated order with its new version. Use this to change an open order; use square_order_create for a new order. Requires the order's current version from square_order_get. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `order` (`object`, required): The sparse order containing only the fields to update and the version to which the update is being applied. Contains all information related to a single order to process with Square, including line items that specify the products to purchase. Order objects also include information about any associated tenders, refunds, and returns. Example: {"line_items":[{"base_price_money":{"amount":200,"currency":"USD"},"name":"COOKIE","quantity":"2","uid":"cookie_uid"}],"version":1} - `order_id` (`string`, required): The ID of the order to update. Example: CAISENgvlJ6jLWAzERDzjyHVybY - `fields_to_clear` (`array`, optional): The dot notation paths fields to clear. For example, line_items[uid].note. Example: ["discounts"] - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 Example input: `{"order":{},"order_id":""}` ### `square_payment_cancel` Cancel Payment · Write Cancel (void) a Square payment that is still APPROVED and not yet completed. Returns the payment with status CANCELED. Use this to void an authorization; use square_refund_create for a payment that is already COMPLETED. Requires a payment_id from square_payments_list. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `payment_id` (`string`, required): The ID of the payment to cancel. Example: R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY Example input: `{"payment_id":""}` ### `square_payment_complete` Complete Payment · Write Complete (capture) a Square payment that was created with autocomplete set to false. Returns the payment with status COMPLETED. Use this to capture a delayed-capture payment; use square_payment_cancel to void it instead. Requires a payment_id from square_payment_create. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `payment_id` (`string`, required): The unique ID identifying the payment to be completed. Example: R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY - `version_token` (`string`, optional): 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. Example: Z3okDzm2VRv5m5nE3WGx381ItTNhvjkB4VapByyz54h6o Example input: `{"payment_id":""}` ### `square_payment_create` Create Payment · Write Charge a payment source (card nonce, card on file, gift card, or an external or cash payment) for the connected Square seller. Returns the created payment with its id, status (APPROVED or COMPLETED), and amounts. Use this to take a payment; use square_payment_complete to capture a delayed payment, and square_refund_create to refund. Requires a source_id, such as a card ID from square_cards_list, a Web Payments SDK token, or "CASH" or "EXTERNAL". Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `source_id` (`string`, required): 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". Example: ccof:GaJGNaZa8x4OgDJn4GB - `accept_partial_authorization` (`boolean`, optional): If set to true and charging a Square Gift Card, a payment might be returned with amount_money equal to less than what was requested. For example, a request for $20 when charging a Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose to prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card payment. This field cannot be true when autocomplete = true. Default: false - `amount_money` (`object`, optional): 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). The currency code must match the currency associated with the business that is accepting the payment. Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. Example: {"amount":1000,"currency":"USD"} - `app_fee_money` (`object`, optional): 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). 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. To set this field, PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission is required. Represents an amount of money. Example: {"amount":10,"currency":"USD"} - `autocomplete` (`boolean`, optional): If set to true, this payment will be completed when possible. If set to false, this payment is held in an approved state until either explicitly completed (captured) or canceled (voided). Default: true - `billing_address` (`object`, optional): The buyer's billing address. Represents a postal address in a country. Example: {"address_line_1":"500 Electric Ave","locality":"New York","administrative_district_level_1":"NY","postal_code":"10003","country":"US"} - `buyer_email_address` (`string`, optional): The buyer's email address. Example: buyer@example.com - `buyer_phone_number` (`string`, optional): The buyer's phone number. Must follow the following format: 1. A leading + symbol (followed by a country code) 2. The phone number can contain spaces and the special characters ( , ) , - , and .. Alphabetical characters aren't allowed. 3. The phone number must contain between 9 and 16 digits. Example: +12125551234 - `cash_details` (`object`, optional): Additional details required when recording a cash payment (source_id is CASH). Stores details about a cash payment. Contains only non-confidential information. Example: {"buyer_supplied_money":{"amount":500,"currency":"USD"}} - `customer_details` (`object`, optional): Details about the customer making the payment. Example: {"customer_initiated":true,"seller_keyed_in":true} - `customer_id` (`string`, optional): 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. Example: W92WH6P11H4Z77CTET0RNTGFW8 - `delay_action` (`string`, optional): The action to be applied to the payment when the delay_duration has elapsed. The action must be CANCEL or COMPLETE. Default: CANCEL Allowed values: CANCEL, COMPLETE. One of: `CANCEL`, `COMPLETE`. - `delay_duration` (`string`, optional): 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. 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. Example: PT15M - `external_details` (`object`, optional): Additional details required when recording an external payment (source_id is EXTERNAL). Stores details about an external payment. Contains only non-confidential information. Example: {"source_id":"GKY2ZUSDUOHAAW7ZEJ7ZV7ZN","source_fee_money":{"amount":500,"currency":"USD"}} - `location_id` (`string`, optional): The location ID to associate with the payment. If not specified, the main location is used. Example: L88917AVBK2S5 - `note` (`string`, optional): An optional note to be entered by the developer when creating a payment. Example: Brief description - `order_id` (`string`, optional): Associates a previously created order with this payment. Example: CAISENgvlJ6jLWAzERDzjyHVybY - `reference_id` (`string`, optional): 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). Example: 123456 - `shipping_address` (`object`, optional): The buyer's shipping address. Represents a postal address in a country. Example: {"address_line_1":"500 Electric Ave","locality":"New York","administrative_district_level_1":"NY","postal_code":"10003","country":"US"} - `statement_description_identifier` (`string`, optional): 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. Example: INV-1042 - `team_member_id` (`string`, optional): An optional TeamMember ID to associate with this payment. Example: TMXUrsBWWcHTt79t - `tip_money` (`object`, optional): 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). Tips for external vendors such as a 3rd party delivery courier must be recorded using Order.service_charges. The currency code must match the currency associated with the business that is accepting the payment. Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. Example: {"amount":500,"currency":"USD"} - `verification_token` (`string`, optional): 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. Example: verf:CBASEGLHKHPjNTSLfLIUu6IbOyMgAQ Example input: `{"idempotency_key":"","source_id":""}` ### `square_payment_link_create` Create Payment Link · Write Create a Square checkout payment link for a quick one-amount payment or for a full order. Returns the payment link with its shareable URL and the order Square created for it. Use this to collect a payment online; use square_invoice_create to bill a customer with due dates instead. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `checkout_options` (`object`, optional): Describes optional fields to add to the resulting checkout page. Example: {"allow_tipping":true,"subscription_plan_id":"GKY2ZUSDUOHAAW7ZEJ7ZV7ZN","merchant_support_email":"buyer@example.com","ask_for_shipping_address":true} - `description` (`string`, optional): A description of the payment link. You provide this optional description that is useful in your application context. It is not used anywhere. Example: Requested by the customer - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `order` (`object`, optional): Describes the Order for which to create a checkout link. Contains all information related to a single order to process with Square, including line items that specify the products to purchase. Order objects also include information about any associated tenders, refunds, and returns. Example: {"location_id":"L88917AVBK2S5","reference_id":"ref-12345","source":{"name":"Sample name"},"customer_id":"W92WH6P11H4Z77CTET0RNTGFW8"} - `payment_note` (`string`, optional): A note for the payment. After processing the payment, Square adds this note to the resulting Payment. Example: Requested by the customer - `pre_populated_data` (`object`, optional): Describes fields to prepopulate in the resulting checkout page. Describes buyer data to prepopulate in the payment form. Example: {"buyer_email":"buyer@example.com","buyer_phone_number":"+12125551234","buyer_address":{"address_line_1":"500 Electric Ave","locality":"New York","administrative_district_level_1":"NY","postal_code":"10003","country":"US"}} - `quick_pay` (`object`, optional): Describes an ad hoc item and price for which to generate a quick pay checkout link. Describes an ad hoc item and price to generate a quick pay checkout link. Example: {"location_id":"A9Y43N9ABXZBP","name":"Auto Detailing","price_money":{"amount":10000,"currency":"USD"}} Example input: `{}` ### `square_payment_link_update` Update Payment Link · Write Update a Square payment link's description, checkout options, or pre-populated buyer data. Returns the updated payment link. Use this to change an existing link; use square_payment_link_create for a new one. Requires the link's current version from square_payment_link_get. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `payment_link` (`object`, required): The payment_link object describing the updates to apply. Example: {"checkout_options":{"ask_for_shipping_address":true},"version":1} - `payment_link_id` (`string`, required): The ID of the payment link to update. Example: TY4BWEDJ6AI5MBIV Example input: `{"payment_link":{},"payment_link_id":""}` ### `square_payment_update` Update Payment · Write Update the amount, tip, or other editable fields of a Square payment that is still APPROVED (not yet completed). Returns the updated payment record. Use this to adjust an authorized payment before capture; use square_payment_complete to capture it. Requires a payment_id from square_payment_create or square_payments_list. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `payment` (`object`, required): The updated Payment object. Represents a payment processed by the Square API. Example: {"amount_money":{"amount":1000,"currency":"USD"},"tip_money":{"amount":100,"currency":"USD"},"version_token":"ODhwVQ35xwlzRuoZEwKXucfu7583sPTzK48c5zoGd0g6o"} - `payment_id` (`string`, required): The ID of the payment to update. Example: R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY Example input: `{"idempotency_key":"","payment":{},"payment_id":""}` ### `square_refund_create` Refund Payment · Write Refund all or part of a completed Square payment. Returns the created refund with its id and status (usually PENDING at first). Use this for completed payments; use square_payment_cancel to void a payment that is not yet completed. Requires a payment_id from square_payments_list. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `amount_money` (`object`, required): 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). The currency code must match the currency associated with the business that is charging the card. Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. Example: {"amount":1000,"currency":"USD"} - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `app_fee_money` (`object`, optional): 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. To set this field, PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission is required. Represents an amount of money. Money fields can be signed or unsigned. Example: {"amount":10,"currency":"USD"} - `cash_details` (`object`, optional): Additional details required when recording an unlinked cash refund (destination_id is CASH). Stores details about a cash refund. Contains only non-confidential information. Example: {"seller_supplied_money":{"amount":500,"currency":"USD"}} - `customer_id` (`string`, optional): The Customer ID of the customer associated with the refund. This is required if the destination_id refers to a card on file created using the Cards API. Only allowed when unlinked=true. Example: W92WH6P11H4Z77CTET0RNTGFW8 - `destination_id` (`string`, optional): The ID indicating where funds will be refunded to. Required for unlinked refunds. 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. Example: GKY2ZUSDUOHAAW7ZEJ7ZV7ZN - `external_details` (`object`, optional): Additional details required when recording an unlinked external refund (destination_id is EXTERNAL). Stores details about an external refund. Contains only non-confidential information. Example: {"source_id":"GKY2ZUSDUOHAAW7ZEJ7ZV7ZN"} - `location_id` (`string`, optional): The location ID associated with the unlinked refund. Required for requests specifying unlinked=true. Otherwise, if included when unlinked=false, will throw an error. Example: L88917AVBK2S5 - `payment_id` (`string`, optional): The unique ID of the payment being refunded. Required when unlinked=false, otherwise must not be set. Example: R2B3Z8WMVt3EAmzYWLZvz7Y69EbZY - `payment_version_token` (`string`, optional): 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. Example: Z3okDzm2VRv5m5nE3WGx381ItTNhvjkB4VapByyz54h6o - `reason` (`string`, optional): A description of the reason for the refund. Example: Example - `team_member_id` (`string`, optional): An optional TeamMember ID to associate with this refund. Example: TMXUrsBWWcHTt79t - `unlinked` (`boolean`, optional): Indicates that the refund is not linked to a Square payment. If set to true, destination_id and location_id must be supplied while payment_id must not be provided. Example input: `{"amount_money":{"amount":1000,"currency":"USD"},"idempotency_key":""}` ### `square_subscription_cancel` Cancel Subscription · Write Schedule a Square subscription to be canceled at the end of the current billing period. Returns the subscription and the scheduled CANCEL action. Use this to end a subscription; use square_subscription_pause to stop it temporarily. Requires a subscription_id from square_subscriptions_search. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `subscription_id` (`string`, required): The ID of the subscription to cancel. Example: 8151fc89-da15-4eb9-a685-1a70883cebfc Example input: `{"subscription_id":""}` ### `square_subscription_create` Create Subscription · Write Enroll a Square customer in a subscription plan variation at a location. Returns the created subscription with id, status, start date, and charged-through date. Use this to start a subscription; use square_subscription_update to change one. Requires a plan_variation_id from square_catalog_list (type SUBSCRIPTION_PLAN_VARIATION) and a customer_id. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `customer_id` (`string`, required): The ID of the customer subscribing to the subscription plan variation. Example: CHFGVKYY8RSV93M5KCYTG4PN0G - `location_id` (`string`, required): The ID of the location the subscription is associated with. Example: S8GWD5R9QB376 - `canceled_date` (`string`, optional): 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 completes, the specified canceled_date sets the date when the subscription stops through the end of the last cycle. Example: 2026-11-01 - `card_id` (`string`, optional): 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. Example: ccof:qy5x8hHGYsgLrp4Q4GB - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `monthly_billing_anchor_date` (`integer`, optional): The day-of-the-month to change the billing date to. Example: 1 - `phases` (`array`, optional): array of phases for this subscription Example: [{"order_template_id":"U2NaowWxzXwpsZU697x7ZHOAnCNZY","ordinal":0}] - `plan_variation_id` (`string`, optional): The ID of the subscription plan variation created using the Catalog API. Example: 6JHXF3B2CW3YKHDV4XEM674H - `price_override_money` (`object`, optional): A custom price which overrides the cost of a subscription plan variation with STATIC pricing. This field does not affect itemized subscriptions with RELATIVE pricing. Instead, you should edit the Subscription's order template. Represents an amount of money. Money fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. Example: {"amount":500,"currency":"USD"} - `source` (`object`, optional): The origination details of the subscription. Example: {"name":"My Application"} - `start_date` (`string`, optional): The YYYY-MM-DD-formatted date to start the subscription. If it is unspecified, the subscription starts immediately. Example: 2023-06-20 - `tax_percentage` (`string`, optional): 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%. - `timezone` (`string`, optional): 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. Example: America/Los_Angeles Example input: `{"customer_id":"","location_id":""}` ### `square_subscription_pause` Pause Subscription · Write Schedule a pause for a Square subscription, for a number of billing cycles or until a resume date. Returns the subscription and the scheduled PAUSE action. Use this to stop billing temporarily; use square_subscription_resume to restart it. Requires a subscription_id from square_subscriptions_search. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `subscription_id` (`string`, required): The ID of the subscription to pause. Example: 8151fc89-da15-4eb9-a685-1a70883cebfc - `pause_cycle_duration` (`integer`, optional): The number of billing cycles the subscription will be paused before it is reactivated. When this is set, a RESUME action is also scheduled to take place on the subscription at the end of the specified pause cycle duration. In this case, neither resume_effective_date nor resume_change_timing may be specified. Example: 1 - `pause_effective_date` (`string`, optional): The YYYY-MM-DD-formatted date when the scheduled PAUSE action takes place on the subscription. When this date is unspecified or falls within the current billing cycle, the subscription is paused on the starting date of the next billing cycle. Example: 2026-11-01 - `pause_reason` (`string`, optional): The user-provided reason to pause the subscription. Example: Customer is traveling - `resume_change_timing` (`string`, optional): The timing whether the subscription is reactivated immediately or at the end of the billing cycle, relative to resume_effective_date. Allowed values: IMMEDIATE, END_OF_BILLING_CYCLE. One of: `IMMEDIATE`, `END_OF_BILLING_CYCLE`. - `resume_effective_date` (`string`, optional): The date when the subscription is reactivated by a scheduled RESUME action. This date must be at least one billing cycle ahead of pause_effective_date. Example: 2026-12-01 Example input: `{"subscription_id":""}` ### `square_subscription_resume` Resume Subscription · Write Schedule a paused or deactivated Square subscription to resume. Returns the subscription and the scheduled RESUME action. Use this after square_subscription_pause; use square_subscription_create for a new enrollment. Requires a subscription_id from square_subscriptions_search. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `subscription_id` (`string`, required): The ID of the subscription to resume. Example: 8151fc89-da15-4eb9-a685-1a70883cebfc - `resume_change_timing` (`string`, optional): The timing to resume a subscription, relative to the specified resume_effective_date attribute value. Allowed values: IMMEDIATE, END_OF_BILLING_CYCLE. One of: `IMMEDIATE`, `END_OF_BILLING_CYCLE`. - `resume_effective_date` (`string`, optional): The YYYY-MM-DD-formatted date when the subscription reactivated. Example: 2026-12-01 Example input: `{"subscription_id":""}` ### `square_subscription_update` Update Subscription · Write Update a Square subscription, for example its card, price override, or tax percentage. Returns the updated subscription. Use this for direct field changes; use square_subscription_pause, square_subscription_resume, or square_subscription_cancel for status changes. Requires a subscription_id from square_subscriptions_search. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `subscription` (`object`, required): 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. Represents a subscription purchased by a customer. Example: {"canceled_date":null,"card_id":"{NEW CARD ID}"} - `subscription_id` (`string`, required): The ID of the subscription to update. Example: 8151fc89-da15-4eb9-a685-1a70883cebfc Example input: `{"subscription":{},"subscription_id":""}` ### `square_team_member_create` Create Team Member · Write Create a Square team member with name, contact details, and location assignments. Returns the created team member with its new id. Use this to add staff; use square_team_member_update to edit them. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `team_member` (`object`, required): **Required** The data used to create the TeamMember object. If you include wage_setting, you must provide job_id for each job assignment. To get job IDs, call ListJobs. A record representing an individual team member for a business. Example: {"assigned_locations":{"assignment_type":"EXPLICIT_LOCATIONS","location_ids":["YSGH2WBKG94QZ","GA2Y9HSJ8KRYT"]},"email_address":"joe_doe@gmail.com","family_name":"Doe","given_name":"Joe","phone_number":"+14159283333","reference_id":"reference_id_1","status":"ACTIVE","wage_setting":{"is_overtime_exempt":true,"job_assignments":[{"annual_rate":{"amount":3000000,"currency":"USD"},"job_id":"FjS8x95cqHiMenw4f1NAUH4P","pay_type":"SALARY","weekly_hours":40},{"hourly_rate":{"amount":2000,"currency":"USD"},"job_id":"VDNpRv8da51NU8qZFC5zDWpF","pay_type":"HOURLY"}]}} - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 Example input: `{"team_member":{}}` ### `square_team_member_update` Update Team Member · Write Update a Square team member's name, contact details, status, or location assignments. Returns the updated team member. Use this to edit staff; use square_team_member_create to add new staff. Requires a team_member_id from square_team_members_search. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `team_member` (`object`, required): The team member fields to add, change, or clear. Fields can be cleared using a null value. To update wage_setting.job_assignments, you must provide the complete list of job assignments. If needed, call ListJobs to get the required job_id values. A record representing an individual team member for a business. Example: {"assigned_locations":{"assignment_type":"EXPLICIT_LOCATIONS","location_ids":["YSGH2WBKG94QZ","GA2Y9HSJ8KRYT"]},"email_address":"joe_doe@gmail.com","family_name":"Doe","given_name":"Joe","phone_number":"+14159283333","reference_id":"reference_id_1","status":"ACTIVE","wage_setting":{"is_overtime_exempt":true,"job_assignments":[{"annual_rate":{"amount":3000000,"currency":"USD"},"job_id":"FjS8x95cqHiMenw4f1NAUH4P","pay_type":"SALARY","weekly_hours":40},{"hourly_rate":{"amount":1200,"currency":"USD"},"job_id":"VDNpRv8da51NU8qZFC5zDWpF","pay_type":"HOURLY"}]}} - `team_member_id` (`string`, required): The ID of the team member to update. Example: TMXUrsBWWcHTt79t Example input: `{"team_member":{},"team_member_id":""}` ### `square_timecard_create` Create Timecard · Write Create a Square timecard for a team member at a location, with start time and optional end time and breaks. Returns the created timecard with its id and version. Use this to record worked time; use square_timecard_update to change a timecard. Requires a team_member_id and location_id. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `timecard` (`object`, required): The Timecard to be created. A record of the hourly rate, start time, and end time of a single timecard (shift) for a team member. This might include a record of the start and end times of breaks taken during the shift. Example: {"breaks":[{"break_type_id":"REGS1EQR1TPZ5","end_at":"2019-01-25T06:16:00-05:00","expected_duration":"PT5M","is_paid":true,"name":"Tea Break","start_at":"2019-01-25T06:11:00-05:00"}],"declared_cash_tip_money":{"amount":500,"currency":"USD"},"end_at":"2019-01-25T13:11:00-05:00","location_id":"PAA1RJZZKXBFG","start_at":"2019-01-25T03:11:00-05:00","team_member_id":"ormj0jJJZ5OZIzxrZYJI","wage":{"hourly_rate":{"amount":1100,"currency":"USD"},"tip_eligible":true,"title":"Barista"}} - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 Example input: `{"timecard":{}}` ### `square_timecard_update` Update Timecard · Write Update an existing Square timecard, for example to set its end time or edit breaks, using its current version. Returns the updated timecard. Use this to close or correct a timecard; use square_timecard_create for a new one. Requires a timecard id from square_timecards_search. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `timecard` (`object`, required): The updated Timecard object. A record of the hourly rate, start time, and end time of a single timecard (shift) for a team member. This might include a record of the start and end times of breaks taken during the shift. Example: {"breaks":[{"break_type_id":"REGS1EQR1TPZ5","end_at":"2019-01-25T06:16:00-05:00","expected_duration":"PT5M","id":"X7GAQYVVRRG6P","is_paid":true,"name":"Tea Break","start_at":"2019-01-25T06:11:00-05:00"}],"declared_cash_tip_money":{"amount":500,"currency":"USD"},"end_at":"2019-01-25T13:11:00-05:00","location_id":"PAA1RJZZKXBFG","start_at":"2019-01-25T03:11:00-05:00","status":"CLOSED","team_member_id":"ormj0jJJZ5OZIzxrZYJI","version":1,"wage":{"hourly_rate":{"amount":1500,"currency":"USD"},"tip_eligible":true,"title":"Bartender"}} - `timecard_id` (`string`, required): The ID of the object being updated. Example: T35HMQSN89SV4 Example input: `{"timecard":{},"timecard_id":""}` ### `square_vendor_create` Create Vendor · Write Create a Square vendor (supplier) with name, contacts, and address. Returns the created vendor with its id. Use this to add a supplier; use square_vendor_update to edit one. Read only: no. Destructive: no. Idempotent (safe to retry): no. Inputs: - `idempotency_key` (`string`, required): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 - `vendor` (`object`, required): The requested Vendor to be created. Represents a supplier to a seller. Example: {"account_number":"4025391","address":{"address_line_1":"505 Electric Ave","address_line_2":"Suite 600","administrative_district_level_1":"NY","country":"US","locality":"New York","postal_code":"10003"},"contacts":[{"email_address":"joe@joesfreshseafood.com","name":"Joe Burrow","phone_number":"1-212-555-4250"}],"name":"Joe's Fresh Seafood","note":"a vendor"} Example input: `{"idempotency_key":"","vendor":{"id":"INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4","name":"Jack's Chicken Shack","status":"ACTIVE","version":1}}` ### `square_vendor_update` Update Vendor · Write Update a Square vendor's name, contacts, address, note, or status, using its current version. Returns the updated vendor. Use this to edit a supplier; use square_vendor_create to add one. Requires a vendor_id from square_vendors_search. Read only: no. Destructive: no. Idempotent (safe to retry): yes. Inputs: - `vendor` (`object`, required): The specified Vendor to be updated. Represents a supplier to a seller. Example: {"id":"INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4","name":"Jack's Chicken Shack","status":"ACTIVE","version":1} - `idempotency_key` (`string`, optional): A unique string (for example a UUID) that identifies this request. Square uses it to make retries safe: repeating a call with the same key returns the original result instead of acting twice. Generate a new value for each distinct operation. Example: 7b0f3ec5-086a-4871-8f13-3c81b3875218 Example input: `{"vendor":{"id":"INV_V_JDKYHBWT1D4F8MFH63DBMEN8Y4","name":"Jack's Chicken Shack","status":"ACTIVE","version":1}}` ## Related Other Accounting & Finance connectors ([all 37](/agentkit/connectors/?category=accounting-finance)): - [QuickBooks](/agentkit/connectors/quickbooks/): Scalekit connector, OAuth, 117 tools - [Xero](/agentkit/connectors/xero/): Scalekit connector, OAuth, 94 tools - [Stripe](/agentkit/connectors/stripe/): Scalekit connector, Access token, 178 tools --- ## More Scalekit documentation | Resource | What it contains | When to use it | |----------|-----------------|----------------| | [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content | | [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas | | [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |