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.