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.
-
Additional
Recipient Represents an additional recipient other than the merchant receiving a portion of this tender.
-
Address
Represents a physical address.
-
Appointment
Segment Defines an appointment segment of a booking.
BETA -
Availability
Describes a slot available for booking, encapsulating appointment segments, the location and starting time.
BETA
-
Balance
Payment Details Reflects the current status of a balance payment.
-
Bank
Account Represents a bank account.
-
Bank
Account Created Webhook Data -
Bank
Account Created Webhook Object -
Bank
Account Disabled Webhook Data -
Bank
Account Disabled Webhook Object -
Bank
Account Verified Webhook Data -
Bank
Account Verified Webhook Object -
Booking
Represents a booking as a time-bound service contract for a seller's staff member to provide a specified service at a given location to a requesting customer in one or more appointment segments.
BETA -
Booking
Created Webhook Data BETA -
Booking
Created Webhook Object BETA -
Booking
Updated Webhook Data BETA -
Booking
Updated Webhook Object BETA -
Break
A record of an employee's break during a shift.
-
Break
Type A defined break template that sets an expectation for possible Break instances on a Shift.
-
Business
Appointment Settings The service appointment settings, including where and how the service is provided.
BETA -
Business
Booking Profile BETA -
Business
Hours Represents the hours of operation for a business location.
-
Business
Hours Period 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.
-
Card
Payment Details Reflects the current status of a card payment.
-
Card
Payment Timeline The timeline for card payments.
-
Cash
Drawer Device -
Cash
Drawer Shift This model gives the details of a cash drawer shift.
-
Cash
Drawer Shift Event -
Cash
Drawer Shift Summary The summary of a closed cash drawer shift.
-
Catalog
Category A category to which a CatalogItem instance belongs.
-
Catalog
Custom Attribute Definition Contains information defining a custom attribute.
BETA -
Catalog
Custom Attribute Definition Number Config BETA -
Catalog
Custom Attribute Definition Selection Config Configuration associated with SELECTION-type custom attribute definitions.
BETA -
Catalog
Custom Attribute Definition Selection Config Custom Attribute Selection A named selection for this SELECTION-type custom attribute definition.
BETA -
Catalog
Custom Attribute Definition String Config Configuration associated with Custom Attribute Definitions of type STRING.
BETA -
Catalog
Custom Attribute Value An instance of a custom attribute.
BETA -
Catalog
Discount A discount applicable to items.
-
Catalog
Id Mapping A mapping between a temporary client-supplied ID and a permanent server-generated ID.
-
Catalog
Image An image file to use in Square catalogs.
-
Catalog
Info Response Limits -
Catalog
Item A CatalogObject instance of the ITEM type, also referred to as an item, in the catalog.
-
Catalog
Item Modifier List Info Options to control the properties of a CatalogModifierList applied to a CatalogItem instance.
-
Catalog
Item Option A group of variations for a CatalogItem.
BETA -
Catalog
Item Option For Item An option that can be assigned to an item.
BETA -
Catalog
Item Option Value An enumerated value that can link a CatalogItemVariation to an item option as one of its item option values.
BETA -
Catalog
Item Option Value For Item Variation A CatalogItemOptionValue links an item variation to an item option as an item option value.
BETA -
Catalog
Item Variation An item variation i.e., product in the Catalog object model.
-
Catalog
Measurement Unit Represents the unit used to measure a CatalogItemVariation and specifies the precision for decimal quantities.
BETA -
Catalog
Modifier A modifier applicable to items at the time of sale.
-
Catalog
Modifier List A list of modifiers applicable to items at the time of sale.
-
Catalog
Modifier Override Options to control how to override the default behavior of the specified modifier.
-
Catalog
Object The wrapper object for the Catalog entries of a given object type.
-
Catalog
Object Batch A batch of catalog objects.
-
Catalog
Object Reference A reference to a Catalog object at a specific version.
BETA -
Catalog
Pricing Rule Defines how discounts are automatically applied to a set of items that match the pricing rule during the active time period.
-
Catalog
Product Set Represents a collection of catalog objects for the purpose of applying a PricingRule.
-
Catalog
Query A query composed of one or more different types of filters to narrow the scope of targeted objects when calling the SearchCatalogObjects endpoint.
-
Catalog
Query Exact The query filter to return the search result by exact match of the specified attribute name and value.
-
Catalog
Query Items For Item Options The query filter to return the items containing the specified item option IDs.
BETA -
Catalog
Query Items For Modifier List The query filter to return the items containing the specified modifier list IDs.
-
Catalog
Query Items For Tax The query filter to return the items containing the specified tax IDs.
-
Catalog
Query Item Variations For Item Option Values The query filter to return the item variations containing the specified item option value IDs.
BETA -
Catalog
Query Prefix The query filter to return the search result whose named attribute values are prefixed by the specified attribute value.
-
Catalog
Query Range The query filter to return the search result whose named attribute values fall between the specified range.
-
Catalog
Query Set The query filter to return the search results by exact match of the specified attribute_name and any of the attribute_values.
-
Catalog
Query Sorted Attribute The query expression to specify the key to sort search results.
-
Catalog
Query Text 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.
-
Catalog
Quick Amount Represents a Quick Amount in the Catalog.
BETA -
Catalog
Quick Amounts Settings A parent Catalog Object model represents a set of Quick Amounts and the settings control the amounts.
BETA -
Catalog
Subscription Plan Describes a subscription plan.
BETA -
Catalog
Tax A tax applicable to an item.
-
Catalog
Time Period Represents a time period - either a single period or a repeating period.
-
Catalog
V1 Id A Square API V1 identifier of an item, including the object ID and its associated location ID.
-
Catalog
Version Updated Webhook Catalog Version -
Catalog
Version Updated Webhook Data -
Catalog
Version Updated Webhook Object -
Charge
Request Additional Recipient 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.
-
Custom
Attribute Filter 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.
-
Customer
Created Webhook Data The data associated with the webhook event.
BETA -
Customer
Created Webhook Event Context Information about the change that triggered the event.
BETA -
Customer
Created Webhook Event Context Merge Information about a merge operation, which creates a new customer using aggregated properties from two or more existing customers.
BETA -
Customer
Created Webhook Object An object that contains the customer associated with the webhook event.
BETA -
Customer
Creation Source Filter Creation source filter.
-
Customer
Deleted Webhook Data The data associated with the webhook event.
BETA -
Customer
Deleted Webhook Event Context Information about the change that triggered the event.
BETA -
Customer
Deleted Webhook Event Context Merge Information about a merge operation, which creates a new customer using aggregated properties from two or more existing customers.
BETA -
Customer
Deleted Webhook Object An object that contains the customer associated with the webhook event.
BETA -
Customer
Filter Represents a set of CustomerQuery filters used to limit the set of Customers returned by SearchCustomers.
-
Customer
Group Represents a group of customer profiles.
BETA -
Customer
Group Info Contains some brief information about a Customer Group with its identifier included.
-
Customer
Preferences Represents communication preferences for the customer profile.
-
Customer
Query Represents a query including filtering criteria, sorting criteria, or both used to search for customer profiles.
-
Customer
Segment Represents a group of customer profiles that match one or more predefined filter criteria.
BETA -
Customer
Sort Specifies how searched customers profiles are sorted, including the sort key and sort order.
-
Customer
Text Filter A filter to select customers based on exact or fuzzy matching of customer attributes against a specified query.
-
Customer
Updated Webhook Data The data associated with the webhook event.
BETA -
Customer
Updated Webhook Object An object that contains the customer associated with the webhook event.
BETA
-
Date
Range A range defined by two dates.
-
Device
-
Device
Checkout Options -
Device
Code -
Device
Code Paired Webhook Data -
Device
Code Paired Webhook Object -
Device
Details Details about the device that took the payment.
-
Dispute
Represents a dispute a cardholder initiated with their bank.
BETA -
Dispute
Created Webhook Data BETA -
Dispute
Created Webhook Object BETA -
Disputed
Payment The payment the cardholder disputed.
BETA -
Dispute
Evidence BETA -
Dispute
Evidence Added Webhook Data BETA -
Dispute
Evidence Added Webhook Object BETA -
Dispute
Evidence File A file to be uploaded as dispute evidence.
BETA -
Dispute
Evidence Removed Webhook Data BETA -
Dispute
Evidence Removed Webhook Object BETA -
Dispute
State Changed Webhook Data BETA -
Dispute
State Changed Webhook Object BETA
-
Employee
An employee object that is used by the external API.
-
Employee
Represents one of a business's employees.
V1 -
Employee
Role V1EmployeeRole
V1 -
Employee
Wage 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.
-
Inventory
Adjustment Represents a change in state or quantity of product inventory at a particular time and location.
-
Inventory
Change Represents a single physical count, inventory, adjustment, or transfer that is part of the history of inventory changes for a particular CatalogObject.
-
Inventory
Count 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.
-
Inventory
Count Updated Webhook Data -
Inventory
Count Updated Webhook Object -
Inventory
Physical Count Represents the quantity of an item variation that is physically present at a specific location, verified by a seller or a seller's employee.
-
Inventory
Transfer 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 -
Invoice
Canceled Webhook Data BETA -
Invoice
Canceled Webhook Object BETA -
Invoice
Created Webhook Data BETA -
Invoice
Created Webhook Object BETA -
Invoice
Custom Field An additional seller-defined and customer-facing field to include on the invoice.
BETA -
Invoice
Deleted Webhook Data BETA -
Invoice
Filter Describes query filters to apply.
BETA -
Invoice
Payment Made Webhook Data BETA -
Invoice
Payment Made Webhook Object BETA -
Invoice
Payment Reminder Describes a payment request reminder automatic notification that Square sends to the customer.
BETA -
Invoice
Published Webhook Data BETA -
Invoice
Published Webhook Object BETA -
Invoice
Query Describes query criteria for searching invoices.
BETA -
Invoice
Recipient Provides customer data that Square uses to deliver an invoice.
BETA -
Invoice
Refunded Webhook Data BETA -
Invoice
Refunded Webhook Object BETA -
Invoice
Scheduled Charge Failed Webhook Data BETA -
Invoice
Scheduled Charge Failed Webhook Object BETA -
Invoice
Sort Identifies the sort field and sort order.
BETA -
Invoice
Updated Webhook Data BETA -
Invoice
Updated Webhook Object BETA -
Item
Variation Location Overrides Price and inventory alerting overrides for a CatalogItemVariation at a specific Location.
-
Labor
Shift Created Webhook Data -
Labor
Shift Created Webhook Object -
Labor
Shift Deleted Webhook Data -
Labor
Shift Updated Webhook Data -
Labor
Shift Updated Webhook Object -
Location
-
Location
Created Webhook Data BETA -
Location
Updated Webhook Data BETA -
Loyalty
Account Describes a loyalty account.
BETA -
Loyalty
Account Created Webhook Data BETA -
Loyalty
Account Deleted Webhook Data BETA -
Loyalty
Account Mapping Associates a loyalty account with the buyer's phone number.
BETA -
Loyalty
Account Updated Webhook Data BETA -
Loyalty
Event Provides information about a loyalty event.
BETA -
Loyalty
Event Accumulate Points Provides metadata when the event type is ACCUMULATE_POINTS.
BETA -
Loyalty
Event Adjust Points Provides metadata when the event type is ADJUST_POINTS.
BETA -
Loyalty
Event Created Webhook Data BETA -
Loyalty
Event Create Reward Provides metadata when the event type is CREATE_REWARD.
BETA -
Loyalty
Event Date Time Filter Filter events by date time range.
BETA -
Loyalty
Event Delete Reward Provides metadata when the event type is DELETE_REWARD.
BETA -
Loyalty
Event Expire Points Provides metadata when the event type is EXPIRE_POINTS.
BETA -
Loyalty
Event Filter The filtering criteria.
BETA -
Loyalty
Event Location Filter Filter events by location.
BETA -
Loyalty
Event Loyalty Account Filter Filter events by loyalty account.
BETA -
Loyalty
Event Order Filter Filter events by the order associated with the event.
BETA -
Loyalty
Event Other Provides metadata when the event type is OTHER.
BETA -
Loyalty
Event Query Represents a query used to search for loyalty events.
BETA -
Loyalty
Event Redeem Reward Provides metadata when the event type is REDEEM_REWARD.
BETA -
Loyalty
Event Type Filter Filter events by event type.
BETA -
Loyalty
Program BETA -
Loyalty
Program Accrual Rule Defines an accrual rule, which is how buyers can earn points.
BETA -
Loyalty
Program Expiration Policy Describes when the loyalty program expires.
BETA -
Loyalty
Program Reward Definition Provides details about the reward tier discount.
BETA -
Loyalty
Program Reward Tier Describes a loyalty program reward tier.
BETA -
Loyalty
Program Terminology BETA -
Loyalty
Program Updated Webhook Data BETA -
Loyalty
Reward BETA
-
Measurement
Unit Represents a unit of measurement to use with a quantity, such as ounces or inches.
BETA -
Measurement
Unit Custom The information needed to define a custom unit, provided by the seller.
BETA -
Merchant
Represents a Square seller.
-
Money
Represents an amount of money.
-
Money
V1
-
Oauth
Authorization Revoked Webhook Data BETA -
Oauth
Authorization Revoked Webhook Object BETA -
Oauth
Authorization Revoked Webhook Revocation Object BETA -
Order
Contains all information related to a single order to process with Square, including line items that specify the products to purchase.
-
Order
Created BETA -
Order
Created Object BETA -
Order
Created Webhook Data BETA -
Order
Entry A lightweight description of an Order that is returned when returned_entries is true on a SearchOrderRequest
-
Order
Fulfillment Contains details on how to fulfill this order.
-
Order
Fulfillment Pickup Details Contains details necessary to fulfill a pickup order.
-
Order
Fulfillment Pickup Details Curbside Pickup Details Specific details for curbside pickup.
BETA -
Order
Fulfillment Recipient Contains information on the recipient of a fulfillment.
-
Order
Fulfillment Shipment Details Contains details necessary to fulfill a shipment order.
BETA -
Order
Fulfillment Updated BETA -
Order
Fulfillment Updated Object BETA -
Order
Fulfillment Updated Update Information about fulfillment updates.
BETA -
Order
Fulfillment Updated Webhook Data BETA -
Order
Line Item Represents a line item in an order.
-
Order
Line Item Applied Discount Represents an applied portion of a discount to a line item in an order.
BETA -
Order
Line Item Applied Tax Represents an applied portion of a tax to a line item in an order.
BETA -
Order
Line Item Discount Represents a discount that applies to one or more line items in an order.
-
Order
Line Item Modifier A CatalogModifier.
-
Order
Line Item Pricing Blocklists Describes pricing adjustments that are blocked from manual and automatic application to a line item.
BETA -
Order
Line Item Pricing Blocklists Blocked Discount A discount to block from applying to a line item.
BETA -
Order
Line Item Pricing Blocklists Blocked Tax A tax to block from applying to a line item.
BETA -
Order
Line Item Tax Represents a tax that applies to one or more line item in the order.
-
Order
Money Amounts A collection of various money amounts.
BETA -
Order
Pricing Options Pricing options for an order.
-
Order
Quantity Unit Contains the measurement unit for a quantity and a precision which specifies the number of digits after the decimal point for decimal quantities.
-
Order
Return The set of line items, service charges, taxes, discounts, tips, etc.
BETA -
Order
Return Discount Represents a discount being returned that applies to one or more return line items in an order.
BETA -
Order
Return Line Item The line item being returned in an Order.
BETA -
Order
Return Line Item Modifier A line item modifier being returned.
BETA -
Order
Return Service Charge Represents the service charge applied to the original order.
-
Order
Return Tax Represents a tax being returned that applies to one or more return line items in an order.
BETA -
Order
Reward Represents a reward that may be applied to an order if the necessary reward tier criteria are met.
BETA -
Order
Rounding Adjustment A rounding adjustment of the money being returned.
BETA -
Order
Service Charge Represents a service charge applied to an order.
-
Order
Source Represents the origination details of an order.
-
Order
Updated BETA -
Order
Updated Object BETA -
Order
Updated Webhook Data BETA
-
Payment
Represents a payment processed by the Square API.
-
Payment
A payment represents a paid transaction between a Square merchant and a customer.
V1 -
Payment
Created Webhook Data -
Payment
Created Webhook Object -
Payment
Discount V1PaymentDiscount
V1 -
Payment
Item Detail V1PaymentItemDetail
V1 -
Payment
Itemization Payment include an itemizations field that lists the items purchased, along with associated fees, modifiers, and discounts.
V1 -
Payment
Modifier V1PaymentModifier
V1 -
Payment
Options -
Payment
Refund Represents a refund of a payment made using Square.
-
Payment
Surcharge V1PaymentSurcharge
V1 -
Payment
Tax V1PaymentTax
V1 -
Payment
Updated Webhook Data -
Payment
Updated Webhook Object -
Phone
Number Represents a phone number.
V1 -
Processing
Fee Represents the 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 -
Refund
Created Webhook Data -
Refund
Created Webhook Object -
Refund
Updated Webhook Data -
Refund
Updated Webhook Object -
Risk
Evaluation Represents fraud risk information for the associated payment.
BETA
-
Search
Availability Filter A query filter to search for availabilities by.
BETA -
Search
Availability Query Query conditions to search for availabilities of bookings.
BETA -
Search
Loyalty Accounts Request Loyalty Account Query The search criteria for the loyalty accounts.
BETA -
Search
Loyalty Rewards Request Loyalty Reward Query The set of search requirements.
BETA -
Search
Orders Customer Filter Filter based on Order customer_id and any Tender customer_id associated with the Order.
BETA -
Search
Orders Date Time Filter Filter for Order objects based on whether their CREATED_AT, CLOSED_AT or UPDATED_AT timestamps fall within a specified time range.
-
Search
Orders Filter Filtering criteria to use for a SearchOrders request.
-
Search
Orders Fulfillment Filter Filter based on Order Fulfillment information.
-
Search
Orders Query Contains query criteria for the search.
-
Search
Orders Sort Sorting criteria for a SearchOrders request.
-
Search
Orders Source Filter Filter based on order source information.
-
Search
Orders State Filter Filter by current Order state.
-
Search
Subscriptions Filter Represents a set of SearchSubscriptionsQuery filters used to limit the set of Subscriptions returned by SearchSubscriptions.
BETA -
Search
Subscriptions Query Represents a query including filtering criteria used to search for subscriptions.
BETA -
Search
Team Members Filter Represents a filter used in a search for TeamMember objects.
-
Search
Team Members Query Represents the parameters in a search for TeamMember objects.
-
Segment
Filter A query filter to search for appointment segments by.
BETA -
Settlement
V1Settlement
V1 -
Settlement
Entry V1SettlementEntry
V1 -
Shift
A record of the hourly rate, start, and end times for a single work shift for an employee.
-
Shift
Filter Defines a filter used in a search for Shift records.
-
Shift
Query The parameters of a Shift search query.
-
Shift
Sort Sets the sort order of search results.
-
Shift
Wage The hourly wage rate used to compensate an employee for this shift.
-
Shift
Workday 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.
-
Source
Application Provides information about the application used to generate a change.
-
Standard
Unit Description Contains the name and abbreviation for standard measurement unit.
-
Standard
Unit Description Group Group of standard measurement units.
-
Subscription
Represents a customer subscription to a subscription plan.
BETA -
Subscription
Created Webhook Data BETA -
Subscription
Created Webhook Object BETA -
Subscription
Event Describes changes to subscription and billing states.
BETA -
Subscription
Phase Describes a phase in a subscription plan.
BETA -
Subscription
Updated Webhook Data BETA -
Subscription
Updated Webhook Object BETA
-
Team
Member A record representing an individual team member for a business.
-
Team
Member Assigned Locations An object that represents a team member's assignment to locations.
-
Team
Member Booking Profile The booking profile of a seller's team member, including the team member's ID, display name, description and whether the team member can be booked as a service provider.
BETA -
Team
Member Wage 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 -
Tender
Card Details Represents additional details of a tender with type CARD or SQUARE_GIFT_CARD
-
Tender
Cash Details Represents the details of a tender with type CASH.
-
Terminal
Checkout -
Terminal
Checkout Created Webhook Data -
Terminal
Checkout Created Webhook Object -
Terminal
Checkout Query -
Terminal
Checkout Query Filter -
Terminal
Checkout Query Sort -
Terminal
Checkout Updated Webhook Data -
Terminal
Checkout Updated Webhook Object -
Terminal
Refund -
Terminal
Refund Created Webhook Data -
Terminal
Refund Created Webhook Object -
Terminal
Refund Query -
Terminal
Refund Query Filter -
Terminal
Refund Query Sort -
Terminal
Refund Updated Webhook Data -
Terminal
Refund Updated Webhook Object -
Time
Range Represents a generic time range.
-
Tip
Settings -
Transaction
Represents a transaction processed with Square, either with the Connect API or with Square Point of Sale.