Square Customer Groups API
The Customer Groups API lets applications create and manage groups of customers, enabling segmentation for targeted marketing, pricing rules, and loyalty programs.
OpenAPI Specification
openapi: 3.0.0
info:
version: '2.0'
title: Square
description: >-
Supercharge Square for sellers of every size. Our entire connected commerce
platform from elegant hardware to a rich suite of Square APIs is yours to
build with. Whether youre developing an app or composing a bespoke solution,
this is the place to make it happen.
termsOfService: https://connect.squareup.com/tos
contact:
name: Square Developer Platform
email: [email protected]
url: https://squareup.com/developers
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
externalDocs:
description: 'Read the official documentation here:'
url: https://docs.connect.squareup.com/
x-server-configuration:
default-environment: production
default-server: default
environments:
- name: production
servers:
- name: default
url: https://connect.squareup.com
- name: sandbox
servers:
- name: default
url: https://connect.squareupsandbox.com
- name: custom
servers:
- name: default
url: '{custom_url}'
parameters:
- name: custom_url
description: >-
Sets the base URL requests are made to. Defaults to
`https://connect.squareup.com`
type: string
example: https://connect.squareup.com
x-square-generic-error-codes:
- ACCESS_TOKEN_EXPIRED
- ACCESS_TOKEN_REVOKED
- API_VERSION_INCOMPATIBLE
- APPLICATION_DISABLED
- ARRAY_EMPTY
- ARRAY_LENGTH_TOO_LONG
- ARRAY_LENGTH_TOO_SHORT
- BAD_CERTIFICATE
- BAD_GATEWAY
- BAD_REQUEST
- CONFLICT
- CONFLICTING_PARAMETERS
- CURRENCY_MISMATCH
- EXPECTED_ARRAY
- EXPECTED_BASE64_ENCODED_BYTE_ARRAY
- EXPECTED_BOOLEAN
- EXPECTED_FLOAT
- EXPECTED_INTEGER
- EXPECTED_JSON_BODY
- EXPECTED_MAP
- EXPECTED_OBJECT
- EXPECTED_STRING
- FORBIDDEN
- GATEWAY_TIMEOUT
- GONE
- IDEMPOTENCY_KEY_REUSED
- INCORRECT_TYPE
- INSUFFICIENT_SCOPES
- INTERNAL_SERVER_ERROR
- INVALID_ARRAY_VALUE
- INVALID_CONTENT_TYPE
- INVALID_CURSOR
- INVALID_ENUM_VALUE
- INVALID_FORM_VALUE
- INVALID_SORT_ORDER
- INVALID_SQUARE_VERSION_FORMAT
- INVALID_TIME
- INVALID_TIME_RANGE
- INVALID_VALUE
- LOCATION_MISMATCH
- MAP_KEY_LENGTH_TOO_LONG
- MAP_KEY_LENGTH_TOO_SHORT
- MERCHANT_SUBSCRIPTION_NOT_FOUND
- METHOD_NOT_ALLOWED
- MISSING_REQUIRED_PARAMETER
- NOT_ACCEPTABLE
- NOT_FOUND
- NOT_IMPLEMENTED
- NO_FIELDS_SET
- RATE_LIMITED
- REQUEST_ENTITY_TOO_LARGE
- REQUEST_TIMEOUT
- SANDBOX_NOT_SUPPORTED
- SERVICE_UNAVAILABLE
- TOO_MANY_MAP_ENTRIES
- UNAUTHORIZED
- UNEXPECTED_VALUE
- UNKNOWN_BODY_PARAMETER
- UNKNOWN_QUERY_PARAMETER
- UNPROCESSABLE_ENTITY
- UNSUPPORTED_MEDIA_TYPE
- V1_ACCESS_TOKEN
- V1_APPLICATION
- VALUE_EMPTY
- VALUE_REGEX_MISMATCH
- VALUE_TOO_HIGH
- VALUE_TOO_LONG
- VALUE_TOO_LOW
- VALUE_TOO_SHORT
servers:
- url: https://connect.squareup.com
variables: {}
components:
securitySchemes:
oauth2:
type: oauth2
x-additional-headers:
- name: Square-Version
description: Square Connect API versions
schema:
default: '2025-01-23'
flows:
authorizationCode:
authorizationUrl: https://connect.squareup.com/oauth2/authorize
tokenUrl: https://connect.squareup.com/oauth2/token
scopes:
ADDON_CONFIGURATIONS_READ: >-
__HTTP Method__: `GET`
Grants write access for third-party Add-ons to read configurations
of their Add-ons, for example, when calling
`RetrieveConfiguration` endpoint.
ADDON_CONFIGURATIONS_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access for third-party Add-ons to store
configurations of their Add-ons, for example, when calling
`CreateConfiguration` endpoint.
APPOINTMENTS_ALL_READ: >-
__HTTP Method__: `GET`, `POST`
Grants read access to all of a seller's booking information,
calendar, and business details.
This permission must be accompanied by the `APPOINTMENTS_READ`
permission.
APPOINTMENTS_ALL_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to all booking details, including
double-booking a seller.
This permission must be accompanied by the `APPOINTMENTS_WRITE`
permission.
APPOINTMENTS_BUSINESS_SETTINGS_READ: >-
__HTTP Method__: `GET`
Grants read access to booking business settings. For example, to
call the
ListTeamMemberBookingProfiles endpoint.
APPOINTMENTS_READ: >-
__HTTP Method__: `GET`, `POST`
Grants read access to booking information. For example, to call
the
RetrieveBooking endpoint.
APPOINTMENTS_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to booking information. For example, to call
the CreateBooking endpoint.
BANK_ACCOUNTS_READ: >-
__HTTP Method__: `GET`
Grants read access to bank account information associated with the
targeted
Square account. For example, to call the Connect v1
ListBankAccounts endpoint.
CASH_DRAWER_READ: >-
__HTTP Method__: `GET`
Grants read access to cash drawer shift information. For example,
to call the
ListCashDrawerShifts endpoint.
CHANNELS_CREATE: >-
__HTTP Method__: `POST`
Grants write access to create channels, for example, when calling
the
`CreateChannel` endpoint.
CHANNELS_READ: |-
__HTTP Method__: `GET`
Grants read access to view channels, for example, when calling the
`RetrieveChannel` endpoint.
CHANNELS_UPDATE: >-
__HTTP Method__: `PUT`
Grants write access to update channels, for example, when calling
the
`UpdateChannel` endpoint.
CUSTOMERS_READ: >-
__HTTP Method__: `GET`
Grants read access to customer information. For example, to call
the
ListCustomers endpoint.
CUSTOMERS_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to customer information. For example, to
create and update
customer profiles.
DEVICES_READ: |-
__HTTP Method__: `GET`
Grants read access to device information. For example, to
call the `GetDevice` and `ListDevices` endpoints.
DEVICE_CREDENTIAL_MANAGEMENT: >-
__HTTP Method__: `POST`, `GET`
Grants read/write access to device credentials information. For
example, to
call the CreateDeviceCode endpoint.
DISPUTES_READ: >-
__HTTP Method__: `GET`
Grants read access to dispute information. For example, to call
the RetrieveDispute
endpoint.
DISPUTES_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to dispute information. For example, to call
the SubmitEvidence
endpoint.
EMPLOYEES_READ: >-
__HTTP Method__: `GET`
Grants read access to employee profile information. For example,
to call the
Connect v1 Employees API.
EMPLOYEES_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to employee profile information. For example,
to create
and modify employee profiles.
GIFTCARDS_READ: >-
__HTTP Method__: `GET`, `POST`
Grants read access to gift card information. For example, to call
the RetrieveGiftCard
endpoint.
GIFTCARDS_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to gift card information. For example, to call
the CreateGiftCard
endpoint.
INVENTORY_READ: >-
__HTTP Method__: `GET`
Grants read access to inventory information. For example, to call
the
RetrieveInventoryCount endpoint.
INVENTORY_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to inventory information. For example, to call
the
BatchChangeInventory endpoint.
INVOICES_READ: >-
__HTTP Method__: `GET`, `POST`
Grants read access to invoice information. For example, to call
the ListInvoices endpoint.
INVOICES_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to invoice information. For example, to call
the CreateInvoice endpoint.
ITEMS_READ: >-
__HTTP Method__: `GET`
Grants read access to product catalog information. For example, to
obtain objects in a product catalog.
ITEMS_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to product catalog information. For example,
to modify or
add to a product catalog.
LOYALTY_READ: >-
__HTTP Method__: `GET`
Grants read access to loyalty information. For example, to call
the
ListLoyaltyPrograms endpoint.
LOYALTY_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to loyalty information. For example, to call
the
CreateLoyaltyAccount endpoint.
MERCHANT_PROFILE_READ: >-
__HTTP Method__: `GET`
Grants read access to business and location information. For
example, to
obtain a location ID for subsequent activity.
MERCHANT_PROFILE_WRITE: >-
__HTTP Method__: `POST`, `PUT`
Grants write access to business and location information. For
example, to create a new location or
update the business hours at an existing location.
ONLINE_STORE_SITE_READ: |-
__HTTP Method__: `GET`, `POST`
Read access to ECOM online store site details.
ONLINE_STORE_SNIPPETS_READ: |-
__HTTP Method__: `GET`, `POST`
Read access to ECOM online store snippets on published websites.
ONLINE_STORE_SNIPPETS_WRITE: |-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Write access to ECOM online store snippets on published websites.
ORDERS_READ: |-
__HTTP Method__: `GET`
Grants read access to order information. For example, to call the
BatchRetrieveOrders endpoint.
ORDERS_WRITE: |-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to order information. For example, to call the
CreateCheckout endpoint.
PAYMENTS_READ: >-
__HTTP Method__: `GET`
Grants read access to transaction and refund information. For
example, to call
the RetrieveTransaction endpoint.
PAYMENTS_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to transaction and refunds information. For
example, to
process payments with the Payments or Checkout API.
PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Allow third party applications to deduct a portion of each
transaction amount.
__Required__ to use multiparty transaction functionality with the
Payments
API.
PAYMENTS_WRITE_IN_PERSON: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to payments and refunds information. For
example, to
process in-person payments.
PAYMENTS_WRITE_SHARED_ONFILE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Allows the developer to process payments on behalf of a seller
using a shared on file payment method.
PAYOUTS_READ: >-
__HTTP Method__: `GET`
Grants read access to payouts and payout entries information. For
example,
to call the Connect v2 `ListPayouts` endpoint.
PERMISSION_SETS_READ: >-
__HTTP Method__: `GET`
Grants read access to Permission Sets. For example, to
call the `ListPermissionSets` and `RetrievePermissionSet`
endpoints.
PERMISSION_SETS_WRITE: |-
__HTTP Method__: `PUT`
Grants write access to Permission Sets.
RESERVATIONS_READ: >-
__HTTP Method__: `GET`
Grants read access to reservation information, for example, when
calling the
`RetrieveReservation` endpoint.
RESERVATIONS_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to reservation information, for example, when
calling the
`CreateReservation` endpoint.
RESTAURANT_CHECKS_READ: >-
__HTTP Method__: `GET`
Grants read access to check information, for example, when calling
the
`RetrieveCheck` endpoint.
SETTLEMENTS_READ: >-
__HTTP Method__: `GET`
Grants read access to settlement (deposit) information. For
example, to call
the Connect v1 ListSettlements endpoint.
SUBSCRIPTIONS_READ: >-
__HTTP Method__: `GET`, `POST`
Grants read access to subscription information. For example, to
call the RetrieveSubscription
endpoint.
SUBSCRIPTIONS_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to subscription information. For example, to
call the CreateSubscription
endpoint.
TIMECARDS_READ: >-
__HTTP Method__: `GET`
Grants read access to employee timecard information. For example,
to call the
Connect v2 SearchShifts endpoint.
TIMECARDS_SETTINGS_READ: >-
__HTTP Method__: `GET`
Grants read access to employee timecard settings information. For
example, to
call the GetBreakType endpoint.
TIMECARDS_SETTINGS_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to employee timecard settings information. For
example, to
call the UpdateBreakType endpoint.
TIMECARDS_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to employee shift information. For example, to
create
and modify employee shifts.
VENDOR_READ: >-
__HTTP Method__: `GET`, `POST`
Grants read access to vendor information, for example, when
calling the
`RetrieveVendor` endpoint.
VENDOR_WRITE: >-
__HTTP Method__: `POST`, `PUT`, `DELETE`
Grants write access to vendor information, for example, when
calling the
`BulkUpdateVendors` endpoint.
oauth2ClientSecret:
type: apiKey
in: header
name: Authorization
schemas:
ACHDetails:
type: object
description: >-
ACH-specific details about `BANK_ACCOUNT` type payments with the
`transfer_type` of `ACH`.
x-release-status: PUBLIC
properties:
routing_number:
type: string
description: The routing number for the bank account.
maxLength: 50
nullable: true
account_number_suffix:
type: string
description: The last few digits of the bank account number.
minLength: 1
maxLength: 4
nullable: true
account_type:
type: string
description: >-
The type of the bank account performing the transfer. The account
type can be `CHECKING`,
`SAVINGS`, or `UNKNOWN`.
maxLength: 50
nullable: true
AcceptDisputeRequest:
type: object
description: Defines the request parameters for the `AcceptDispute` endpoint.
x-release-status: PUBLIC
properties: {}
example: {}
AcceptDisputeResponse:
type: object
description: Defines the fields in an `AcceptDispute` response.
x-release-status: PUBLIC
properties:
errors:
type: array
items:
$ref: '#/components/schemas/Error'
description: Information about errors encountered during the request.
dispute:
$ref: '#/components/schemas/Dispute'
description: Details about the accepted dispute.
example:
dispute:
amount_money:
amount: 2500
currency: USD
brand_dispute_id: '100000809947'
card_brand: VISA
created_at: '2022-06-29T18:45:22.265Z'
disputed_payment:
payment_id: zhyh1ch64kRBrrlfVhwjCEjZWzNZY
due_at: '2022-07-13T00:00:00.000Z'
id: XDgyFu7yo1E2S5lQGGpYn
location_id: L1HN3ZMQK64X9
reason: NO_KNOWLEDGE
reported_at: '2022-06-29T00:00:00.000Z'
state: ACCEPTED
updated_at: '2022-07-07T19:14:42.650Z'
version: 2
AcceptedPaymentMethods:
type: object
x-release-status: PUBLIC
properties:
apple_pay:
type: boolean
description: Whether Apple Pay is accepted at checkout.
nullable: true
google_pay:
type: boolean
description: Whether Google Pay is accepted at checkout.
nullable: true
cash_app_pay:
type: boolean
description: Whether Cash App Pay is accepted at checkout.
nullable: true
afterpay_clearpay:
type: boolean
description: Whether Afterpay/Clearpay is accepted at checkout.
nullable: true
AccumulateLoyaltyPointsRequest:
type: object
description: >-
Represents an
[AccumulateLoyaltyPoints](api-endpoint:Loyalty-AccumulateLoyaltyPoints)
request.
x-release-status: PUBLIC
x-params-example: '?account_id=5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd'
required:
- accumulate_points
- idempotency_key
- location_id
properties:
accumulate_points:
$ref: '#/components/schemas/LoyaltyEventAccumulatePoints'
description: >-
The points to add to the account.
If you are using the Orders API to manage orders, specify the order
ID.
Otherwise, specify the points to add.
idempotency_key:
type: string
description: >-
A unique string that identifies the `AccumulateLoyaltyPoints`
request.
Keys can be any valid string but must be unique for every request.
minLength: 1
maxLength: 128
location_id:
type: string
description: The [location](entity:Location) where the purchase was made.
example:
accumulate_points:
order_id: RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY
idempotency_key: 58b90739-c3e8-4b11-85f7-e636d48d72cb
location_id: P034NEENMD09F
AccumulateLoyaltyPointsResponse:
type: object
description: >-
Represents an
[AccumulateLoyaltyPoints](api-endpoint:Loyalty-AccumulateLoyaltyPoints)
response.
x-release-status: PUBLIC
properties:
errors:
type: array
items:
$ref: '#/components/schemas/Error'
description: Any errors that occurred during the request.
event:
$ref: '#/components/schemas/LoyaltyEvent'
description: >-
The resulting loyalty event. Starting in Square version 2022-08-17,
this field is no longer returned.
x-release-status: DEPRECATED
events:
type: array
items:
$ref: '#/components/schemas/LoyaltyEvent'
description: >-
The resulting loyalty events. If the purchase qualifies for points,
the `ACCUMULATE_POINTS` event
is always included. When using the Orders API, the
`ACCUMULATE_PROMOTION_POINTS` event is included
if the purchase also qualifies for a loyalty promotion.
example:
events:
- accumulate_points:
loyalty_program_id: d619f755-2d17-41f3-990d-c04ecedd64dd
order_id: RFZfrdtm3mhO1oGzf5Cx7fEMsmGZY
points: 6
created_at: '2020-05-08T21:41:12Z'
id: ee46aafd-1af6-3695-a385-276e2ef0be26
location_id: P034NEENMD09F
loyalty_account_id: 5adcb100-07f1-4ee7-b8c6-6bb9ebc474bd
source: LOYALTY_API
type: ACCUMULATE_POINTS
ActionCancelReason:
type: string
enum:
- BUYER_CANCELED
- SELLER_CANCELED
- TIMED_OUT
x-enum-elements:
- name: BUYER_CANCELED
description: A person canceled the `TerminalCheckout` from a Square device.
- name: SELLER_CANCELED
description: A client canceled the `TerminalCheckout` using the API.
- name: TIMED_OUT
description: >-
The `TerminalCheckout` timed out (see `deadline_duration` on the
`TerminalCheckout`).
x-release-status: PUBLIC
ActivityType:
type: string
enum:
- ADJUSTMENT
- APP_FEE_REFUND
- APP_FEE_REVENUE
- AUTOMATIC_SAVINGS
- AUTOMATIC_SAVINGS_REVERSED
- CHARGE
- DEPOSIT_FEE
- DEPOSIT_FEE_REVERSED
- DISPUTE
- ESCHEATMENT
- FEE
- FREE_PROCESSING
- HOLD_ADJUSTMENT
- INITIAL_BALANCE_CHANGE
- MONEY_TRANSFER
- MONEY_TRANSFER_REVERSAL
- OPEN_DISPUTE
- OTHER
- OTHER_ADJUSTMENT
- PAID_SERVICE_FEE
- PAID_SERVICE_FEE_REFUND
- REDEMPTION_CODE
- REFUND
- RELEASE_ADJUSTMENT
- RESERVE_HOLD
- RESERVE_RELEASE
- RETURNED_PAYOUT
- SQUARE_CAPITAL_PAYMENT
- SQUARE_CAPITAL_REVERSED_PAYMENT
- SUBSCRIPTION_FEE
- SUBSCRIPTION_FEE_PAID_REFUND
- SUBSCRIPTION_FEE_REFUND
- TAX_ON_FEE
- THIRD_PARTY_FEE
- THIRD_PARTY_FEE_REFUND
- PAYOUT
- AUTOMATIC_BITCOIN_CONVERSIONS
- AUTOMATIC_BITCOIN_CONVERSIONS_REVERSED
- CREDIT_CARD_REPAYMENT
- CREDIT_CARD_REPAYMENT_REVERSED
- LOCAL_OFFERS_CASHBACK
- LOCAL_OFFERS_FEE
- PERCENTAGE_PROCESSING_ENROLLMENT
- PERCENTAGE_PROCESSING_DEACTIVATION
- PERCENTAGE_PROCESSING_REPAYMENT
- PERCENTAGE_PROCESSING_REPAYMENT_REVERSED
- PROCESSING_FEE
- PROCESSING_FEE_REFUND
- UNDO_PROCESSING_FEE_REFUND
- GIFT_CARD_LOAD_FEE
- GIFT_CARD_LOAD_FEE_REFUND
- UNDO_GIFT_CARD_LOAD_FEE_REFUND
- BALANCE_FOLDERS_TRANSFER
- BALANCE_FOLDERS_TRANSFER_REVERSED
- GIFT_CARD_POOL_TRANSFER
- GIFT_CARD_POOL_TRANSFER_REVERSED
- SQUARE_PAYROLL_TRANSFER
- SQUARE_PAYROLL_TRANSFER_REVERSED
x-enum-elements:
- name: ADJUSTMENT
description: A manual adjustment applied to the seller's account by Square.
- name: APP_FEE_REFUND
description: A refund for an application fee on a payment.
- name: APP_FEE_REVENUE
description: Revenue generated from an application fee on a payment.
- name: AUTOMATIC_SAVINGS
description: >-
An automatic transfer from the payment processing balance to the
Square Savings account. These are generally proportional to the
seller's sales.
- name: AUTOMATIC_SAVINGS_REVERSED
description: >-
An automatic transfer from the Square Savings account back to the
processing balance. These are generally proportional to the seller's
refunds.
- name: CHARGE
description: A credit card payment capture.
- name: DEPOSIT_FEE
description: A fee assessed because of a deposit, such as an instant deposit.
- name: DEPOSIT_FEE_REVERSED
description: >-
Indicates that Square returned a fee that was previously assessed
because of a deposit, such as an instant deposit, back to the
seller's account.
- name: DISPUTE
description: The balance change due to a dispute event.
- name: ESCHEATMENT
description: An escheatment entry for remittance.
- name: FEE
description: The cost plus adjustment fee.
- name: FREE_PROCESSING
description: >-
Square offers free payments processing for a variety of business
scenarios, including seller
referrals or when Square wants to apologize (for example, for a bug,
customer service, or repricing complication).
This entry represents a credit to the seller for the purposes of
free processing.
- name: HOLD_ADJUSTMENT
description: An adjustment made by Square related to holding a payment.
- name: INITIAL_BALANCE_CHANGE
description: >-
An external change to a seller's balance (initial, in the sense that
it causes the creation of the other activity types, such as a hold
and refund).
- name: MONEY_TRANSFER
description: The balance change from a money transfer.
- name: MONEY_TRANSFER_REVERSAL
description: The reversal of a money transfer.
- name: OPEN_DISPUTE
description: The balance change for a chargeback that's been filed.
- name: OTHER
description: Any other type that doesn't belong in the rest of the types.
- name: OTHER_ADJUSTMENT
description: Any other type of adjustment that doesn't fall under existing types.
- name: PAID_SERVICE_FEE
description: A fee paid to a third-party seller.
- name: PAID_SERVICE_FEE_REFUND
description: A fee refunded to a third-party seller.
- name: REDEMPTION_CODE
description: Repayment for a redemption code.
- name: REFUND
description: A refund for an existing card payment.
- name: RELEASE_ADJUSTMENT
description: An adjustment made by Square related to releasing a payment.
- name: RESERVE_HOLD
description: Fees paid for a funding risk reserve.
- name: RESERVE_RELEASE
description: Fees released from a risk reserve.
- name: RETURNED_PAYOUT
description: >-
An entry created when Square receives a response for the ACH file
that Square sent indicating that the
settlement of the original entry failed.
- name: SQUARE_CAPITAL_PAYMENT
description: >-
A capital merchant cash advance (MCA) assessment. These are
generally proportional to the merchant's sales but can be issued for
other reasons related to the MCA.
- name: SQUARE_CAPITAL_REVERSED_PAYMENT
description: >-
A capital merchant cash advance (MCA) assessment refund. These are
generally proportional to the merchant's refunds but can be issued
for other reasons related to the MCA.
- name: SUBSCRIPTION_FEE
description: A fee charged for subscription to a Square product.
- name: SUBSCRIPTION_FEE_PAID_REFUND
description: A Square subscription fee that's been refunded.
- name: SUBSCRIPTION_FEE_REFUND
description: The refund of a previously charged Square product subscription fee.
- name: TAX_ON_FEE
description: The tax paid on fee amounts.
- name: THIRD_PARTY_FEE
description: Fees collected by a third-party platform.
- name: THIRD_PARTY_FEE_REFUND
description: Refunded fees from a third-party platform.
- name: PAYOUT
description: >-
The balance change due to a money transfer. Note that this type is
never returned by the Payouts API.
- name: AUTOMATIC_BITCOIN_CONVERSIONS
description: >-
Indicates that the portion of each payment withheld by Square was
automatically converted into bitcoin using Cash App. The seller
manages their bitcoin in their Cash App account.
- name: AUTOMATIC_BITCOIN_CONVERSIONS_REVERSED
description: >-
Indicates that a withheld payment, which was scheduled to be
converted into bitcoin using Cash App, was deposited back to the
Square payments balance.
- name: CREDIT_CARD_REPAYMENT
description: >-
Indicates that a repayment toward the outstanding balance on the
seller's Square credit card was made.
- name: CREDIT_CARD_REPAYMENT_REVERSED
description: >-
Indicates that a repayment toward the outstanding balance on the
seller's Square credit card was reversed.
- name: LOCAL_OFFERS_CASHBACK
description: >-
Cashback amount given by a Square Local Offers seller to their
customer for a purchase.
- name: LOCAL_OFFERS_FEE
description: >-
A commission fee paid by a Square Local Offers seller to Square for
a purchase discovered through Square Local Offers.
- name: PERCENTAGE_PROCESSING_ENROLLMENT
description: >-
When activating Percentage Processing, a credit is applied to the
seller’s account to offset any negative balance caused by a dispute.
- name: PERCENTAGE_PROCESSING_DEACTIVATION
description: >-
Deducting the outstanding Percentage Processing balance from the
seller’s account. It's the final installment in repaying the
dispute-induced negative balance through percentage processing.
- name: PERCENTAGE_PROCESSING_REPAYMENT
description: >-
Withheld funds from a payment to cover a negative balance. It's an
installment to repay the amount from a dispute that had been offset
during Percentage Processing enrollment.
- name: PERCENTAGE_PROCESSING_REPAYMENT_REVERSED
description: >-
The reversal of a percentage processing repayment that happens for
example when a refund is issued for a payment.
- name: PROCESSING_FEE
description: >-
The processing fee for a payment. If sellers opt for Gross
Settlement, i.e., direct bank withdrawal instead of deducting fees
from daily sales, the processing fee is recorded separately as a new
payout entry, not part of the CHARGE payout entry.
- name: PROCESSING_FEE_REFUND
description: >-
The processing fee for a pa
# --- truncated at 32 KB (2344 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/square/refs/heads/main/openapi/square-openapi.yml