# Square on boxd

> Square provides payment processing, POS systems, invoicing, and e-commerce tools, enabling sellers to accept card payments and manage their business.

- Page: https://boxd.sh/integrations/square/
- CLI: `run square` (122 commands, 43 marked common)
- SDK: `import { square } from "@boxd/run"`; every parameter and response type is at `@boxd/run/square`
- Triggers: none
- Connect: `run auth square` (Sign in with Square), or https://app.boxd.sh/integrations/detail/square
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth square      # once: prints a link to connect your account
run square           # list its commands
run square list-cards
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { every, square } from "@boxd/run";

every("1 hour", async () => {
  const result = await square.listCards({});
  console.log(result);
});
```

Run it with `run square.run.ts`. Square has no triggers; `every()` polls on a schedule, keeps the script running as a job, and wakes the machine when it is due.

## Commands

Required flags are listed; `run square <command> --help` lists the optional ones. "common" marks what `run square` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `accept-dispute` | `square.acceptDispute()` | `--dispute-id` | 0 | Accept a dispute and acknowledge liability, returning funds to the cardholder |
| `add-group-to-customer` | `square.addGroupToCustomer()` | `--customer-id` `--group-id` | 0 | Add a customer to a customer group |
| `calculate-order` | `square.calculateOrder()` | `--order` | 1 | Preview order pricing without creating an order |
| `cancel-booking` | `square.cancelBooking()` | `--booking-id` | 2 | Cancels an existing Square booking, terminating the reservation |
| `cancel-invoice` | `square.cancelInvoice()` | `--invoice-id` `--version` | 0 | Cancels a Square invoice, preventing further payments from being collected |
| `cancel-payment` | `square.cancelPayment()` | `--payment-id` | 0 | Cancels (voids) a payment that is in APPROVED status |
| `create-batch-inventory-changes` ·common | `square.createBatchInventoryChanges()` | `--changes` `--idempotency-key` | 1 | Applies multiple inventory adjustments and physical counts in a single batch request |
| `create-bulk-customers` ·common | `square.createBulkCustomers()` | `--customers` | 0 | Create multiple customer profiles in a single request |
| `create-card` | `square.createCard()` | `--card` `--idempotency-key` `--source-id` | 1 | Create a card on file |
| `create-customer` ·common | `square.createCustomer()` | — | 12 | Create a new customer profile in Square |
| `create-customer-custom-attribute-definition` | `square.createCustomerCustomAttributeDefinition()` | `--custom-attribute-definition` | 1 | Create a customer-related custom attribute definition |
| `create-customer-group` | `square.createCustomerGroup()` | `--group` | 1 | Create a new customer group for a business |
| `create-dispute-evidence-file` | `square.createDisputeEvidenceFile()` | `--dispute-id` `--file` `--idempotency-key` | 5 | Upload a file as dispute evidence |
| `create-dispute-evidence-text` | `square.createDisputeEvidenceText()` | `--dispute-id` `--evidence-text` `--idempotency-key` | 1 | Upload text evidence for a dispute challenge |
| `create-gift-card-activity` ·common | `square.createGiftCardActivity()` | `--gift-card-activity` `--idempotency-key` | 0 | Creates a gift card activity to manage gift card balances |
| `create-invoice-attachment` | `square.createInvoiceAttachment()` | `--file` `--invoice-id` | 2 | Upload and attach a file to a Square invoice |
| `create-location` ·common | `square.createLocation()` | `--location` | 0 | Create a new business location in a Square account |
| `create-location-custom-attribute-definition` | `square.createLocationCustomAttributeDefinition()` | `--custom-attribute-definition` | 1 | Create a location-related custom attribute definition |
| `create-order` ·common | `square.createOrder()` | `--idempotency-key` `--order` | 0 | Creates a new Square order with line items, taxes, discounts, and fulfillment details |
| `create-refund` ·common | `square.createRefund()` | `--amount-money` `--idempotency-key` `--payment-id` | 4 | Refunds a Square payment in full or partially |
| `create-team-member` ·common | `square.createTeamMember()` | `--idempotency-key` `--team-member` | 0 | Create a new team member in Square |
| `delete-catalog-object` ·common | `square.deleteCatalogObject()` | `--object-id` | 0 | Delete a Square catalog object by ID |
| `delete-catalog-objects-batch` | `square.deleteCatalogObjectsBatch()` | `--object-ids` | 0 | Deletes a set of CatalogObjects based on a list of target object IDs and returns a set of successfully deleted IDs in the response |
| `delete-customer` | `square.deleteCustomer()` | `--customer-id` | 1 | Delete a Square customer profile |
| `delete-customer-custom-attribute` | `square.deleteCustomerCustomAttribute()` | `--customer-id` `--key` | 0 | Delete a custom attribute from a customer profile |
| `delete-customer-custom-attribute-definition` | `square.deleteCustomerCustomAttributeDefinition()` | `--key` | 0 | Delete a customer-related custom attribute definition |
| `delete-customer-group` | `square.deleteCustomerGroup()` | `--group-id` | 0 | Delete a customer group by its ID |
| `delete-customers-bulk` ·common | `square.deleteCustomersBulk()` | `--customer-ids` | 0 | Bulk delete customer profiles from Square |
| `delete-dispute-evidence` | `square.deleteDisputeEvidence()` | `--dispute-id` `--evidence-id` | 0 | Removes a specific piece of evidence from a dispute |
| `delete-invoice` | `square.deleteInvoice()` | `--invoice-id` | 1 | Delete a Square invoice (only DRAFT invoices can be deleted) |
| `delete-invoice-attachment` | `square.deleteInvoiceAttachment()` | `--attachment-id` `--invoice-id` | 0 | Delete an attachment from a Square invoice |
| `delete-location-custom-attribute` | `square.deleteLocationCustomAttribute()` | `--key` `--location-id` | 0 | Delete a custom attribute from a location |
| `delete-location-custom-attribute-definition` | `square.deleteLocationCustomAttributeDefinition()` | `--key` | 0 | Delete a location-related custom attribute definition |
| `delete-locations-custom-attributes-batch` | `square.deleteLocationsCustomAttributesBatch()` | `--values` | 0 | Delete custom attributes from multiple locations in a single batch request |
| `delete-merchant-custom-attribute` | `square.deleteMerchantCustomAttribute()` | `--key` `--merchant-id` | 0 | Delete a custom attribute from a merchant profile |
| `delete-merchant-custom-attribute-definition` | `square.deleteMerchantCustomAttributeDefinition()` | `--key` | 0 | Delete a merchant-related custom attribute definition |
| `delete-merchants-custom-attributes-batch` | `square.deleteMerchantsCustomAttributesBatch()` | `--values` | 0 | Delete custom attributes from multiple merchants in a single batch request |
| `delete-webhook-subscription` | `square.deleteWebhookSubscription()` | `--subscription-id` | 0 | Permanently deletes a webhook subscription by its ID |
| `get-booking` ·common | `square.getBooking()` | `--booking-id` | 0 | Retrieves detailed information about a specific Square booking by its ID |
| `get-business-booking-profile` | `square.getBusinessBookingProfile()` | `--merchant-ids` | 0 | Retrieve the business booking profile for a Square merchant via GraphQL |
| `get-current-merchant` ·common | `square.getCurrentMerchant()` | — | 0 | Retrieve merchant information associated with the access token using Square's GraphQL API |
| `get-customer-custom-attribute` | `square.getCustomerCustomAttribute()` | `--customer-id` `--key` | 2 | Retrieves a custom attribute from a customer profile in Square |
| `get-customers-custom-attribute-definitions` | `square.getCustomersCustomAttributeDefinitions()` | `--key` | 1 | Retrieve a customer-related custom attribute definition from Square |
| `get-customers-graphql` | `square.getCustomersGraphql()` | `--merchant-id` | 1 | Retrieve customer profiles from Square Customer Directory using GraphQL API |
| `get-dispute-evidence` | `square.getDisputeEvidence()` | `--dispute-id` `--evidence-id` | 0 | Retrieves detailed information about a specific piece of evidence that was uploaded for a dispute |
| `get-gift-card-from-gan` | `square.getGiftCardFromGan()` | `--gan` | 0 | Retrieves detailed information about a gift card by its GAN (gift card account number) |
| `get-invoice` | `square.getInvoice()` | `--invoice-id` | 0 | Retrieves detailed information about a specific Square invoice by its ID |
| `get-loyalty-account` ·common | `square.getLoyaltyAccount()` | `--account-id` | 0 | Retrieve detailed information about a specific Square loyalty account by ID |
| `get-merchant` ·common | `square.getMerchant()` | `--merchant-id` | 0 | Retrieve detailed information about a specific Square merchant by ID |
| `get-online-checkout-location-settings` | `square.getOnlineCheckoutLocationSettings()` | `--location-id` | 0 | Retrieve location-level settings for Square online checkout |
| `get-refund` ·common | `square.getRefund()` | `--refund-id` | 0 | Retrieves a specific payment refund by its unique ID from Square |
| `get-subscription` ·common | `square.getSubscription()` | `--subscription-id` | 1 | Retrieves detailed information about a specific Square customer subscription by its ID |
| `get-team-member` ·common | `square.getTeamMember()` | `--team-member-id` | 0 | Retrieve detailed information about a specific Square team member by ID |
| `link-customer-to-gift-card` | `square.linkCustomerToGiftCard()` | `--customer-id` `--gift-card-id` | 0 | Link a customer to a gift card in Square |
| `list-cards` ·common | `square.listCards()` | — | 5 | Retrieve cards on file associated with a Square account |
| `list-channels` ·common | `square.listChannels()` | — | 5 | List requested channels from Square |
| `list-customer-custom-attribute-definitions` | `square.listCustomerCustomAttributeDefinitions()` | — | 2 | List customer-related custom attribute definitions from Square |
| `list-customer-custom-attribute-definitions-graph-ql` | `square.listCustomerCustomAttributeDefinitionsGraphQl()` | `--merchant-ids` | 0 | Retrieve customer custom attribute definitions via Square's GraphQL API |
| `list-customer-custom-attributes` | `square.listCustomerCustomAttributes()` | `--customer-id` | 3 | List custom attributes for a customer profile |
| `list-customer-groups` ·common | `square.listCustomerGroups()` | — | 2 | Retrieve the list of customer groups of a business |
| `list-customer-segments` ·common | `square.listCustomerSegments()` | — | 2 | Retrieve the list of customer segments of a business |
| `list-customers` ·common | `square.listCustomers()` | — | 5 | Retrieve customer profiles associated with a Square account |
| `list-dispute-evidence` | `square.listDisputeEvidence()` | `--dispute-id` | 1 | List evidence items associated with a given dispute |
| `list-invoices` | `square.listInvoices()` | `--location-id` | 2 | List invoices for a Square location |
| `list-location-custom-attribute-definitions` | `square.listLocationCustomAttributeDefinitions()` | — | 3 | List location-related custom attribute definitions from Square |
| `list-locations` ·common | `square.listLocations()` | — | 0 | Retrieve all business locations from a Square account |
| `list-locations-custom-attributes` | `square.listLocationsCustomAttributes()` | `--location-id` | 4 | List custom attributes for a specific location in Square |
| `list-merchant-custom-attribute-definitions` | `square.listMerchantCustomAttributeDefinitions()` | — | 3 | List merchant-related custom attribute definitions from Square |
| `list-merchants` ·common | `square.listMerchants()` | — | 1 | Retrieve merchant account information associated with the access token |
| `list-merchants-custom-attributes` | `square.listMerchantsCustomAttributes()` | `--merchant-id` | 4 | List custom attributes for a specific merchant in Square |
| `list-payments` ·common | `square.listPayments()` | — | 15 | List payments by location and time range to enable reconciliation and net sales reporting from Square POS |
| `list-subscriptions` ·common | `square.listSubscriptions()` | — | 4 | Search and list Square customer billing subscriptions |
| `list-webhook-event-types` | `square.listWebhookEventTypes()` | — | 1 | List available webhook event types |
| `list-webhook-subscriptions` | `square.listWebhookSubscriptions()` | — | 4 | List all webhook subscriptions owned by your application |
| `pay-order` ·common | `square.payOrder()` | `--idempotency-key` `--order-id` | 2 | Pays an existing Square order by processing approved payments and completing the transaction |
| `remove-group-from-customer` | `square.removeGroupFromCustomer()` | `--customer-id` `--group-id` | 0 | Removes a customer from a customer group |
| `retrieve-bulk-customers` ·common | `square.retrieveBulkCustomers()` | `--customer-ids` | 0 | Retrieve multiple customer profiles in a single request |
| `retrieve-channel` | `square.retrieveChannel()` | `--channel-id` | 0 | Retrieve a Square channel by its ID |
| `retrieve-channels-bulk` | `square.retrieveChannelsBulk()` | `--channel-ids` | 0 | Bulk retrieve multiple Square channels by their IDs in a single request |
| `retrieve-customer` ·common | `square.retrieveCustomer()` | `--customer-id` | 0 | Retrieve detailed information about a specific Square customer by ID |
| `retrieve-customer-group` | `square.retrieveCustomerGroup()` | `--group-id` | 0 | Retrieve a specific Square customer group by ID |
| `retrieve-customer-segment` | `square.retrieveCustomerSegment()` | `--segment-id` | 0 | Retrieve a specific customer segment by its ID |
| `retrieve-dispute` | `square.retrieveDispute()` | `--dispute-id` | 0 | Retrieve a Square dispute by ID |
| `retrieve-inventory-changes` ·common | `square.retrieveInventoryChanges()` | `--catalog-object-id` | 2 | Retrieves the inventory change history for a catalog object at specified locations |
| `retrieve-inventory-counts-batch` ·common | `square.retrieveInventoryCountsBatch()` | — | 6 | Retrieve inventory counts for multiple catalog objects and locations in a single batch request |
| `retrieve-location` ·common | `square.retrieveLocation()` | `--location-id` | 0 | Retrieve detailed information about a specific Square location by ID |
| `retrieve-location-custom-attribute` | `square.retrieveLocationCustomAttribute()` | `--key` `--location-id` | 2 | Retrieves a custom attribute associated with a location in Square |
| `retrieve-location-custom-attribute-definition` | `square.retrieveLocationCustomAttributeDefinition()` | `--key` | 1 | Retrieve a location-related custom attribute definition |
| `retrieve-merchant-custom-attribute` | `square.retrieveMerchantCustomAttribute()` | `--key` `--merchant-id` | 2 | Retrieves a custom attribute associated with a merchant in Square |
| `retrieve-merchant-custom-attribute-definition` | `square.retrieveMerchantCustomAttributeDefinition()` | `--key` | 1 | Retrieve a merchant-related custom attribute definition from Square |
| `retrieve-merchants` | `square.retrieveMerchants()` | `--merchant-ids` | 0 | Retrieve merchant information including status, main location details, and capabilities using Square's GraphQL API |
| `retrieve-order` | `square.retrieveOrder()` | `--order-id` | 0 | Retrieves detailed information about a specific Square order by its ID |
| `retrieve-payment-link` | `square.retrievePaymentLink()` | `--id` | 0 | Retrieves a Square-hosted payment link by ID |
| `retrieve-token-status` | `square.retrieveTokenStatus()` | — | 0 | Retrieve information about an OAuth access token or personal access token |
| `retrieve-webhook-subscription` | `square.retrieveWebhookSubscription()` | `--subscription-id` | 0 | Retrieve a Square webhook subscription by its ID |
| `search-booking-availability` ·common | `square.searchBookingAvailability()` | `--query` | 0 | Searches for available appointment time slots for booking services at Square locations |
| `search-catalog-objects` ·common | `square.searchCatalogObjects()` | — | 8 | Searches for catalog objects (items, categories, taxes, discounts, etc.) in the Square catalog |
| `search-customers` ·common | `square.searchCustomers()` | — | 4 | Search customer profiles in Square Customer Directory |
| `search-orders` ·common | `square.searchOrders()` | `--location-ids` | 4 | Search orders across one or more Square locations with filters |
| `submit-dispute-evidence` | `square.submitDisputeEvidence()` | `--dispute-id` | 0 | Submits evidence for a dispute to the cardholder's bank |
| `test-webhook-subscription` | `square.testWebhookSubscription()` | `--subscription-id` | 1 | Tests a webhook subscription by sending a test event to the configured notification URL |
| `update-booking` ·common | `square.updateBooking()` | `--booking` `--booking-id` | 1 | Updates an existing Square booking with new appointment details, times, notes, or team members |
| `update-customer` ·common | `square.updateCustomer()` | `--customer-id` | 12 | Update an existing Square customer profile |
| `update-customer-custom-attribute-definition` | `square.updateCustomerCustomAttributeDefinition()` | `--key` | 5 | Update a customer-related custom attribute definition in Square |
| `update-customer-group` | `square.updateCustomerGroup()` | `--group` `--group-id` | 0 | Update a customer group's information by its ID |
| `update-customers-bulk` ·common | `square.updateCustomersBulk()` | `--customers` | 0 | Update multiple customer profiles in a single batch operation |
| `update-location` ·common | `square.updateLocation()` | `--location` `--location-id` | 0 | Update an existing business location in a Square account |
| `update-location-custom-attribute-definition` | `square.updateLocationCustomAttributeDefinition()` | `--custom-attribute-definition` `--key` | 1 | Update a location-related custom attribute definition in Square |
| `update-merchant-custom-attribute-definition` | `square.updateMerchantCustomAttributeDefinition()` | `--custom-attribute-definition` `--key` | 1 | Update a merchant-related custom attribute definition in Square |
| `update-online-checkout-location-settings` | `square.updateOnlineCheckoutLocationSettings()` | `--location-id` `--location-settings` | 0 | Update location-level settings for Square online checkout |
| `update-order` | `square.updateOrder()` | `--order-id` | 3 | Updates an existing Square order by adding, modifying, or removing fields |
| `update-team-member` ·common | `square.updateTeamMember()` | `--team-member` `--team-member-id` | 0 | Update an existing Square team member's information |
| `update-webhook-subscription` | `square.updateWebhookSubscription()` | `--subscription-id` | 5 | Update a Square webhook subscription |
| `update-webhook-subscription-signature-key` | `square.updateWebhookSubscriptionSignatureKey()` | `--subscription-id` | 1 | Rotate the signature key for a webhook subscription |
| `upsert-catalog-object` ·common | `square.upsertCatalogObject()` | `--idempotency-key` `--object` | 0 | Creates or updates a catalog object in the Square catalog |
| `upsert-catalog-objects-batch` ·common | `square.upsertCatalogObjectsBatch()` | `--batches` `--idempotency-key` | 0 | Creates or updates multiple catalog objects in a single batch operation |
| `upsert-customer-custom-attribute` | `square.upsertCustomerCustomAttribute()` | `--custom-attribute` `--customer-id` `--key` | 1 | Create or update a custom attribute for a customer profile |
| `upsert-customer-custom-attributes-batch` | `square.upsertCustomerCustomAttributesBatch()` | `--values` | 0 | Create or update custom attributes for multiple customers in a single batch request |
| `upsert-location-custom-attribute` | `square.upsertLocationCustomAttribute()` | `--custom-attribute` `--key` `--location-id` | 1 | Create or update a custom attribute for a location |
| `upsert-locations-custom-attributes-batch` | `square.upsertLocationsCustomAttributesBatch()` | `--values` | 0 | Create or update custom attributes for multiple locations in a single batch request |
| `upsert-merchant-custom-attribute` | `square.upsertMerchantCustomAttribute()` | `--custom-attribute` `--key` `--merchant-id` | 1 | Create or update a custom attribute for a merchant profile |
| `upsert-merchants-custom-attributes-batch` | `square.upsertMerchantsCustomAttributesBatch()` | `--values` | 0 | Create or update custom attributes for multiple merchants in a single batch request |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.