Objects & Enums
Reference for data types shared across the Square API
The Square API shares common objects across endpoints, such as
Address or Payment, to make it easier for
you to build your app and enforce consistency across our API surface.
This reference documents every common object currently in use.
-
AdditionalRecipient
Represents an additional recipient other than the merchant receiving a portion of this tender.
-
Address
Represents a physical address.
-
BalancePaymentDetails
Reflects the current status of a balance payment.
-
BankAccount
Represents a bank account.
-
BankAccount
V1BankAccount
V1 -
BankAccountCreatedWebhookData
-
BankAccountCreatedWebhookObject
-
BankAccountDisabledWebhookData
-
BankAccountDisabledWebhookObject
-
BankAccountVerifiedWebhookData
-
BankAccountVerifiedWebhookObject
-
Break
A record of an employee's break during a shift.
-
BreakType
A defined break template that sets an expectation for possible Break instances on a Shift.
-
BusinessHours
Represents the hours of operation for a business location.
-
BusinessHoursPeriod
Represents a period of time during which a business location is open.
-
Card
Represents the payment details of a card to be used for payments.
-
CardPaymentDetails
Reflects the current status of a card payment.
-
CashDrawerDevice
-
CashDrawerEvent
V1CashDrawerEvent
V1 -
CashDrawerShift
This model gives the details of a cash drawer shift.
-
CashDrawerShift
Contains details for a single cash drawer shift.
V1 -
CashDrawerShiftEvent
-
CashDrawerShiftSummary
The summary of a closed cash drawer shift.
-
CatalogCategory
A category to which a CatalogItem instance belongs.
-
CatalogCustomAttributeDefinition
Contains information defining a custom attribute.
BETA -
CatalogCustomAttributeDefinitionNumberConfig
BETA -
CatalogCustomAttributeDefinitionSelectionConfig
Configuration associated with SELECTION-type custom attribute definitions.
BETA -
CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection
A named selection for this SELECTION-type custom attribute definition.
BETA -
CatalogCustomAttributeDefinitionStringConfig
Configuration associated with Custom Attribute Definitions of type STRING.
BETA -
CatalogCustomAttributeValue
An instance of a custom attribute.
BETA -
CatalogDiscount
A discount applicable to items.
-
CatalogIdMapping
A mapping between a temporary client-supplied ID and a permanent server-generated ID.
-
CatalogImage
An image file to use in Square catalogs.
-
CatalogInfoResponseLimits
-
CatalogItem
An CatalogObject instance of the ITEM type, also referred to as an item, in the catalog.
-
CatalogItemModifierListInfo
Options to control the properties of a CatalogModifierList applied to a CatalogItem instance.
-
CatalogItemOption
A group of variations for a CatalogItem.
BETA -
CatalogItemOptionForItem
An option that can be assigned to an item.
BETA -
CatalogItemOptionValue
An enumerated value that can link a CatalogItemVariation to an item option as one of its item option values.
BETA -
CatalogItemOptionValueForItemVariation
A CatalogItemOptionValue links an item variation to an item option as an item option value.
BETA -
CatalogItemVariation
An item variation i.e., product in the Catalog object model.
-
CatalogMeasurementUnit
Represents the unit used to measure a CatalogItemVariation and specifies the precision for decimal quantities.
BETA -
CatalogModifier
A modifier applicable to items at the time of sale.
-
CatalogModifierList
A list of modifiers applicable to items at the time of sale.
-
CatalogModifierOverride
Options to control how to override the default behavior of the specified modifier.
-
CatalogObject
The wrapper object for the Catalog entries of a given object type.
-
CatalogObjectBatch
A batch of catalog objects.
-
CatalogPricingRule
Defines how discounts are automatically applied to a set of items that match the pricing rule during the active time period.
-
CatalogProductSet
Represents a collection of catalog objects for the purpose of applying a PricingRule.
-
CatalogQuery
A query composed of one or more different types of filters to narrow the scope of targeted objects when calling the SearchCatalogObjects endpoint.
-
CatalogQueryExact
The query filter to return the serch result by exact match of the specified attribute name and value.
-
CatalogQueryItemsForItemOptions
The query filter to return the items containing the specified item option IDs.
BETA -
CatalogQueryItemsForModifierList
The query filter to return the items containing the specified modifier list IDs.
-
CatalogQueryItemsForTax
The query filter to return the items containing the specified tax IDs.
-
CatalogQueryItemVariationsForItemOptionValues
The query filter to return the item variations containing the specified item option value IDs.
BETA -
CatalogQueryPrefix
The query filter to return the search result whose named attribute values are prefixed by the specified attribute value.
-
CatalogQueryRange
The query filter to return the search result whose named attribute values fall between the specified range.
-
CatalogQuerySortedAttribute
The query expression to specify the key to sort search results.
-
CatalogQueryText
The query filter to return the search result whose searchable attribute values contain all of the specified keywords or tokens, independent of the token order or case.
-
CatalogQuickAmount
Represents a Quick Amount in the Catalog.
BETA -
CatalogQuickAmountsSettings
A parent Catalog Object model represents a set of Quick Amounts and the settings control the amounts.
BETA -
CatalogSubscriptionPlan
Describes a subscription plan.
BETA -
CatalogTax
A tax applicable to an item.
-
CatalogTimePeriod
Represents a time period - either a single period or a repeating period.
-
CatalogV1Id
A Square API V1 identifier of an item, including the object ID and its associated location ID.
-
CatalogVersionUpdatedWebhookCatalogVersion
-
CatalogVersionUpdatedWebhookData
-
CatalogVersionUpdatedWebhookObject
-
Category
V1Category
V1 -
ChargeRequestAdditionalRecipient
Represents an additional recipient other than the merchant entitled to a portion of the tender.
-
Checkout
Square Checkout lets merchants accept online payments for supported payment types using a checkout workflow hosted on squareup.com.
-
Coordinates
Latitude and longitude coordinates.
-
CustomAttributeFilter
Supported custom attribute query expressions for calling the SearchCatalogItems endpoint to search for items or item variations.
BETA -
Customer
Represents a Square customer profile, which can have one or more cards on file associated with it.
-
CustomerCreationSourceFilter
Creation source filter.
-
CustomerFilter
Represents a set of CustomerQuery filters used to limit the set of Customers returned by SearchCustomers.
-
CustomerGroup
Represents a group of customer profiles.
BETA -
CustomerGroupInfo
Contains some brief information about a Customer Group with its identifier included.
-
CustomerPreferences
Represents communication preferences for the customer profile.
-
CustomerQuery
Represents a query including filtering criteria, sorting criteria, or both used to search for customer profiles.
-
CustomerSegment
Represents a group of customer profiles that match one or more predefined filter criteria.
BETA -
CustomerSort
Specifies how searched customers profiles are sorted, including the sort key and sort order.
-
CustomerTextFilter
A filter to select customers based on exact or fuzzy matching of customer attributes against a specified query.
BETA
-
DateRange
A range defined by two dates.
-
Device
-
DeviceCheckoutOptions
BETA -
DeviceCode
BETA -
DeviceCodePairedWebhookData
BETA -
DeviceCodePairedWebhookObject
BETA -
DeviceDetails
Details about the device that took the payment.
-
Discount
V1Discount
V1 -
Dispute
Represents a dispute a cardholder initiated with their bank.
BETA -
DisputeCreatedWebhookData
BETA -
DisputeCreatedWebhookObject
BETA -
DisputedPayment
The payment the cardholder disputed.
BETA -
DisputeEvidence
BETA -
DisputeEvidenceAddedWebhookData
BETA -
DisputeEvidenceAddedWebhookObject
BETA -
DisputeEvidenceFile
A file to be uploaded as dispute evidence.
BETA -
DisputeEvidenceRemovedWebhookData
BETA -
DisputeEvidenceRemovedWebhookObject
BETA -
DisputeStateChangedWebhookData
BETA -
DisputeStateChangedWebhookObject
BETA
-
Employee
An employee object that is used by the external API.
-
Employee
Represents one of a business's employees.
V1 -
EmployeeRole
V1EmployeeRole
V1 -
EmployeeWage
The hourly wage rate that an employee will earn on a Shift for doing the job specified by the title property of this object.
-
Error
Represents an error encountered during a request to the Connect API.
-
InventoryAdjustment
Represents a change in state or quantity of product inventory at a particular time and location.
-
InventoryChange
Represents a single physical count, inventory, adjustment, or transfer that is part of the history of inventory changes for a particular CatalogObject.
-
InventoryCount
Represents Square's estimated quantity of items in a particular state at a particular location based on the known history of physical counts and inventory adjustments.
-
InventoryCountUpdatedWebhookData
-
InventoryCountUpdatedWebhookObject
-
InventoryEntry
V1InventoryEntry
V1 -
InventoryPhysicalCount
Represents the quantity of an item variation that is physically present at a specific location, verified by a seller or a seller's employee.
-
InventoryTransfer
Represents the transfer of a quantity of product inventory at a particular time from one location to another.
-
Invoice
Stores information about an invoice.
BETA -
InvoiceCanceledWebhookData
BETA -
InvoiceCanceledWebhookObject
BETA -
InvoiceCreatedWebhookData
BETA -
InvoiceCreatedWebhookObject
BETA -
InvoiceDeletedWebhookData
BETA -
InvoiceFilter
Describes query filters to apply.
BETA -
InvoicePaymentMadeWebhookData
BETA -
InvoicePaymentMadeWebhookObject
BETA -
InvoicePaymentReminder
Describes a payment request reminder automatic notification that Square sends to the customer.
BETA -
InvoicePublishedWebhookData
BETA -
InvoicePublishedWebhookObject
BETA -
InvoiceQuery
Describes query criteria for searching invoices.
BETA -
InvoiceRecipient
Provides customer data that Square uses to deliver an invoice.
BETA -
InvoiceRefundedWebhookData
BETA -
InvoiceRefundedWebhookObject
BETA -
InvoiceScheduledChargeFailedWebhookData
BETA -
InvoiceScheduledChargeFailedWebhookObject
BETA -
InvoiceSort
Identifies the sort field and sort order.
BETA -
InvoiceUpdatedWebhookData
BETA -
InvoiceUpdatedWebhookObject
BETA -
Item
V1Item
V1 -
ItemImage
V1ItemImage
V1 -
ItemVariationLocationOverrides
Price and inventory alerting overrides for a CatalogItemVariation at a specific Location.
-
LaborShiftCreatedWebhookData
-
LaborShiftCreatedWebhookObject
-
LaborShiftDeletedWebhookData
-
LaborShiftUpdatedWebhookData
-
LaborShiftUpdatedWebhookObject
-
Location
-
LoyaltyAccount
Describes a loyalty account.
BETA -
LoyaltyAccountCreatedWebhookData
BETA -
LoyaltyAccountDeletedWebhookData
BETA -
LoyaltyAccountMapping
Associates a loyalty account with the buyer's phone number.
BETA -
LoyaltyAccountUpdatedWebhookData
BETA -
LoyaltyEvent
Provides information about a loyalty event.
BETA -
LoyaltyEventAccumulatePoints
Provides metadata when the event type is ACCUMULATE_POINTS.
BETA -
LoyaltyEventAdjustPoints
Provides metadata when the event type is ADJUST_POINTS.
BETA -
LoyaltyEventCreatedWebhookData
BETA -
LoyaltyEventCreateReward
Provides metadata when the event type is CREATE_REWARD.
BETA -
LoyaltyEventDateTimeFilter
Filter events by date time range.
BETA -
LoyaltyEventDeleteReward
Provides metadata when the event type is DELETE_REWARD.
BETA -
LoyaltyEventExpirePoints
Provides metadata when the event type is EXPIRE_POINTS.
BETA -
LoyaltyEventFilter
The filtering criteria.
BETA -
LoyaltyEventLocationFilter
Filter events by location.
BETA -
LoyaltyEventLoyaltyAccountFilter
Filter events by loyalty account.
BETA -
LoyaltyEventOrderFilter
Filter events by the order associated with the event.
BETA -
LoyaltyEventOther
Provides metadata when the event type is OTHER.
BETA -
LoyaltyEventQuery
Represents a query used to search for loyalty events.
BETA -
LoyaltyEventRedeemReward
Provides metadata when the event type is REDEEM_REWARD.
BETA -
LoyaltyEventTypeFilter
Filter events by event type.
BETA -
LoyaltyProgram
BETA -
LoyaltyProgramAccrualRule
Defines an accrual rule, which is how buyers can earn points.
BETA -
LoyaltyProgramExpirationPolicy
Describes when the loyalty program expires.
BETA -
LoyaltyProgramRewardDefinition
Provides details about the loyalty program reward tier definition.
BETA -
LoyaltyProgramRewardTier
Describes a loyalty program reward tier.
BETA -
LoyaltyProgramTerminology
BETA -
LoyaltyProgramUpdatedWebhookData
BETA -
LoyaltyReward
BETA
-
MeasurementUnit
Represents a unit of measurement to use with a quantity, such as ounces or inches.
BETA -
MeasurementUnitCustom
The information needed to define a custom unit, provided by the seller.
BETA -
Merchant
Represents a Square seller.
-
Merchant
Defines the fields that are included in the response body of a request to the RetrieveBusiness endpoint.
V1 -
MerchantLocationDetails
Additional information for a single-location account specified by its associated business account, if it has one.
V1 -
ModifierList
V1ModifierList
V1 -
ModifierOption
V1ModifierOption
V1 -
Money
Represents an amount of money.
-
Money
V1
-
OauthAuthorizationRevokedWebhookData
BETA -
OauthAuthorizationRevokedWebhookObject
BETA -
OauthAuthorizationRevokedWebhookRevocationObject
BETA -
Order
Contains all information related to a single order to process with Square, including line items that specify the products to purchase.
-
OrderCreated
BETA -
OrderCreatedObject
BETA -
OrderCreatedWebhookData
BETA -
OrderEntry
A lightweight description of an Order that is returned when returned_entries is true on a SearchOrderRequest
-
OrderFulfillment
Contains details on how to fulfill this order.
-
OrderFulfillmentPickupDetails
Contains details necessary to fulfill a pickup order.
-
OrderFulfillmentPickupDetailsCurbsidePickupDetails
Specific details for curbside pickup.
BETA -
OrderFulfillmentRecipient
Contains information on the recipient of a fulfillment.
-
OrderFulfillmentShipmentDetails
Contains details necessary to fulfill a shipment order.
BETA -
OrderFulfillmentUpdated
BETA -
OrderFulfillmentUpdatedObject
BETA -
OrderFulfillmentUpdatedUpdate
Information about fulfillment updates.
BETA -
OrderFulfillmentUpdatedWebhookData
BETA -
OrderLineItem
Represents a line item in an order.
-
OrderLineItemAppliedDiscount
Represents an applied portion of a discount to a line item in an order.
BETA -
OrderLineItemAppliedTax
Represents an applied portion of a tax to a line item in an order.
BETA -
OrderLineItemDiscount
Represents a discount that applies to one or more line items in an order.
-
OrderLineItemModifier
A CatalogModifier.
-
OrderLineItemTax
Represents a tax that applies to one or more line item in the order.
-
OrderMoneyAmounts
A collection of various money amounts.
BETA -
OrderPricingOptions
Pricing options for an order.
-
OrderQuantityUnit
Contains the measurement unit for a quantity and a precision which specifies the number of digits after the decimal point for decimal quantities.
-
OrderReturn
The set of line items, service charges, taxes, discounts, tips, etc.
BETA -
OrderReturnDiscount
Represents a discount being returned that applies to one or more return line items in an order.
BETA -
OrderReturnLineItem
The line item being returned in an Order.
BETA -
OrderReturnLineItemModifier
A line item modifier being returned.
BETA -
OrderReturnServiceCharge
Represents the service charge applied to the original order.
-
OrderReturnTax
Represents a tax being returned that applies to one or more return line items in an order.
BETA -
OrderReward
Represents a reward that may be applied to an order if the necessary reward tier criteria are met.
BETA -
OrderRoundingAdjustment
A rounding adjustment of the money being returned.
BETA -
OrderServiceCharge
Represents a service charge applied to an order.
-
OrderSource
Represents the origination details of an order.
-
OrderUpdated
BETA -
OrderUpdatedObject
BETA -
OrderUpdatedWebhookData
BETA
-
Page
V1Page
V1 -
PageCell
V1PageCell
V1 -
Payment
Represents a payment processed by the Square API.
-
Payment
A payment represents a paid transaction between a Square merchant and a customer.
V1 -
PaymentCreatedWebhookData
-
PaymentCreatedWebhookObject
-
PaymentDiscount
V1PaymentDiscount
V1 -
PaymentItemDetail
V1PaymentItemDetail
V1 -
PaymentItemization
Payment include an itemizations field that lists the items purchased, along with associated fees, modifiers, and discounts.
V1 -
PaymentModifier
V1PaymentModifier
V1 -
PaymentOptions
BETA -
PaymentRefund
Represents a refund of a payment made using Square.
-
PaymentSurcharge
V1PaymentSurcharge
V1 -
PaymentTax
V1PaymentTax
V1 -
PaymentUpdatedWebhookData
-
PaymentUpdatedWebhookObject
-
PhoneNumber
Represents a phone number.
V1 -
ProcessingFee
Represents Square processing fee.
-
Range
The range of a number value between the specified lower and upper bounds.
BETA -
Refund
Represents a refund processed for a Square transaction.
-
Refund
V1Refund
V1 -
RefundCreatedWebhookData
-
RefundCreatedWebhookObject
-
RefundUpdatedWebhookData
-
RefundUpdatedWebhookObject
-
SearchLoyaltyAccountsRequestLoyaltyAccountQuery
The search criteria for the loyalty accounts.
BETA -
SearchLoyaltyRewardsRequestLoyaltyRewardQuery
The set of search requirements.
BETA -
SearchOrdersCustomerFilter
Filter based on Order customer_id and any Tender customer_id associated with the Order.
BETA -
SearchOrdersDateTimeFilter
Filter for Order objects based on whether their CREATED_AT, CLOSED_AT or UPDATED_AT timestamps fall within a specified time range.
-
SearchOrdersFilter
Filtering criteria to use for a SearchOrders request.
-
SearchOrdersFulfillmentFilter
Filter based on Order Fulfillment information.
-
SearchOrdersQuery
Contains query criteria for the search.
-
SearchOrdersSort
Sorting criteria for a SearchOrders request.
-
SearchOrdersSourceFilter
Filter based on order source information.
-
SearchOrdersStateFilter
Filter by current Order state.
-
SearchSubscriptionsFilter
Represents a set of SearchSubscriptionsQuery filters used to limit the set of Subscriptions returned by SearchSubscriptions.
BETA -
SearchSubscriptionsQuery
Represents a query including filtering criteria used to search for subscriptions.
BETA -
SearchTeamMembersFilter
Represents a filter used in a search for TeamMember objects.
-
SearchTeamMembersQuery
Represents the parameters in a search for TeamMember objects.
-
Settlement
V1Settlement
V1 -
SettlementEntry
V1SettlementEntry
V1 -
Shift
A record of the hourly rate, start, and end times for a single work shift for an employee.
-
ShiftFilter
Defines a filter used in a search for Shift records.
-
ShiftQuery
The parameters of a Shift search query.
-
ShiftSort
Sets the sort order of search results.
-
ShiftWage
The hourly wage rate used to compensate an employee for this shift.
-
ShiftWorkday
A Shift search query filter parameter that sets a range of days that a Shift must start or end in before passing the filter condition.
-
SourceApplication
Provides information about the application used to generate a change.
-
StandardUnitDescription
Contains the name and abbreviation for standard measurement unit.
-
StandardUnitDescriptionGroup
Group of standard measurement units.
-
Subscription
Represents a customer subscription to a subscription plan.
BETA -
SubscriptionCreatedWebhookData
BETA -
SubscriptionCreatedWebhookObject
BETA -
SubscriptionEvent
Describes changes to subscription and billing states.
BETA -
SubscriptionPhase
Describes a phase in a subscription plan.
BETA -
SubscriptionUpdatedWebhookData
BETA -
SubscriptionUpdatedWebhookObject
BETA
-
TeamMember
A record representing an individual team member for a business.
-
TeamMemberAssignedLocations
An object that represents a team member's assignment to locations.
-
TeamMemberWage
The hourly wage rate that a team member will earn on a Shift for doing the job specified by the title property of this object.
-
Tender
Represents a tender i.e., a method of payment used in a Square transaction.
-
Tender
A tender represents a discrete monetary exchange.
V1 -
TenderBankTransferDetails
Represents the details of a tender with type BANK_TRANSFER.
-
TenderCardDetails
Represents additional details of a tender with type CARD or SQUARE_GIFT_CARD
-
TenderCashDetails
Represents the details of a tender with type CASH.
-
TerminalCheckout
BETA -
TerminalCheckoutCreatedWebhookData
BETA -
TerminalCheckoutCreatedWebhookObject
BETA -
TerminalCheckoutQuery
BETA -
TerminalCheckoutQueryFilter
BETA -
TerminalCheckoutQuerySort
BETA -
TerminalCheckoutUpdatedWebhookData
BETA -
TerminalCheckoutUpdatedWebhookObject
BETA -
Timecard
Represents a timecard for an employee.
V1 -
TimecardEvent
V1TimecardEvent
V1 -
TimeRange
Represents a generic time range.
-
TipSettings
BETA -
Transaction
Represents a transaction processed with Square, either with the Connect API or with Square Point of Sale.