The complete list of Square CLI commands, grouped by domain.
This page lists every command the Square CLI exposes, grouped by domain. Commands follow the shape square <domain> <resource> <verb>.
For the arguments, options, and output shape of any command, run its --help or --schema:
square catalog item list --help square catalog item list --schema
To list every command as a machine-readable manifest, run square --llms --format json.
Note
This reference is generated from the CLI itself and reflects the commands available at publication. Run square --help for the exact set installed in your environment.
Show the Square CLI license notice.
| Command | Description |
|---|---|
square about | Show the Square CLI license notice. |
Apple Pay domain registration for web payments.
| Command | Description |
|---|---|
square apple-pay domain register | Activates a domain for use with Apple Pay on the Web and Square. A validation is performed on this domain by Apple to ensure that it is properly set up as an Apple Pay enabled domain |
Deploy and manage seller web apps on the Square apps platform: register an app (3–30 character lowercase alphanumeric slug with single hyphens, no leading/trailing hyphen), bundle and deploy a build to a live URL, inspect status, and promote or roll back.
| Command | Description |
|---|---|
square apps site deploy | Package a built app and deploy it to one of the app's environments. Every app has its own staging and production environments; --env picks which one (defaults to the app's staging). Select --env production explicitly to attempt deploy-and-activate, not prepare-then-promote. Server authorization and approval still apply; the production setup and what the live URL serves are not verified by this CLI. |
square apps site init | Register a new app under a slug, owned by you. Run this once before apps site deploy. The slug becomes part of the app id (app_<slug>) and the deployed URL. Re-running with a slug you already own is a no-op that returns the existing app; a slug owned by someone else fails with SLUG_TAKEN. |
square apps site list | List the apps you own, with their active staging and production URLs. |
square apps site promote | Make a specific (already-deployed) deployment the active one for an environment. Promoting returns the resulting activation status. A requires_review result means no change has taken effect; follow the returned reason and inspect status. |
square apps site rollback | Roll one of the app's environments back to its previous deployment (resolved by the platform). On success the result names the deployment now active. A requires_review result means the rollback has not taken effect; follow the returned reason — nothing has changed yet. A requires_redeploy result means the previous deployment can't be reactivated as is; redeploy it with square apps site deploy. Run square apps site status to confirm the current state at any time. |
square apps site status | Show an app's active staging and production deployments plus recent deployment history. History includes failed and uncertain attempts with recovery outcomes when available. The active deployments listed here are not proof of what the live URL serves; check the URL too. An attempt in history or its URL does not mean it is ready or active. |
Authenticate the CLI: log in via browser OAuth, inspect, and remove stored credentials.
| Command | Description |
|---|---|
square auth login | Log in to Square. Opens the browser for delegated OAuth and stores a refreshable token pair. Browser OAuth targets production unless $SQUARE_CLI_ENVIRONMENT names another configured environment. |
square auth logout | Remove the stored credentials file. |
square auth status | Show which Square API endpoint and access token the CLI would use, plus the stored login’s merchant, expiries, refreshability, and whether Square has rejected it. Pass --probe to check that the login works. |
Linked bank accounts: link, look up, and disable.
| Command | Description |
|---|---|
square bank-accounts bank-account create | Store a bank account on file for a square account |
square bank-accounts bank-account disable | Disable a bank account |
square bank-accounts bank-account get | Retrieve details of a BankAccount bank account linked to a Square account |
square bank-accounts bank-account get-by-v1-id | Returns details of a BankAccount identified by V1 bank account ID |
square bank-accounts bank-account list | Returns a list of BankAccount objects linked to a Square account. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
Custom attribute definitions and values on bookings.
| Command | Description |
|---|---|
square booking-custom-attributes booking-custom-attribute bulk-delete | Bulk deletes bookings custom attributes. To call this endpoint with buyer-level permissions, set APPOINTMENTS_WRITE for the OAuth scope |
square booking-custom-attributes booking-custom-attribute bulk-upsert | Bulk upserts bookings custom attributes. To call this endpoint with buyer-level permissions, set APPOINTMENTS_WRITE for the OAuth scope |
square booking-custom-attributes booking-custom-attribute delete | Deletes a bookings custom attribute. To call this endpoint with buyer-level permissions, set APPOINTMENTS_WRITE for the OAuth scope |
square booking-custom-attributes booking-custom-attribute get | Retrieves a bookings custom attribute. To call this endpoint with buyer-level permissions, set APPOINTMENTS_READ for the OAuth scope |
square booking-custom-attributes booking-custom-attribute list | Lists a booking's custom attributes. To call this endpoint with buyer-level permissions, set APPOINTMENTS_READ for the OAuth scope. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square booking-custom-attributes booking-custom-attribute upsert | Upserts a bookings custom attribute. To call this endpoint with buyer-level permissions, set APPOINTMENTS_WRITE for the OAuth scope |
square booking-custom-attributes definition create | Creates a bookings custom attribute definition. To call this endpoint with buyer-level permissions, set APPOINTMENTS_WRITE for the OAuth scope |
square booking-custom-attributes definition delete | Deletes a bookings custom attribute definition. To call this endpoint with buyer-level permissions, set APPOINTMENTS_WRITE for the OAuth scope |
square booking-custom-attributes definition get | Retrieves a bookings custom attribute definition. To call this endpoint with buyer-level permissions, set APPOINTMENTS_READ for the OAuth scope |
square booking-custom-attributes definition list | Get all bookings custom attribute definitions. To call this endpoint with buyer-level permissions, set APPOINTMENTS_READ for the OAuth scope. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square booking-custom-attributes definition update | Updates a bookings custom attribute definition. To call this endpoint with buyer-level permissions, set APPOINTMENTS_WRITE for the OAuth scope |
Appointments: bookings, availability, team member booking profiles.
| Command | Description |
|---|---|
square bookings availability search | Searches for availabilities for booking. To call this endpoint with buyer-level permissions, set APPOINTMENTS_READ for the OAuth scope |
square bookings booking bulk-get | Bulk-Retrieves a list of bookings by booking IDs. To call this endpoint with buyer-level permissions, set APPOINTMENTS_READ for the OAuth scope |
square bookings booking cancel | Cancels an existing booking. To call this endpoint with buyer-level permissions, set APPOINTMENTS_WRITE for the OAuth scope |
square bookings booking create | Creates a booking |
square bookings booking get | Retrieves a booking. To call this endpoint with buyer-level permissions, set APPOINTMENTS_READ for the OAuth scope |
square bookings booking list | List operational bookings with optional location, customer, team-member, and start-time filters. The Bookings API excludes recurring appointments. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square bookings booking update | Updates a booking. To call this endpoint with buyer-level permissions, set APPOINTMENTS_WRITE for the OAuth scope |
square bookings business-profile get | Retrieves a seller's booking profile |
square bookings location-profile get | Retrieves a seller's location booking profile |
square bookings location-profile list | Lists location booking profiles of a seller. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square bookings team-member-profile bulk-get | Retrieves one or more team members' booking profiles |
square bookings team-member-profile get | Retrieves a team member's booking profile |
square bookings team-member-profile list | Lists booking profiles for team members. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
Cards on file: store, look up, and disable.
| Command | Description |
|---|---|
square cards card create | Adds a card on file to an existing merchant |
square cards card disable | Disables the card, preventing any further updates or charges. Disabling an already disabled card is allowed but has no effect |
square cards card get | Retrieves details for a specific Card |
square cards card list | Retrieves a list of cards owned by the account making the request. A max of 25 cards will be returned. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
Cash drawer shifts and per-shift event journals.
| Command | Description |
|---|---|
square cash-drawers shift get | Provides the summary details for a single cash drawer shift. See ListCashDrawerShiftEvents for a list of cash drawer shift events |
square cash-drawers shift list | Provides the details for all of the cash drawer shifts for a location in a date range. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square cash-drawers shift-event list | Provides a paginated list of events for a single cash drawer shift. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
Manage catalog objects, typed catalog resources, and catalog utility endpoints.
| Command | Description |
|---|---|
square catalog availability-period create | Creates a new AVAILABILITY_PERIOD catalog object; id must be a "#"-prefixed placeholder |
square catalog availability-period get | The catalog object with the given id, typed as AVAILABILITY_PERIOD. The object's type is not verified — use catalogObject to check type when unsure |
square catalog availability-period update | Sparsely updates the existing AVAILABILITY_PERIOD catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog catalog-object batch-delete | Deletes a set of CatalogItems based on the provided list of target IDs and returns a set of successfully deleted IDs in the response. Deletion is a cascading event such that all children of the targeted object are also deleted |
square catalog catalog-object batch-get | Returns a set of objects based on the provided ID |
square catalog catalog-object batch-upsert | Creates or updates up to 10,000 target objects based on the provided list of objects. The target objects are grouped into batches and each batch is inserted/updated in an all-or-nothing manner |
square catalog catalog-object count | Count catalog objects (total and per type) by draining minimal id-only pages at the maximum page size (1000); cost is one request per 1000 objects. Run this before --all or bulk operations to size the catalog first. Without --object-types only top-level object types are counted — nested types (ITEM_VARIATION, MODIFIER, IMAGE, ITEM_OPTION_VAL) must be requested explicitly. This excludes deleted objects by default, not archived or non-sellable objects. For an active, sellable, or location-specific count, list the relevant objects and evaluate their documented state fields before counting. An id-only total cannot establish those populations. |
square catalog catalog-object delete | Deletes a single CatalogObject based on the provided ID and returns the set of successfully deleted IDs in the response. Deletion is a cascading event such that all children of the targeted object are also deleted |
square catalog catalog-object get | Returns a single CatalogItem as a CatalogObject based on the provided ID |
square catalog catalog-object list | Lists the objects in a seller's catalog. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square catalog catalog-object update | Sparse batch update of catalog objects, applied atomically: present fields replace stored values, absent fields are preserved, keyed lists (variations, modifiers, location overrides) merge per element, and unkeyed lists replace wholesale |
square catalog catalog-object upsert | Creates a new or updates the specified CatalogObject. This endpoint uses full-replacement semantics. The client must send the complete object, and any field absent from the request is interpreted as an intentional clear |
square catalog category create | Creates a new CATEGORY catalog object; id must be a "#"-prefixed placeholder |
square catalog category get | The catalog object with the given id, typed as CATEGORY. The object's type is not verified — use catalogObject to check type when unsure |
square catalog category update | Sparsely updates the existing CATEGORY catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog custom-attribute-definition create | Creates a new CUSTOM_ATTRIBUTE_DEFINITION catalog object; id must be a "#"-prefixed placeholder |
square catalog custom-attribute-definition get | The catalog object with the given id, typed as CUSTOM_ATTRIBUTE_DEFINITION. The object's type is not verified — use catalogObject to check type when unsure |
square catalog custom-attribute-definition update | Sparsely updates the existing CUSTOM_ATTRIBUTE_DEFINITION catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog discount create | Creates a new DISCOUNT catalog object; id must be a "#"-prefixed placeholder |
square catalog discount get | The catalog object with the given id, typed as DISCOUNT. The object's type is not verified — use catalogObject to check type when unsure |
square catalog discount update | Sparsely updates the existing DISCOUNT catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog image create | Upload an image file (JPEG, PNG, or GIF; max 15MB) as a new catalog image, optionally attached to a catalog object. |
square catalog image get | The catalog object with the given id, typed as IMAGE. The object's type is not verified — use catalogObject to check type when unsure |
square catalog image replace | Replace the file of an existing catalog image (JPEG, PNG, or GIF; max 15MB). The image id and its attachments are preserved; the CDN URL changes. |
square catalog info get | Retrieves information about the Square Catalog API, such as batch size limits that can be used by the BatchUpsertCatalogObjects endpoint |
square catalog item create | Creates a new ITEM catalog object; id must be a "#"-prefixed placeholder |
square catalog item get | The catalog object with the given id, typed as ITEM. The object's type is not verified — use catalogObject to check type when unsure |
square catalog item list | Lists the sellable items in a seller's catalog. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square catalog item update | Sparsely updates the existing ITEM catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog item-modifier-list update | Updates the CatalogModifierList objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item |
square catalog item-option create | Creates a new ITEM_OPTION catalog object; id must be a "#"-prefixed placeholder |
square catalog item-option get | The catalog object with the given id, typed as ITEM_OPTION. The object's type is not verified — use catalogObject to check type when unsure |
square catalog item-option update | Sparsely updates the existing ITEM_OPTION catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog item-option-value create | Creates a new ITEM_OPTION_VAL catalog object; id must be a "#"-prefixed placeholder |
square catalog item-option-value get | The catalog object with the given id, typed as ITEM_OPTION_VAL. The object's type is not verified — use catalogObject to check type when unsure |
square catalog item-option-value update | Sparsely updates the existing ITEM_OPTION_VAL catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog item-tax update | Updates the CatalogTax objects that apply to the targeted CatalogItem without having to perform an upsert on the entire item |
square catalog item-variation create | Creates a new ITEM_VARIATION catalog object; id must be a "#"-prefixed placeholder |
square catalog item-variation get | The catalog object with the given id, typed as ITEM_VARIATION. The object's type is not verified — use catalogObject to check type when unsure |
square catalog item-variation update | Sparsely updates the existing ITEM_VARIATION catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog measurement-unit create | Creates a new MEASUREMENT_UNIT catalog object; id must be a "#"-prefixed placeholder |
square catalog measurement-unit get | The catalog object with the given id, typed as MEASUREMENT_UNIT. The object's type is not verified — use catalogObject to check type when unsure |
square catalog measurement-unit update | Sparsely updates the existing MEASUREMENT_UNIT catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog menu list | Menus: catalog categories whose category_type is MENU_CATEGORY (Square Food & Beverage). Preset alias of SearchCatalogObjects; walk objects { items } for menu contents. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square catalog modifier create | Creates a new MODIFIER catalog object; id must be a "#"-prefixed placeholder |
square catalog modifier get | The catalog object with the given id, typed as MODIFIER. The object's type is not verified — use catalogObject to check type when unsure |
square catalog modifier update | Sparsely updates the existing MODIFIER catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog modifier-list create | Creates a new MODIFIER_LIST catalog object; id must be a "#"-prefixed placeholder |
square catalog modifier-list get | The catalog object with the given id, typed as MODIFIER_LIST. The object's type is not verified — use catalogObject to check type when unsure |
square catalog modifier-list update | Sparsely updates the existing MODIFIER_LIST catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog pricing-rule create | Creates a new PRICING_RULE catalog object; id must be a "#"-prefixed placeholder |
square catalog pricing-rule get | The catalog object with the given id, typed as PRICING_RULE. The object's type is not verified — use catalogObject to check type when unsure |
square catalog pricing-rule update | Sparsely updates the existing PRICING_RULE catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog product-set create | Creates a new PRODUCT_SET catalog object; id must be a "#"-prefixed placeholder |
square catalog product-set get | The catalog object with the given id, typed as PRODUCT_SET. The object's type is not verified — use catalogObject to check type when unsure |
square catalog product-set update | Sparsely updates the existing PRODUCT_SET catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog quick-amounts-settings create | Creates a new QUICK_AMOUNTS_SETTINGS catalog object; id must be a "#"-prefixed placeholder |
square catalog quick-amounts-settings get | The catalog object with the given id, typed as QUICK_AMOUNTS_SETTINGS. The object's type is not verified — use catalogObject to check type when unsure |
square catalog quick-amounts-settings update | Sparsely updates the existing QUICK_AMOUNTS_SETTINGS catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog subscription-plan create | Creates a new SUBSCRIPTION_PLAN catalog object; id must be a "#"-prefixed placeholder |
square catalog subscription-plan get | The catalog object with the given id, typed as SUBSCRIPTION_PLAN. The object's type is not verified — use catalogObject to check type when unsure |
square catalog subscription-plan update | Sparsely updates the existing SUBSCRIPTION_PLAN catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog subscription-plan-variation create | Creates a new SUBSCRIPTION_PLAN_VARIATION catalog object; id must be a "#"-prefixed placeholder |
square catalog subscription-plan-variation get | The catalog object with the given id, typed as SUBSCRIPTION_PLAN_VARIATION. The object's type is not verified — use catalogObject to check type when unsure |
square catalog subscription-plan-variation update | Sparsely updates the existing SUBSCRIPTION_PLAN_VARIATION catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog tax create | Creates a new TAX catalog object; id must be a "#"-prefixed placeholder |
square catalog tax get | The catalog object with the given id, typed as TAX. The object's type is not verified — use catalogObject to check type when unsure |
square catalog tax update | Sparsely updates the existing TAX catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
square catalog time-period create | Creates a new TIME_PERIOD catalog object; id must be a "#"-prefixed placeholder |
square catalog time-period get | The catalog object with the given id, typed as TIME_PERIOD. The object's type is not verified — use catalogObject to check type when unsure |
square catalog time-period update | Sparsely updates the existing TIME_PERIOD catalog object named by object.id: fields present in the request replace the stored values; absent fields are PRESERVED |
Sales channels a seller exposes inventory and orders through.
| Command | Description |
|---|---|
square channels channel bulk-get | Retrieves multiple channels by ID in one call, returning a per-channel success or error response |
square channels channel get | Retrieves a single sales channel by its ID |
square channels channel list | Lists the seller's sales channels, optionally filtered by status or associated entity reference. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
Hosted checkout: payment links and checkout location settings.
| Command | Description |
|---|---|
square checkout location-settings get | Retrieves the location-level settings for a Square-hosted checkout page |
square checkout location-settings update | Updates the location-level settings for a Square-hosted checkout page |
square checkout merchant-settings get | Retrieves the merchant-level settings for a Square-hosted checkout page |
square checkout merchant-settings update | Updates the merchant-level settings for a Square-hosted checkout page |
square checkout payment-link create | Creates a Square-hosted checkout page. Applications can share the resulting payment link with their buyer to pay for goods and services |
square checkout payment-link delete | Deletes a payment link |
square checkout payment-link get | Retrieves a payment link |
square checkout payment-link list | Lists all payment links. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square checkout payment-link update | Updates a payment link. You can update the payment_link fields such as description, checkout_options, and pre_populated_data. You cannot update other fields such as the order_id, version, URL, or timestamp field |
Custom attribute definitions and values on customer profiles.
| Command | Description |
|---|---|
square customer-custom-attributes customer-custom-attribute bulk-upsert | Creates or updates custom attributes for customer profiles as a bulk operation. Use this endpoint to set the value of one or more custom attributes for one or more customer profiles |
square customer-custom-attributes customer-custom-attribute delete | Deletes a custom attribute associated with a customer profile. To delete a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES |
square customer-custom-attributes customer-custom-attribute get | Retrieves a custom attribute associated with a customer profile. You can use the with_definition query parameter to also retrieve the custom attribute definition in the same call |
square customer-custom-attributes customer-custom-attribute list | Lists the custom attributes associated with a customer profile. You can use the with_definitions query parameter to also retrieve custom attribute definitions in the same call. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square customer-custom-attributes customer-custom-attribute upsert | Creates or updates a custom attribute for a customer profile. Use this endpoint to set the value of a custom attribute for a specified customer profile |
square customer-custom-attributes definition create | Creates a customer-related custom attribute definition for a Square seller account. Use this endpoint to define a custom attribute that can be associated with customer profiles |
square customer-custom-attributes definition delete | Deletes a customer-related custom attribute definition from a Square seller account. Deleting a custom attribute definition also deletes the corresponding custom attribute from all customer profiles in the seller's Customer Directory |
square customer-custom-attributes definition get | Retrieves a customer-related custom attribute definition from a Square seller account |
square customer-custom-attributes definition list | Lists the customer-related custom attribute definitions that belong to a Square seller account. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square customer-custom-attributes definition update | Updates a customer-related custom attribute definition for a Square seller account. Use this endpoint to update the following fields: name, description, visibility, or the schema for a Selection data type |
Manually curated customer groups.
| Command | Description |
|---|---|
square customer-groups customer-group create | Creates a new customer group for a business. The request must include the name value of the group |
square customer-groups customer-group delete | Deletes a customer group as identified by the group_id value |
square customer-groups customer-group get | Get one manual customer group's metadata as a bare group object. This response does not include members or a member count. To show the group, also run square customers customer search --group-ids '{"any":["GROUP_ID"]}' and page through its objects array. For a count alone, add --count --limit 1 to that customer search and read count. |
square customer-groups customer-group list | List manual customer groups. Output is {objects: [...], cursor}; match the requested group by name and retain its id. Follow cursor until null for a complete list. For members, run square customers customer search --group-ids '{"any":["GROUP_ID"]}' and read its objects array. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square customer-groups customer-group update | Updates a customer group as identified by the group_id value |
Rule-based customer segments computed by Square.
| Command | Description |
|---|---|
square customer-segments customer-segment get | Retrieves a specific customer segment as identified by the segment_id value |
square customer-segments customer-segment list | Retrieves the list of customer segments of a business. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
Customer directory: profiles, search, bulk operations, group membership, and cards on file.
| Command | Description |
|---|---|
square customers card create | Adds a card on file to an existing customer. As with charges, calls to CreateCustomerCard are idempotent |
square customers card delete | Removes a card on file from a customer |
square customers customer add-to-group | Adds a group membership to a customer. The customer is identified by the customer_id value and the customer group is identified by the group_id value |
square customers customer bulk-create | Creates multiple customer profiles for a business. This endpoint takes a map of individual create requests and returns a map of responses |
square customers customer bulk-delete | Deletes multiple customer profiles. The endpoint takes a list of customer IDs and returns a map of responses |
square customers customer bulk-get | Retrieves multiple customer profiles. This endpoint takes a list of customer IDs and returns a map of responses |
square customers customer bulk-update | Updates multiple customer profiles. This endpoint takes a map of individual update requests and returns a map of responses |
square customers customer create | Creates a new customer for a business. You must provide at least one of the following values in your request to this endpoint: - given_name - family_name - company_name - email_address - phone_number |
square customers customer delete | Deletes a customer profile from a business. To delete a customer profile that was created by merging existing profiles, you must use the ID of the newly created profile |
square customers customer get | Get one customer. Output is the bare profile with camelCase fields such as id, givenName, familyName, emailAddress, and phoneNumber; there is no customer wrapper. For narrow output use --filter-output id,givenName,familyName,emailAddress. Inspect unfiltered output if a projection is empty before concluding data is missing. |
square customers customer list | List customer profiles. Output is {objects: [...], cursor}; profile fields use camelCase (givenName, familyName, emailAddress). Name matching and missing-email searches require filtering this list locally; search has no name or email-exists filter. Save --format json output to a file, verify .objects is an array, then filter .objects[] with jq. Do not use --filter-output customers.* or objects.givenName: these paths discard the records. A missing field or {} is not evidence of an empty directory. Follow cursor until null before claiming all matches; --all handles this for suitably small directories. New profile changes may take time to appear. Before local filtering, verify exact nested fields against unprojected output or schema: state/region is address.administrativeDistrictLevel1. A guessed field path must not silently become a zero-match result. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square customers customer remove-from-group | Removes a group membership from a customer. The customer is identified by the customer_id value and the customer group is identified by the group_id value |
square customers customer search | Search customers by supported filters. Output is {objects: [...], cursor, count?} with camelCase profile fields. For a group's members, pass --group-ids '{"any":["GROUP_ID"]}'; --count --limit 1 gives its total count. Name and missing-email filters are unsupported: use customer list and filter .objects[] locally. Use --schema --format json when piping the schema to jq. A filtered {} does not establish that there are no customers. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square customers customer update | Updates a customer profile. This endpoint supports sparse updates, so only new or changed fields are required in the request. To add or update a field, specify the new value. To remove a field, specify null |
Square hardware devices and device codes.
| Command | Description |
|---|---|
square devices code create | Creates a DeviceCode that can be used to login to a Square Terminal device to enter the connected terminal mode |
square devices code get | Retrieves one DeviceCode, including its pairing secret. Use it only when the seller authorizes retrieving a pairing code; --filter-output trims what is printed, not what is retrieved. |
square devices code list | Lists DeviceCodes associated with the merchant, including each code's pairing secret. Use it only when the seller authorizes retrieving a pairing code; --filter-output trims what is printed, not what is retrieved. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square devices device get | Retrieves Device with the associated device_id |
square devices device list | List devices associated with the merchant. Currently, only Terminal API devices are supported. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
Payment disputes, evidence, and dispute lifecycle actions.
| Command | Description |
|---|---|
square disputes dispute accept | Accepts the loss on a dispute. Square returns the disputed amount to the cardholder and updates the dispute state to ACCEPTED. Square debits the disputed amount from the seller’s Square account |
square disputes dispute get | Returns details about a specific dispute |
square disputes dispute list | Returns a list of disputes associated with a particular account. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square disputes evidence delete | Removes specified evidence from a dispute. Square does not send the bank any evidence that is removed |
square disputes evidence get | Returns the metadata for the evidence specified in the request URL path. You must maintain a copy of any evidence uploaded if you want to reference it later. Evidence cannot be downloaded after you upload it |
square disputes evidence list | Returns a list of evidence associated with a dispute. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square disputes evidence submit | Submits evidence to the cardholder's bank |
square disputes evidence-text create | Uploads text to use as evidence for a dispute challenge |
Merchant event stream: event listing and event type metadata.
| Command | Description |
|---|---|
square events event disable | Disables events to prevent them from being searchable. All events are disabled by default. You must enable events to make them searchable |
square events event enable | Enables events to make them searchable. Only events that occur while in the enabled state are searchable |
square events event list | Lists the Square API events retained for the account (events from the last 28 days). Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square events type list | Lists all event types that you can subscribe to as webhooks or query using the Events API |
Gift card activity ledger: loads, redemptions, adjustments.
| Command | Description |
|---|---|
square gift-card-activities gift-card-activity create | Creates a gift card activity to manage the balance or state of a gift card. For example, create an ACTIVATE activity to activate a gift card with an initial balance before first use |
square gift-card-activities gift-card-activity list | Lists gift card activities. By default, you get gift card activities for all gift cards in the seller's account. You can optionally specify query parameters to filter the list. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
Gift cards: issuance, lookup by GAN or nonce, and customer linking.
| Command | Description |
|---|---|
square gift-cards gift-card create | Creates a digital gift card or registers a physical (plastic) gift card. The resulting gift card has a PENDING state |
square gift-cards gift-card get | Retrieves a gift card using the gift card ID |
square gift-cards gift-card get-by-gan | Retrieves a gift card using the gift card account number (GAN) |
square gift-cards gift-card get-by-nonce | Retrieves a gift card using a secure payment token that represents the gift card |
square gift-cards gift-card link-customer | Links a customer to a gift card, which is also referred to as adding a card on file |
square gift-cards gift-card list | Lists all gift cards. You can specify optional filters to retrieve a subset of the gift cards. Results are sorted by created_at in ascending order. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square gift-cards gift-card unlink-customer | Unlinks a customer from a gift card, which is also referred to as removing a card on file |
Run GraphQL operations directly against the configured endpoint.
| Command | Description |
|---|---|
square graphql run | Execute a GraphQL operation document against the configured endpoint, using the same URL and token resolution as generated commands. |
Inventory counts, adjustments, adjustment reasons, and transfer orders.
| Command | Description |
|---|---|
square inventory adjustment get | Returns the InventoryAdjustment object with the provided adjustment_id |
square inventory adjustment update | Applies an update to the provided adjustment. On success: returns the newly updated adjustment. On failure: returns a list of related errors |
square inventory adjustment-reason create | Creates a custom inventory adjustment reason |
square inventory adjustment-reason delete | Soft deletes a custom inventory adjustment reason |
square inventory adjustment-reason get | Returns the inventory adjustment reason identified by the provided reason_id. Deleted custom reasons can be retrieved by ID |
square inventory adjustment-reason list | Returns the standard and custom inventory adjustment reasons available to the seller |
square inventory adjustment-reason restore | Restores a soft-deleted custom inventory adjustment reason |
square inventory adjustment-reason update | Updates a custom inventory adjustment reason |
square inventory change batch-apply | Applies adjustments and counts to the provided item quantities. On success: returns the current calculated counts for all objects referenced in the request. On failure: returns a list of related errors |
square inventory change batch-get | Returns historical physical counts and adjustments based on the provided filter criteria. To return stock moved between locations, filter by reason_ids with TRANSFER and IN_TRANSIT. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square inventory change get | Returns a set of physical counts and inventory adjustments for the provided CatalogObject at the requested Locations. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square inventory count batch-get | Returns current counts for the provided CatalogObjects at the requested Locations. Results are paginated and sorted in descending order according to their calculated_at timestamp (newest first). Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square inventory count get | Retrieves the current calculated stock count for a given CatalogObject at a given set of Locations. Responses are paginated and unsorted. For more sophisticated queries, use a batch endpoint. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square inventory physical-count get | Returns the InventoryPhysicalCount object with the provided physical_count_id |
square inventory transfer-order cancel | Cancels a transfer order in STARTED or PARTIALLY_RECEIVED status. Any unreceived quantities will no longer be receivable and will be immediately returned to the source Location's inventory |
square inventory transfer-order create | Creates a new transfer order in DRAFT status. A transfer order represents the intent to move CatalogItemVariations from one Location to another. The source and destination locations must be different and must belong to your Square account |
square inventory transfer-order delete | Deletes a transfer order in DRAFT status. Only draft orders can be deleted. Once an order is started via StartTransferOrder, it can no longer be deleted. Creates a transfer_order.deleted webhook event |
square inventory transfer-order get | Retrieves a specific TransferOrder by ID |
square inventory transfer-order list | Lists the transfer orders of a business. Calling this without any filter returns every transfer order sorted by creation date; the list can be filtered by source location IDs, destination location IDs, or transfer order status. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square inventory transfer-order receive | Records receipt of CatalogItemVariations for a transfer order. This endpoint supports partial receiving - you can receive items in multiple batches |
square inventory transfer-order start | Changes a DRAFT transfer order to STARTED status. This decrements inventory at the source Location and marks it as in-transit. The order must be in DRAFT status and have all required fields populated |
square inventory transfer-order update | Updates an existing transfer order. This endpoint supports sparse updates, allowing you to modify specific fields without affecting others. Creates a transfer_order.updated webhook event |
Invoices: creation, delivery, payment tracking, and managed invoicing.
| Command | Description |
|---|---|
square invoices attachment delete | Removes an attachment from an invoice and permanently deletes the file. Attachments can be removed only from invoices in the DRAFT, SCHEDULED, UNPAID, or PARTIALLY_PAID state |
square invoices invoice cancel | Cancels an invoice. The seller cannot collect payments for the canceled invoice. You cannot cancel an invoice in the DRAFT state or in a terminal state: PAID, REFUNDED, CANCELED, or FAILED |
square invoices invoice create | Creates a draft invoice for an order created using the Orders API. A draft invoice remains in your account and no action is taken |
square invoices invoice delete | Deletes the specified invoice. When an invoice is deleted, the associated order status changes to CANCELED. You can only delete a draft invoice (you cannot delete a published invoice, including one that is scheduled for processing) |
square invoices invoice get | Retrieves an invoice by invoice ID |
square invoices invoice list | Returns a list of invoices for a given location. The response is paginated. If truncated, the response includes a cursor that you use in a subsequent request to retrieve the next set of invoices. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square invoices invoice publish | Publishes the specified draft invoice. After an invoice is published, Square follows up based on the invoice configuration |
square invoices invoice search | Searches for invoices from a location specified in the filter. You can optionally specify customers in the filter for whom to retrieve invoices. In the current implementation, you can only specify one location and optionally one customer. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square invoices invoice update | Updates an invoice. This endpoint supports sparse updates, so you only need to specify the fields you want to change along with the required version field. Some restrictions apply to updating invoices |
Labor: shifts, timecards, breaks, wages, and scheduling.
| Command | Description |
|---|---|
square labor break-type create | Creates a new BreakType. A BreakType is a template for creating Break objects |
square labor break-type delete | Deletes an existing BreakType. A BreakType can be deleted even if it is referenced from a Shift |
square labor break-type get | Returns a single BreakType specified by id |
square labor break-type list | Returns a paginated list of BreakType instances for a business. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square labor break-type update | Updates an existing BreakType |
square labor employee-wage get | Returns a single EmployeeWage specified by id |
square labor employee-wage list | Returns a paginated list of EmployeeWage instances for a business. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square labor scheduled-shift bulk-publish | Publishes 1 - 100 scheduled shifts. This endpoint takes a map of individual publish requests and returns a map of responses |
square labor scheduled-shift create | Creates a scheduled shift by providing draft shift details such as job ID, team member assignment, and start and end times. The following draft_shift_details fields are required: - location_id - job_id - start_at - end_at |
square labor scheduled-shift get | Retrieves a scheduled shift by ID |
square labor scheduled-shift list | List scheduled shifts, with optional location, team-member, status, and time filters. Start-time bounds are inclusive and compare the selected draft or published version. To query a half-open interval [start, end), page through the results and retain only start <= startAt < end, comparing timestamps as instants. Read draftShiftDetails.startAt for DRAFT and publishedShiftDetails.startAt for PUBLISHED; skip missing details and deleted drafts. If requesting both versions, filter each independently and keep their views separate. Count each shift ID once in overall counts; do not sum draft and published counts. For different location timezones, query each distinct boundary pair separately or fetch a covering range and filter each location against its own boundaries. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square labor scheduled-shift publish | Publishes a scheduled shift. When a scheduled shift is published, Square keeps the draft_shift_details field as is and copies it to the published_shift_details field |
square labor scheduled-shift update | Updates the draft shift details for a scheduled shift. This endpoint supports sparse updates, so only new, changed, or removed fields are required in the request. You must publish the shift to make updates public |
square labor shift create | Creates a new Shift. A Shift represents a complete workday for a single team member |
square labor shift delete | Deletes a Shift |
square labor shift get | Returns a single Shift specified by id |
square labor shift search | Returns a paginated list of Shift records for a business. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square labor shift update | Updates an existing Shift. When adding a Break to a Shift, any earlier Break instances in the Shift have the end_at property set to a valid RFC-3339 datetime string |
square labor team-member-wage get | Returns a single TeamMemberWage specified by id |
square labor team-member-wage list | Returns a paginated list of TeamMemberWage instances for a business. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square labor timecard create | Creates a new Timecard. A Timecard represents a complete workday for a single team member |
square labor timecard delete | Deletes a Timecard |
square labor timecard get | Returns a single Timecard specified by id |
square labor timecard list | List worked timecards, with optional location, team-member, status, and time filters. Workday date filters represent whole local dates. For a non-midnight interval, use --start-start-at and --start-end-at with RFC3339 timestamps and the UTC offset at each boundary. These constrain startAt, not endAt; do not also constrain the timecard's end when selecting by start time. Timestamp bounds are inclusive. For [start, end), page through all matching results and discard startAt >= end before aggregating. Different location timezones need separate boundary pairs or a covering query with per-location filtering. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square labor timecard update | Updates an existing Timecard. When adding a Break to a Timecard, any earlier Break instances in the Timecard have the end_at property set to a valid RFC-3339 datetime string |
square labor workweek-config list | List the merchant's configured workweeks for labor, timecards, and scheduling. startOfWeek and startOfDayLocalTime define the local week boundary; interpret them in each relevant location's IANA timezone from locations location list. Reuse current authenticated workweek context when supplied; otherwise read these settings before resolving a relative labor week. An empty or failed lookup does not establish a Sunday-start default. Do not guess which config applies when multiple configurations have no documented location mapping. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square labor workweek-config update | Updates a WorkweekConfig |
Custom attribute definitions and values on locations.
| Command | Description |
|---|---|
square location-custom-attributes definition create | Creates a location-related custom attribute definition for a Square seller account. Use this endpoint to define a custom attribute that can be associated with locations |
square location-custom-attributes definition delete | Deletes a location-related custom attribute definition from a Square seller account. Deleting a custom attribute definition also deletes the corresponding custom attribute from all locations |
square location-custom-attributes definition get | Retrieves a location-related custom attribute definition from a Square seller account |
square location-custom-attributes definition list | Lists the location-related custom attribute definitions that belong to a Square seller account. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square location-custom-attributes definition update | Updates a location-related custom attribute definition for a Square seller account. Use this endpoint to update the following fields: name, description, visibility, or the schema for a Selection data type |
square location-custom-attributes location-custom-attribute bulk-delete | Deletes custom attributes for locations as a bulk operation. To delete a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES |
square location-custom-attributes location-custom-attribute bulk-upsert | Creates or updates custom attributes for locations as a bulk operation. Use this endpoint to set the value of one or more custom attributes for one or more locations |
square location-custom-attributes location-custom-attribute delete | Deletes a custom attribute associated with a location. To delete a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES |
square location-custom-attributes location-custom-attribute get | Retrieves a custom attribute associated with a location. You can use the with_definition query parameter to also retrieve the custom attribute definition in the same call |
square location-custom-attributes location-custom-attribute list | Lists the custom attributes associated with a location. You can use the with_definitions query parameter to also retrieve custom attribute definitions in the same call. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square location-custom-attributes location-custom-attribute upsert | Creates or updates a custom attribute for a location. Use this endpoint to set the value of a custom attribute for a specified location |
Seller locations: addresses, hours, capabilities, and settings.
| Command | Description |
|---|---|
square locations location create | Creates a location. Creating new locations allows for separate configuration of receipt layouts, item prices, and sales reports |
square locations location get | Retrieves details of a single location. Specify "main" as the location ID to retrieve details of the main location |
square locations location list | List the seller's locations. With --format json, the CLI returns an objects array with camelCase fields, not the Connect API locations envelope. Validate that objects is an array before extracting IDs; a missing collection or failed command is not an empty location list. Inspect status and timezone for the requested scope. An inactive location can still have historical orders and sales. |
square locations location update | Updates a location |
Loyalty programs, accounts, points, promotions, and rewards.
| Command | Description |
|---|---|
square loyalty account create | Creates a loyalty account. To create a loyalty account, you must provide the program_id and a mapping with the phone_number of the buyer |
square loyalty account get | Retrieves a loyalty account |
square loyalty account list | Lists the loyalty accounts in a seller's loyalty program. Calling this without any filter returns every loyalty account; the list can be filtered by phone-number mappings or by customer IDs (the two filters cannot be combined). Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square loyalty event list | Lists the loyalty events in the program's ledger — every point-balance change (earn, redeem, adjust, expire) is recorded as an event. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square loyalty point accumulate | Adds points earned from a purchase to a loyalty account. - If you are using the Orders API to manage orders, provide the order_id |
square loyalty point adjust | Adds points to or subtracts points from a buyer's account. Use this endpoint only when you need to manually adjust points |
square loyalty point calculate | Calculates the number of points a buyer can earn from a purchase |
square loyalty program get | Retrieves the loyalty program in a seller's account, specified by the program ID or the keyword main. Loyalty programs define how buyers can earn points and redeem points for rewards |
square loyalty program list | Returns a list of loyalty programs in the seller's account. Loyalty programs define how buyers can earn points and redeem points for rewards |
square loyalty promotion cancel | Cancels a loyalty promotion. Use this endpoint to cancel an ACTIVE promotion earlier than the end date, cancel an ACTIVE promotion when an end date is not specified, or cancel a SCHEDULED promotion |
square loyalty promotion create | Creates a loyalty promotion for a loyalty program. A loyalty promotion enables buyers to earn points in addition to those earned from the base loyalty program |
square loyalty promotion get | Retrieves a loyalty promotion |
square loyalty promotion list | Lists the loyalty promotions associated with a loyalty program. Results are sorted by the created_at date in descending order (newest to oldest). Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square loyalty reward create | Creates a loyalty reward |
square loyalty reward delete | Deletes a loyalty reward by doing the following: - Returns the loyalty points back to the loyalty account. - If an order ID was specified when the reward was created (see CreateLoyaltyReward), it updates the order by removing the reward and related discounts |
square loyalty reward get | Retrieves a loyalty reward |
square loyalty reward list | Lists the loyalty rewards in the seller's loyalty program. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square loyalty reward redeem | Redeems a loyalty reward. The endpoint sets the reward to the REDEEMED terminal state. If you are using your own order processing system (not using the Orders API), you call this endpoint after the buyer paid for the purchase |
Custom attribute definitions and values on the merchant.
| Command | Description |
|---|---|
square merchant-custom-attributes definition create | Creates a merchant-related custom attribute definition for a Square seller account. Use this endpoint to define a custom attribute that can be associated with a merchant connecting to your application |
square merchant-custom-attributes definition delete | Deletes a merchant-related custom attribute definition from a Square seller account. Deleting a custom attribute definition also deletes the corresponding custom attribute from the merchant |
square merchant-custom-attributes definition get | Retrieves a merchant-related custom attribute definition from a Square seller account |
square merchant-custom-attributes definition list | Lists the merchant-related custom attribute definitions that belong to a Square seller account. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square merchant-custom-attributes definition update | Updates a merchant-related custom attribute definition for a Square seller account. Use this endpoint to update the following fields: name, description, visibility, or the schema for a Selection data type |
square merchant-custom-attributes merchant-custom-attribute bulk-delete | Deletes custom attributes for a merchant as a bulk operation. To delete a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES |
square merchant-custom-attributes merchant-custom-attribute bulk-upsert | Creates or updates custom attributes for a merchant as a bulk operation. Use this endpoint to set the value of one or more custom attributes for a merchant |
square merchant-custom-attributes merchant-custom-attribute delete | Deletes a custom attribute associated with a merchant. To delete a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES |
square merchant-custom-attributes merchant-custom-attribute get | Retrieves a custom attribute associated with a merchant. You can use the with_definition query parameter to also retrieve the custom attribute definition in the same call |
square merchant-custom-attributes merchant-custom-attribute list | Lists the custom attributes associated with a merchant. You can use the with_definitions query parameter to also retrieve custom attribute definitions in the same call. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square merchant-custom-attributes merchant-custom-attribute upsert | Creates or updates a custom attribute for a merchant. Use this endpoint to set the value of a custom attribute for a specified merchant |
The seller account: merchant records and the current-merchant context.
| Command | Description |
|---|---|
square merchants merchant get | Retrieves the Merchant object for the given merchant_id |
square merchants merchant list | Provides details about the merchant associated with a given access token. The access token used to connect your application to a Square seller is associated with a single merchant. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
OAuth token lifecycle: obtain, renew, revoke, and inspect.
| Command | Description |
|---|---|
square oauth token obtain | Returns an OAuth access token and refresh token using the authorization_code or refresh_token grant type |
square oauth token revoke | Revokes an access token generated with the OAuth flow |
square oauth token-status get | Returns information about an OAuth access token or an application’s personal access token |
Custom attribute definitions and values on orders.
| Command | Description |
|---|---|
square order-custom-attributes definition create | Creates an order-related custom attribute definition. Use this endpoint to define a custom attribute that can be associated with orders |
square order-custom-attributes definition delete | Deletes an order-related custom attribute definition from a Square seller account. Only the definition owner can delete a custom attribute definition |
square order-custom-attributes definition get | Retrieves an order-related custom attribute definition from a Square seller account |
square order-custom-attributes definition list | Lists the order-related custom attribute definitions that belong to a Square seller account. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square order-custom-attributes definition update | Updates an order-related custom attribute definition for a Square seller account. Only the definition owner can update a custom attribute definition |
square order-custom-attributes order-custom-attribute bulk-delete | Deletes order custom attributes as a bulk operation. Use this endpoint to delete one or more custom attributes from one or more orders. A custom attribute is based on a custom attribute definition in a Square seller account |
square order-custom-attributes order-custom-attribute bulk-upsert | Creates or updates order custom attributes as a bulk operation. Use this endpoint to set the values of one or more custom attributes for one or more orders. A custom attribute is based on a custom attribute definition in a Square seller account |
square order-custom-attributes order-custom-attribute delete | Deletes a custom attribute associated with an order. To delete a custom attribute owned by another application, the visibility setting must be VISIBILITY_READ_WRITE_VALUES |
square order-custom-attributes order-custom-attribute get | Retrieves a custom attribute associated with an order. You can use the with_definition query parameter to also retrieve the custom attribute definition in the same call |
square order-custom-attributes order-custom-attribute list | Lists the custom attributes associated with an order. You can use the with_definitions query parameter to also retrieve custom attribute definitions in the same call. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square order-custom-attributes order-custom-attribute upsert | Creates or updates a custom attribute for an order. Use this endpoint to set the value of a custom attribute for a specific order. A custom attribute is based on a custom attribute definition in a Square seller account |
Create, retrieve, search, calculate, clone, update, and pay Square orders.
| Command | Description |
|---|---|
square orders order batch-get | Retrieves a set of orders by their IDs. If a given order ID does not exist, the ID is ignored instead of generating an error |
square orders order calculate | Enables applications to preview order pricing without creating an order |
square orders order clone | Creates a new order, in the DRAFT state, by duplicating an existing order. The newly created order has only the core fields (such as line items, taxes, and discounts) copied from the original order |
square orders order create | Creates a new order that can include information about products for purchase and settings to apply to the purchase. To pay for a created order, see Pay for Orders |
square orders order get | Retrieves an Order by ID |
square orders order pay | Pay for an order using one or more approved payments or settle an order with a total of 0. The total of the payment_ids listed in the request must be equal to the order total |
square orders order search | Search orders at 1–10 locations per request. Repeat --location-ids for each ID, for example --location-ids FIRST_LOCATION_ID --location-ids SECOND_LOCATION_ID; never comma-join IDs. For larger scopes, read square locations location list --format json, validate its objects array, and select the requested time basis. For each location's local calendar period, group IDs by timezone, calculate each group's date-boundary offsets, then split each group into batches of at most 10. If the seller requests one shared timezone, apply and label that common window instead. Drain every batch with --all. Check command success and the objects array for each response; count completed batches before claiming the entire scope was searched. Missing collections or failed batches do not establish zero orders. Date filters nest createdAt, updatedAt, or closedAt around startAt/endAt. Choose the timestamp matching the question and set the matching --sort-field CREATED_AT, UPDATED_AT, or CLOSED_AT; mismatches fail. Both startAt and endAt are inclusive. Encode bounds with the seller's timezone offset at each boundary; for a full month, end at its last millisecond rather than midnight of the following month. Results contain an objects array; use --format json before parsing. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square orders order update | Updates an open order by adding, replacing, or deleting fields. Orders with a COMPLETED or CANCELED state cannot be updated |
Work with payment records and their lifecycle. Use Payments for tender, card status, capture, fees, individual payment details, and explicit payment-event rankings. Before listing history, decide whether the question concerns payment events or closed orders/checks. Preserve explicit payment-event wording and the seller's metric.
| Command | Description |
|---|---|
square payments payment cancel | Cancels (voids) a payment. You can use this endpoint to cancel a payment with the APPROVED status |
square payments payment cancel-by-idempotency-key | Cancels (voids) a payment identified by the idempotency key that is specified in the request |
square payments payment complete | Completes (captures) a payment. By default, payments are set to complete immediately after they are created. You can use this endpoint to complete a payment with the APPROVED status |
square payments payment create | Creates a payment using the provided source |
square payments payment get | Retrieves details for a specific payment |
square payments payment list | List payment records for payment-specific questions such as tender, status, capture, and rankings explicitly about payment events (retain payment identity and payment amount). First distinguish payment events from closed orders/checks. Use returned order IDs to join payment detail when needed, and state the selected measure. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square payments payment update | Updates a payment with the APPROVED status. You can update the amount_money and tip_money using this endpoint |
Payouts to seller bank accounts and payout ledger entries.
| Command | Description |
|---|---|
square payouts entry list | Retrieves a list of all payout entries for a specific payout. To call this endpoint, set PAYOUTS_READ for the OAuth scope. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square payouts payout get | Retrieves details of a specific payout identified by a payout ID. To call this endpoint, set PAYOUTS_READ for the OAuth scope |
square payouts payout list | Retrieves a list of all payouts for the default location. You can filter payouts by location ID, status, time range, and order them in ascending or descending order. To call this endpoint, set PAYOUTS_READ for the OAuth scope. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
Payment refunds and refund detail records.
| Command | Description |
|---|---|
square refunds refund create | Refunds a payment. You can refund the entire payment amount or a portion of it. You can use this endpoint to refund a card payment or record a refund of a cash or external payment |
square refunds refund get | Retrieves a specific refund using the refund_id |
square refunds refund list | Retrieves a list of refunds for the account making the request. Results are eventually consistent, and new refunds or changes to refunds might take several seconds to appear. The maximum results per page is 100. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
Answer sales, customer-visit, discount, and other business analytics questions with reports. List the reportable cubes and views with their measures, dimensions, and segments with metadata list, then compute a custom report with query run.
| Command | Description |
|---|---|
square reporting metadata list | List every reportable cube and view with its measures, dimensions, and segments. The full metadata is large: narrow it with --filter-output on objects[] paths, then read the descriptions of the measures and dimensions you plan to use. |
square reporting query run | Compute a custom report over discovered measures, dimensions, and segments. One page of rows per run; page with --limit and --offset. |
Square Online sites and site-level publishing state.
| Command | Description |
|---|---|
square sites site list | Lists the Square Online sites that belong to a seller. Sites are listed in descending order by the created_at date. Note: Square Online APIs are publicly available as part of an early access program |
Script snippets injected into Square Online sites.
| Command | Description |
|---|---|
square snippets snippet delete | Removes your snippet from a Square Online site. You can call ListSites to get the IDs of the sites that belong to a seller. Note: Square Online APIs are publicly available as part of an early access program |
square snippets snippet get | Retrieves your snippet from a Square Online site. A site can contain snippets from multiple snippet applications, but you can retrieve only the snippet that was added by your application |
square snippets snippet upsert | Adds a snippet to a Square Online site or updates the existing snippet on the site. The snippet code is appended to the end of the head element on every page of the site, except checkout pages |
Subscription plans, phases, and subscriber lifecycle.
| Command | Description |
|---|---|
square subscriptions action delete | Deletes a scheduled action for a subscription |
square subscriptions billing-anchor-date change | Changes the billing anchor date for a subscription |
square subscriptions event list | Lists all events for a specific subscription. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square subscriptions plan bulk-swap | Schedules a plan variation change for all active subscriptions under a given plan variation. For more information, see Swap Subscription Plan Variations |
square subscriptions plan swap | Schedules a SWAP_PLAN action to swap a subscription plan variation in an existing subscription. For more information, see Swap Subscription Plan Variations |
square subscriptions subscription cancel | Schedules a CANCEL action to cancel an active subscription. This sets the canceled_date field to the end of the active billing period. After this date, the subscription status changes from ACTIVE to CANCELED |
square subscriptions subscription create | Enrolls a customer in a subscription. If you provide a card on file in the request, Square charges the card for the subscription. Otherwise, Square sends an invoice to the customer's email address |
square subscriptions subscription get | Retrieves a specific subscription |
square subscriptions subscription list | Lists the subscriptions of a business. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square subscriptions subscription pause | Schedules a PAUSE action to pause an active subscription |
square subscriptions subscription resume | Schedules a RESUME action to resume a paused or a deactivated subscription |
square subscriptions subscription update | Updates a subscription by modifying or clearing subscription field values. To clear a field, set its value to null |
Team members, jobs, and wage settings.
| Command | Description |
|---|---|
square team job create | Creates a job in a seller account. A job defines a title and tip eligibility. Note that compensation is defined in a job assignment in a team member's wage setting |
square team job get | Retrieves a specified job |
square team job list | Lists jobs in a seller account. Results are sorted by title in ascending order. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square team job update | Updates the title or tip eligibility of a job. Changes to the title propagate to all JobAssignment, Shift, and TeamMemberWage objects that reference the job ID |
square team member bulk-create | Creates multiple TeamMember objects. The created TeamMember objects are returned on successful creates. This process is non-transactional and processes as much of the request as possible |
square team member bulk-update | Updates multiple TeamMember objects. The updated TeamMember objects are returned on successful updates. This process is non-transactional and processes as much of the request as possible |
square team member create | Creates a single TeamMember object. The TeamMember object is returned on successful creates |
square team member get | Retrieves a TeamMember object for the given TeamMember.id. Learn about Troubleshooting the Team API |
square team member list | Lists the team members of a business. Calling this without any filter returns the entire roster; the list can be filtered by location IDs, ACTIVE or INACTIVE status, or whether the team member is the Square account owner. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square team member update | Updates a single TeamMember object. The TeamMember object is returned on successful updates. Learn about Troubleshooting the Team API |
square team wage-setting get | Retrieves a WageSetting object for a team member specified by TeamMember.id. For more information, see Troubleshooting the Team API |
square team wage-setting update | Creates or updates a WageSetting object. The object is created if a WageSetting with the specified team_member_id doesn't exist. Otherwise, it fully replaces the WageSetting object for the team member |
Square Terminal checkouts, refunds, and device actions.
| Command | Description |
|---|---|
square terminal action cancel | Cancels a Terminal action request if the status of the request permits it |
square terminal action create | Creates a Terminal action request and sends it to the specified device |
square terminal action dismiss | Dismisses a Terminal action request if the status and type of the request permits it |
square terminal action get | Retrieves a Terminal action request by action_id. Terminal action requests are available for 30 days |
square terminal action list | Lists the Terminal action requests created by the account over the past 30 days. Calling this without any filter returns every available action; the list can be filtered by device ID, creation time range, status, or action type. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square terminal checkout cancel | Cancels a Terminal checkout request if the status of the request permits it |
square terminal checkout create | Creates a Terminal checkout request and sends it to the specified device to take a payment for the requested amount |
square terminal checkout dismiss | Dismisses a Terminal checkout request if the status and type of the request permits it |
square terminal checkout get | Retrieves a Terminal checkout request by checkout_id. Terminal checkout requests are available for 30 days |
square terminal checkout list | Lists the Terminal checkout requests created by the application over the past 30 days, scoped to the merchant of the access token. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square terminal refund cancel | Cancels an Interac Terminal refund request by refund request ID if the status of the request permits it |
square terminal refund create | Creates a request to refund an Interac payment completed on a Square Terminal. Refunds for Interac payments on a Square Terminal are supported only for Interac debit cards in Canada |
square terminal refund dismiss | Dismisses a Terminal refund request if the status and type of the request permits it |
square terminal refund get | Retrieves an Interac Terminal refund object by ID. Terminal refund objects are available for 30 days |
square terminal refund list | Lists the Interac Terminal refund requests created by the seller over the past 30 days — these are Terminal refunds, distinct from the payment refunds served by the Refunds API. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
Vendors the seller purchases inventory from.
| Command | Description |
|---|---|
square vendors vendor bulk-create | Creates one or more Vendor objects to represent suppliers to a seller |
square vendors vendor bulk-get | Retrieves one or more vendors of specified Vendor IDs |
square vendors vendor bulk-update | Updates one or more of existing Vendor objects as suppliers to a seller |
square vendors vendor create | Creates a single Vendor object to represent a supplier to a seller |
square vendors vendor get | Retrieves the vendor of a specified Vendor ID |
square vendors vendor list | Lists the vendors the seller purchases inventory from. Square requires a non-empty name or status filter, so to list every vendor filter on both ACTIVE and INACTIVE statuses; an omitted or empty filter is rejected with VALUE_EMPTY. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square vendors vendor update | Updates an existing Vendor object as a supplier to a seller |
Webhook subscriptions, signature keys, and test events.
| Command | Description |
|---|---|
square webhook-subscriptions signature-key update | Updates a webhook subscription by replacing the existing signature key with a new one |
square webhook-subscriptions webhook-event-type list | Lists all webhook event types that can be subscribed to |
square webhook-subscriptions webhook-subscription create | Creates a webhook subscription |
square webhook-subscriptions webhook-subscription delete | Deletes a webhook subscription |
square webhook-subscriptions webhook-subscription get | Retrieves a webhook subscription identified by its ID |
square webhook-subscriptions webhook-subscription list | Lists all webhook subscriptions owned by your application. Paginated: pass the previous response's cursor to fetch the next page; repeat until the response has no cursor. --all drains every page (slow on large datasets) |
square webhook-subscriptions webhook-subscription test | Tests a webhook subscription by sending a test event to the notification URL |
square webhook-subscriptions webhook-subscription update | Updates a webhook subscription |