squareup
Module squareup
API
Definitions
ballerinax/squareup Ballerina library
Overview
This is a generated connector for SquareUp API OpenAPI specification. The SquareUp API allows you to build solutions using the Square platform to meet the business needs of Square sellers.
Prerequisites
Before using this connector in your Ballerina application, complete the following:
- Create SquareUp Account
- Obtaining tokens by following this link
Clients
squareup: Client
This is a generated connector for Square Connect API 2.0 OpenAPI Specification.
Constructor
Gets invoked to initialize the connector
.
The connector initialization requires setting the API credentials. Please create a Squareup account and obtain tokens.
init (ConnectionConfig config, string serviceUrl)
- config ConnectionConfig - The configurations to be used when initializing the
connector
- serviceUrl string "https://connect.squareup.com" - URL of the target service
createMobileAuthorizationCode
function createMobileAuthorizationCode(CreateMobileAuthorizationCodeRequest payload) returns CreateMobileAuthorizationCodeResponse|error
Create Mobile Authorization Code
Parameters
- payload CreateMobileAuthorizationCodeRequest - An object containing the fields to POST for the request.
Return Type
- CreateMobileAuthorizationCodeResponse|error - Success
renewToken
function renewToken(string clientId, RenewTokenRequest payload) returns RenewTokenResponse|error
RenewToken
Parameters
- clientId string - Your application ID, available from the developer dashboard.
- payload RenewTokenRequest - An object containing the fields to POST for the request.
Return Type
- RenewTokenResponse|error - Success
revokeToken
function revokeToken(RevokeTokenRequest payload) returns RevokeTokenResponse|error
RevokeToken
Parameters
- payload RevokeTokenRequest - An object containing the fields to POST for the request.
Return Type
- RevokeTokenResponse|error - Success
obtainToken
function obtainToken(ObtainTokenRequest payload) returns ObtainTokenResponse|error
ObtainToken
Parameters
- payload ObtainTokenRequest - An object containing the fields to POST for the request.
Return Type
- ObtainTokenResponse|error - Success
listEmployees
function listEmployees(string? 'order, string? beginUpdatedAt, string? endUpdatedAt, string? beginCreatedAt, string? endCreatedAt, string? status, string? externalId, int? 'limit, string? batchToken) returns V1Employee[]|error
ListEmployees
Parameters
- 'order string? (default ()) - The order in which employees are listed in the response, based on their created_at field. Default value: ASC
- beginUpdatedAt string? (default ()) - If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format
- endUpdatedAt string? (default ()) - If filtering results by there updated_at field, the end of the requested reporting period, in ISO 8601 format.
- beginCreatedAt string? (default ()) - If filtering results by their created_at field, the beginning of the requested reporting period, in ISO 8601 format.
- endCreatedAt string? (default ()) - If filtering results by their created_at field, the end of the requested reporting period, in ISO 8601 format.
- status string? (default ()) - If provided, the endpoint returns only employee entities with the specified status (ACTIVE or INACTIVE).
- externalId string? (default ()) - If provided, the endpoint returns only employee entities with the specified external_id.
- 'limit int? (default ()) - The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.
- batchToken string? (default ()) - A pagination cursor to retrieve the next set of results for your original query to the endpoint.
Return Type
- V1Employee[]|error - Success
createEmployee
function createEmployee(V1Employee payload) returns V1Employee|error
CreateEmployee
Parameters
- payload V1Employee - An object containing the fields to POST for the request.
Return Type
- V1Employee|error - Success
retrieveEmployee
function retrieveEmployee(string employeeId) returns V1Employee|error
RetrieveEmployee
Parameters
- employeeId string - The employee's ID.
Return Type
- V1Employee|error - Success
updateEmployee
function updateEmployee(string employeeId, V1Employee payload) returns V1Employee|error
UpdateEmployee
Parameters
- employeeId string - The ID of the role to modify.
- payload V1Employee - An object containing the fields to POST for the request.
Return Type
- V1Employee|error - Success
listEmployeeRoles
function listEmployeeRoles(string? 'order, int? 'limit, string? batchToken) returns V1EmployeeRole[]|error
ListEmployeeRoles
Parameters
- 'order string? (default ()) - The order in which employees are listed in the response, based on their created_at field.Default value: ASC
- 'limit int? (default ()) - The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.
- batchToken string? (default ()) - A pagination cursor to retrieve the next set of results for your original query to the endpoint.
Return Type
- V1EmployeeRole[]|error - Success
createEmployeeRole
function createEmployeeRole(V1EmployeeRole payload) returns V1EmployeeRole|error
CreateEmployeeRole
Parameters
- payload V1EmployeeRole - An EmployeeRole object with a name and permissions, and an optional owner flag.
Return Type
- V1EmployeeRole|error - Success
retrieveEmployeeRole
function retrieveEmployeeRole(string roleId) returns V1EmployeeRole|error
RetrieveEmployeeRole
Parameters
- roleId string - The role's ID.
Return Type
- V1EmployeeRole|error - Success
updateEmployeeRole
function updateEmployeeRole(string roleId, V1EmployeeRole payload) returns V1EmployeeRole|error
UpdateEmployeeRole
Parameters
- roleId string - The ID of the role to modify.
- payload V1EmployeeRole - An object containing the fields to POST for the request.
Return Type
- V1EmployeeRole|error - Success
listOrders
function listOrders(string locationId, string? 'order, int? 'limit, string? batchToken) returns V1Order[]|error
ListOrders
Parameters
- locationId string - The ID of the location to list online store orders for.
- 'order string? (default ()) - The order in which payments are listed in the response.
- 'limit int? (default ()) - The maximum number of payments to return in a single response. This value cannot exceed 200.
- batchToken string? (default ()) - A pagination cursor to retrieve the next set of results for your original query to the endpoint.
retrieveOrder
RetrieveOrder
Parameters
- locationId string - The ID of the order's associated location.
- orderId string - The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint
updateOrder
function updateOrder(string locationId, string orderId, V1UpdateOrderRequest payload) returns V1Order|error
UpdateOrder
Parameters
- locationId string - The ID of the order's associated location.
- orderId string - The order's Square-issued ID. You obtain this value from Order objects returned by the List Orders endpoint
- payload V1UpdateOrderRequest - An object containing the fields to POST for the request.
listPayments
function listPayments(string locationId, string? 'order, string? beginTime, string? endTime, int? 'limit, string? batchToken, boolean? includePartial) returns V1Payment[]|error
ListPayments
Parameters
- locationId string - The ID of the location to list payments for. If you specify me, this endpoint returns payments aggregated from all of the business's locations.
- 'order string? (default ()) - The order in which payments are listed in the response.
- beginTime string? (default ()) - The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year.
- endTime string? (default ()) - The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time.
- 'limit int? (default ()) - The maximum number of payments to return in a single response. This value cannot exceed 200.
- batchToken string? (default ()) - A pagination cursor to retrieve the next set of results for your original query to the endpoint.
- includePartial boolean? (default ()) - Indicates whether or not to include partial payments in the response. Partial payments will have the tenders collected so far, but the itemizations will be empty until the payment is completed.
retrievePayment
RetrievePayment
Parameters
- locationId string - The ID of the payment's associated location.
- paymentId string - The Square-issued payment ID. payment_id comes from Payment objects returned by the List Payments endpoint, Settlement objects returned by the List Settlements endpoint, or Refund objects returned by the List Refunds endpoint.
listRefunds
function listRefunds(string locationId, string? 'order, string? beginTime, string? endTime, int? 'limit, string? batchToken) returns V1Refund[]|error
ListRefunds
Parameters
- locationId string - The ID of the location to list refunds for.
- 'order string? (default ()) - The order in which payments are listed in the response.
- beginTime string? (default ()) - The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year.
- endTime string? (default ()) - The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time.
- 'limit int? (default ()) - The approximate number of refunds to return in a single response. Default: 100. Max: 200. Response may contain more results than the prescribed limit when refunds are made simultaneously to multiple tenders in a payment or when refunds are generated in an exchange to account for the value of returned goods.
- batchToken string? (default ()) - A pagination cursor to retrieve the next set of results for your original query to the endpoint.
createRefund
function createRefund(string locationId, V1CreateRefundRequest payload) returns V1Refund|error
CreateRefund
Parameters
- locationId string - The ID of the original payment's associated location.
- payload V1CreateRefundRequest - An object containing the fields to POST for the request.
listSettlements
function listSettlements(string locationId, string? 'order, string? beginTime, string? endTime, int? 'limit, string? status, string? batchToken) returns V1Settlement[]|error
ListSettlements
Parameters
- locationId string - The ID of the location to list settlements for. If you specify me, this endpoint returns settlements aggregated from all of the business's locations.
- 'order string? (default ()) - The order in which settlements are listed in the response.
- beginTime string? (default ()) - The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year.
- endTime string? (default ()) - The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time.
- 'limit int? (default ()) - The maximum number of settlements to return in a single response. This value cannot exceed 200.
- status string? (default ()) - Provide this parameter to retrieve only settlements with a particular status (SENT or FAILED).
- batchToken string? (default ()) - A pagination cursor to retrieve the next set of results for your original query to the endpoint.
Return Type
- V1Settlement[]|error - Success
retrieveSettlement
function retrieveSettlement(string locationId, string settlementId) returns V1Settlement|error
RetrieveSettlement
Parameters
- locationId string - The ID of the settlements's associated location.
- settlementId string - The settlement's Square-issued ID. You obtain this value from Settlement objects returned by the List Settlements endpoint.
Return Type
- V1Settlement|error - Success
registerDomain
function registerDomain(RegisterDomainRequest payload) returns RegisterDomainResponse|error
RegisterDomain
Parameters
- payload RegisterDomainRequest - An object containing the fields to POST for the request.
Return Type
- RegisterDomainResponse|error - Success
listBankAccounts
function listBankAccounts(string? cursor, int? 'limit, string? locationId) returns ListBankAccountsResponse|error
ListBankAccounts
Parameters
- cursor string? (default ()) - The pagination cursor returned by a previous call to this endpoint. Use it in the next
ListBankAccounts
request to retrieve the next set of results. See the Pagination guide for more information.
- 'limit int? (default ()) - Upper limit on the number of bank accounts to return in the response. Currently, 1000 is the largest supported limit. You can specify a limit of up to 1000 bank accounts. This is also the default limit.
- locationId string? (default ()) - Location ID. You can specify this optional filter to retrieve only the linked bank accounts belonging to a specific location.
Return Type
- ListBankAccountsResponse|error - Success
getBankAccountByV1Id
function getBankAccountByV1Id(string v1BankAccountId) returns GetBankAccountByV1IdResponse|error
GetBankAccountByV1Id
Parameters
- v1BankAccountId string - Connect V1 ID of the desired
BankAccount
. For more information, see Retrieve a bank account by using an ID issued by V1 Bank Accounts API.
Return Type
- GetBankAccountByV1IdResponse|error - Success
getBankAccount
function getBankAccount(string bankAccountId) returns GetBankAccountResponse|error
GetBankAccount
Parameters
- bankAccountId string - Square-issued ID of the desired
BankAccount
.
Return Type
- GetBankAccountResponse|error - Success
createBooking
function createBooking(CreateBookingRequest payload) returns CreateBookingResponse|error
CreateBooking
Parameters
- payload CreateBookingRequest - An object containing the fields to POST for the request.
Return Type
- CreateBookingResponse|error - Success
searchAvailability
function searchAvailability(SearchAvailabilityRequest payload) returns SearchAvailabilityResponse|error
SearchAvailability
Parameters
- payload SearchAvailabilityRequest - An object containing the fields to POST for the request.
Return Type
- SearchAvailabilityResponse|error - Success
retrieveBusinessBookingProfile
function retrieveBusinessBookingProfile() returns RetrieveBusinessBookingProfileResponse|error
RetrieveBusinessBookingProfile
Return Type
- RetrieveBusinessBookingProfileResponse|error - Success
listTeamMemberBookingProfiles
function listTeamMemberBookingProfiles(boolean? bookableOnly, int? 'limit, string? cursor, string? locationId) returns ListTeamMemberBookingProfilesResponse|error
ListTeamMemberBookingProfiles
Parameters
- bookableOnly boolean? (default ()) - Indicates whether to include only bookable team members in the returned result (
true
) or not (false
).
- 'limit int? (default ()) - The maximum number of results to return.
- cursor string? (default ()) - The cursor for paginating through the results.
- locationId string? (default ()) - Indicates whether to include only team members enabled at the given location in the returned result.
Return Type
- ListTeamMemberBookingProfilesResponse|error - Success
retrieveTeamMemberBookingProfile
function retrieveTeamMemberBookingProfile(string teamMemberId) returns RetrieveTeamMemberBookingProfileResponse|error
RetrieveTeamMemberBookingProfile
Parameters
- teamMemberId string - The ID of the team member to retrieve.
Return Type
retrieveBooking
function retrieveBooking(string bookingId) returns RetrieveBookingResponse|error
RetrieveBooking
Return Type
- RetrieveBookingResponse|error - Success
updateBooking
function updateBooking(string bookingId, UpdateBookingRequest payload) returns UpdateBookingResponse|error
UpdateBooking
Parameters
- payload UpdateBookingRequest - An object containing the fields to POST for the request.
Return Type
- UpdateBookingResponse|error - Success
cancelBooking
function cancelBooking(string bookingId, CancelBookingRequest payload) returns CancelBookingResponse|error
CancelBooking
Parameters
- payload CancelBookingRequest - An object containing the fields to POST for the request.
Return Type
- CancelBookingResponse|error - Success
listCards
function listCards(string? cursor, string? customerId, boolean? includeDisabled, string? referenceId, string? sortOrder) returns ListCardsResponse|error
ListCards
Parameters
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See Pagination for more information.
- customerId string? (default ()) - Limit results to cards associated with the customer supplied. By default, all cards owned by the merchant are returned.
- includeDisabled boolean? (default ()) - Includes disabled cards. By default, all enabled cards owned by the merchant are returned.
- referenceId string? (default ()) - Limit results to cards associated with the reference_id supplied.
- sortOrder string? (default ()) - Sorts the returned list by when the card was created with the specified order. This field defaults to ASC.
Return Type
- ListCardsResponse|error - Success
createCard
function createCard(CreateCardRequest payload) returns CreateCardResponse|error
CreateCard
Parameters
- payload CreateCardRequest - An object containing the fields to POST for the request.
Return Type
- CreateCardResponse|error - Success
retrieveCard
function retrieveCard(string cardId) returns RetrieveCardResponse|error
RetrieveCard
Parameters
- cardId string - Unique ID for the desired Card.
Return Type
- RetrieveCardResponse|error - Success
disableCard
function disableCard(string cardId) returns DisableCardResponse|error
DisableCard
Parameters
- cardId string - Unique ID for the desired Card.
Return Type
- DisableCardResponse|error - Success
listCashDrawerShifts
function listCashDrawerShifts(string locationId, string? sortOrder, string? beginTime, string? endTime, int? 'limit, string? cursor) returns ListCashDrawerShiftsResponse|error
ListCashDrawerShifts
Parameters
- locationId string - The ID of the location to query for a list of cash drawer shifts.
- sortOrder string? (default ()) - The order in which cash drawer shifts are listed in the response, based on their opened_at field. Default value: ASC
- beginTime string? (default ()) - The inclusive start time of the query on opened_at, in ISO 8601 format.
- endTime string? (default ()) - The exclusive end date of the query on opened_at, in ISO 8601 format.
- 'limit int? (default ()) - Number of cash drawer shift events in a page of results (200 by default, 1000 max).
- cursor string? (default ()) - Opaque cursor for fetching the next page of results.
Return Type
- ListCashDrawerShiftsResponse|error - Success
retrieveCashDrawerShift
function retrieveCashDrawerShift(string locationId, string shiftId) returns RetrieveCashDrawerShiftResponse|error
RetrieveCashDrawerShift
Parameters
- locationId string - The ID of the location to retrieve cash drawer shifts from.
- shiftId string - The shift ID.
Return Type
- RetrieveCashDrawerShiftResponse|error - Success
listCashDrawerShiftEvents
function listCashDrawerShiftEvents(string locationId, string shiftId, int? 'limit, string? cursor) returns ListCashDrawerShiftEventsResponse|error
ListCashDrawerShiftEvents
Parameters
- locationId string - The ID of the location to list cash drawer shifts for.
- shiftId string - The shift ID.
- 'limit int? (default ()) - Number of resources to be returned in a page of results (200 by default, 1000 max).
- cursor string? (default ()) - Opaque cursor for fetching the next page of results.
Return Type
- ListCashDrawerShiftEventsResponse|error - Success
batchDeleteCatalogObjects
function batchDeleteCatalogObjects(BatchDeleteCatalogObjectsRequest payload) returns BatchDeleteCatalogObjectsResponse|error
BatchDeleteCatalogObjects
Parameters
- payload BatchDeleteCatalogObjectsRequest - An object containing the fields to POST for the request.
Return Type
- BatchDeleteCatalogObjectsResponse|error - Success
batchRetrieveCatalogObjects
function batchRetrieveCatalogObjects(BatchRetrieveCatalogObjectsRequest payload) returns BatchRetrieveCatalogObjectsResponse|error
BatchRetrieveCatalogObjects
Parameters
- payload BatchRetrieveCatalogObjectsRequest - An object containing the fields to POST for the request.
Return Type
- BatchRetrieveCatalogObjectsResponse|error - Success
batchUpsertCatalogObjects
function batchUpsertCatalogObjects(BatchUpsertCatalogObjectsRequest payload) returns BatchUpsertCatalogObjectsResponse|error
BatchUpsertCatalogObjects
Parameters
- payload BatchUpsertCatalogObjectsRequest - An object containing the fields to POST for the request.
Return Type
- BatchUpsertCatalogObjectsResponse|error - Success
catalogInfo
function catalogInfo() returns CatalogInfoResponse|error
CatalogInfo
Return Type
- CatalogInfoResponse|error - Success
listCatalog
function listCatalog(string? cursor, string? types, int? catalogVersion) returns ListCatalogResponse|error
ListCatalog
Parameters
- cursor string? (default ()) - The pagination cursor returned in the previous response. Leave unset for an initial request. The page size is currently set to be 100. See Pagination for more information.
- types string? (default ()) - An optional case-insensitive, comma-separated list of object types to retrieve. The valid values are defined in the CatalogObjectType enum, including
ITEM
,ITEM_VARIATION
,CATEGORY
,DISCOUNT
,TAX
,MODIFIER
,MODIFIER_LIST
, orIMAGE
. If this is unspecified, the operation returns objects of all the types at the version of the Square API used to make the request.
- catalogVersion int? (default ()) - The specific version of the catalog objects to be included in the response. This allows you to retrieve historical versions of objects. The specified version value is matched against the CatalogObjects'
version
attribute.
Return Type
- ListCatalogResponse|error - Success
upsertCatalogObject
function upsertCatalogObject(UpsertCatalogObjectRequest payload) returns UpsertCatalogObjectResponse|error
UpsertCatalogObject
Parameters
- payload UpsertCatalogObjectRequest - An object containing the fields to POST for the request.
Return Type
- UpsertCatalogObjectResponse|error - Success
retrieveCatalogObject
function retrieveCatalogObject(string objectId, boolean? includeRelatedObjects, int? catalogVersion) returns RetrieveCatalogObjectResponse|error
RetrieveCatalogObject
Parameters
- objectId string - The object ID of any type of catalog objects to be retrieved.
- includeRelatedObjects boolean? (default ()) - If
true
, the response will include additional objects that are related to the requested object, as follows: If theobject
field of the response contains aCatalogItem
, its associatedCatalogCategory
,CatalogTax
,CatalogImage
andCatalogModifierList
objects will be returned in therelated_objects
field of the response. If theobject
field of the response contains aCatalogItemVariation
, its parentCatalogItem
will be returned in therelated_objects
field of the response. Default value:false
- catalogVersion int? (default ()) - Requests objects as of a specific version of the catalog. This allows you to retrieve historical versions of objects. The value to retrieve a specific version of an object can be found in the version field of CatalogObjects.
Return Type
- RetrieveCatalogObjectResponse|error - Success
deleteCatalogObject
function deleteCatalogObject(string objectId) returns DeleteCatalogObjectResponse|error
DeleteCatalogObject
Parameters
- objectId string - The ID of the catalog object to be deleted. When an object is deleted, other objects in the graph that depend on that object will be deleted as well (for example, deleting a catalog item will delete its catalog item variations).
Return Type
- DeleteCatalogObjectResponse|error - Success
searchCatalogObjects
function searchCatalogObjects(SearchCatalogObjectsRequest payload) returns SearchCatalogObjectsResponse|error
SearchCatalogObjects
Parameters
- payload SearchCatalogObjectsRequest - An object containing the fields to POST for the request.
Return Type
- SearchCatalogObjectsResponse|error - Success
searchCatalogItems
function searchCatalogItems(SearchCatalogItemsRequest payload) returns SearchCatalogItemsResponse|error
SearchCatalogItems
Parameters
- payload SearchCatalogItemsRequest - An object containing the fields to POST for the request.
Return Type
- SearchCatalogItemsResponse|error - Success
updateItemModifierLists
function updateItemModifierLists(UpdateItemModifierListsRequest payload) returns UpdateItemModifierListsResponse|error
UpdateItemModifierLists
Parameters
- payload UpdateItemModifierListsRequest - An object containing the fields to POST for the request.
Return Type
- UpdateItemModifierListsResponse|error - Success
updateItemTaxes
function updateItemTaxes(UpdateItemTaxesRequest payload) returns UpdateItemTaxesResponse|error
UpdateItemTaxes
Parameters
- payload UpdateItemTaxesRequest - An object containing the fields to POST for the request.
Return Type
- UpdateItemTaxesResponse|error - Success
listCustomers
function listCustomers(string? cursor, int? 'limit, string? sortField, string? sortOrder) returns ListCustomersResponse|error
ListCustomers
Parameters
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see Pagination.
- 'limit int? (default ()) - The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. The limit is ignored if it is less than 1 or greater than 100. The default value is 100. For more information, see Pagination.
- sortField string? (default ()) - Indicates how customers should be sorted. The default value is
DEFAULT
.
- sortOrder string? (default ()) - Indicates whether customers should be sorted in ascending (
ASC
) or descending (DESC
) order. The default value isASC
.
Return Type
- ListCustomersResponse|error - Success
createCustomer
function createCustomer(CreateCustomerRequest payload) returns CreateCustomerResponse|error
CreateCustomer
Parameters
- payload CreateCustomerRequest - An object containing the fields to POST for the request.
Return Type
- CreateCustomerResponse|error - Success
listCustomerGroups
function listCustomerGroups(string? cursor, int? 'limit) returns ListCustomerGroupsResponse|error
ListCustomerGroups
Parameters
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see Pagination.
- 'limit int? (default ()) - The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. The limit is ignored if it is less than 1 or greater than 50. The default value is 50. For more information, see Pagination.
Return Type
- ListCustomerGroupsResponse|error - Success
createCustomerGroup
function createCustomerGroup(CreateCustomerGroupRequest payload) returns CreateCustomerGroupResponse|error
CreateCustomerGroup
Parameters
- payload CreateCustomerGroupRequest - An object containing the fields to POST for the request.
Return Type
- CreateCustomerGroupResponse|error - Success
retrieveCustomerGroup
function retrieveCustomerGroup(string groupId) returns RetrieveCustomerGroupResponse|error
RetrieveCustomerGroup
Parameters
- groupId string - The ID of the customer group to retrieve.
Return Type
- RetrieveCustomerGroupResponse|error - Success
updateCustomerGroup
function updateCustomerGroup(string groupId, UpdateCustomerGroupRequest payload) returns UpdateCustomerGroupResponse|error
UpdateCustomerGroup
Parameters
- groupId string - The ID of the customer group to update.
- payload UpdateCustomerGroupRequest - An object containing the fields to POST for the request.
Return Type
- UpdateCustomerGroupResponse|error - Success
deleteCustomerGroup
function deleteCustomerGroup(string groupId) returns DeleteCustomerGroupResponse|error
DeleteCustomerGroup
Parameters
- groupId string - The ID of the customer group to delete.
Return Type
- DeleteCustomerGroupResponse|error - Success
searchCustomers
function searchCustomers(SearchCustomersRequest payload) returns SearchCustomersResponse|error
SearchCustomers
Parameters
- payload SearchCustomersRequest - An object containing the fields to POST for the request.
Return Type
- SearchCustomersResponse|error - Success
listCustomerSegments
function listCustomerSegments(string? cursor, int? 'limit) returns ListCustomerSegmentsResponse|error
ListCustomerSegments
Parameters
- cursor string? (default ()) - A pagination cursor returned by previous calls to
ListCustomerSegments
. This cursor is used to retrieve the next set of query results. For more information, see Pagination.
- 'limit int? (default ()) - The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. The limit is ignored if it is less than 1 or greater than 50. The default value is 50. For more information, see Pagination.
Return Type
- ListCustomerSegmentsResponse|error - Success
retrieveCustomerSegment
function retrieveCustomerSegment(string segmentId) returns RetrieveCustomerSegmentResponse|error
RetrieveCustomerSegment
Parameters
- segmentId string - The Square-issued ID of the customer segment.
Return Type
- RetrieveCustomerSegmentResponse|error - Success
retrieveCustomer
function retrieveCustomer(string customerId) returns RetrieveCustomerResponse|error
RetrieveCustomer
Parameters
- customerId string - The ID of the customer to retrieve.
Return Type
- RetrieveCustomerResponse|error - Success
updateCustomer
function updateCustomer(string customerId, UpdateCustomerRequest payload) returns UpdateCustomerResponse|error
UpdateCustomer
Parameters
- customerId string - The ID of the customer to update.
- payload UpdateCustomerRequest - An object containing the fields to POST for the request.
Return Type
- UpdateCustomerResponse|error - Success
deleteCustomer
function deleteCustomer(string customerId, int? 'version) returns DeleteCustomerResponse|error
DeleteCustomer
Parameters
- customerId string - The ID of the customer to delete.
- 'version int? (default ()) - The current version of the customer profile. As a best practice, you should include this parameter to enable optimistic concurrency control. For more information, see Delete a customer profile.
Return Type
- DeleteCustomerResponse|error - Success
createCustomerCard
function createCustomerCard(string customerId, CreateCustomerCardRequest payload) returns CreateCustomerCardResponse|error
CreateCustomerCard
Parameters
- customerId string - The Square ID of the customer profile the card is linked to.
- payload CreateCustomerCardRequest - An object containing the fields to POST for the request.
Return Type
- CreateCustomerCardResponse|error - Success
deleteCustomerCard
function deleteCustomerCard(string customerId, string cardId) returns DeleteCustomerCardResponse|error
DeleteCustomerCard
Parameters
- customerId string - The ID of the customer that the card on file belongs to.
- cardId string - The ID of the card on file to delete.
Return Type
- DeleteCustomerCardResponse|error - Success
addGroupToCustomer
function addGroupToCustomer(string customerId, string groupId) returns AddGroupToCustomerResponse|error
AddGroupToCustomer
Parameters
- customerId string - The ID of the customer to add to a group.
- groupId string - The ID of the customer group to add the customer to.
Return Type
- AddGroupToCustomerResponse|error - Success
removeGroupFromCustomer
function removeGroupFromCustomer(string customerId, string groupId) returns RemoveGroupFromCustomerResponse|error
RemoveGroupFromCustomer
Parameters
- customerId string - The ID of the customer to remove from the group.
- groupId string - The ID of the customer group to remove the customer from.
Return Type
- RemoveGroupFromCustomerResponse|error - Success
listDeviceCodes
function listDeviceCodes(string? cursor, string? locationId, string? productType, string? status) returns ListDeviceCodesResponse|error
ListDeviceCodes
Parameters
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See Paginating results for more information.
- locationId string? (default ()) - If specified, only returns DeviceCodes of the specified location. Returns DeviceCodes of all locations if empty.
- productType string? (default ()) - If specified, only returns DeviceCodes targeting the specified product type. Returns DeviceCodes of all product types if empty.
- status string? (default ()) - If specified, returns DeviceCodes with the specified statuses. Returns DeviceCodes of status
PAIRED
andUNPAIRED
if empty.
Return Type
- ListDeviceCodesResponse|error - Success
createDeviceCode
function createDeviceCode(CreateDeviceCodeRequest payload) returns CreateDeviceCodeResponse|error
CreateDeviceCode
Parameters
- payload CreateDeviceCodeRequest - An object containing the fields to POST for the request.
Return Type
- CreateDeviceCodeResponse|error - Success
getDeviceCode
function getDeviceCode(string id) returns GetDeviceCodeResponse|error
GetDeviceCode
Parameters
- id string - The unique identifier for the device code.
Return Type
- GetDeviceCodeResponse|error - Success
listDisputes
function listDisputes(string? cursor, string? states, string? locationId) returns ListDisputesResponse|error
ListDisputes
Parameters
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see Pagination.
- states string? (default ()) - The dispute states to filter the result. If not specified, the endpoint returns all open disputes (the dispute status is not
INQUIRY_CLOSED
,WON
, orLOST
).
- locationId string? (default ()) - The ID of the location for which to return a list of disputes. If not specified, the endpoint returns all open disputes (the dispute status is not
INQUIRY_CLOSED
,WON
, orLOST
) associated with all locations.
Return Type
- ListDisputesResponse|error - Success
retrieveDispute
function retrieveDispute(string disputeId) returns RetrieveDisputeResponse|error
RetrieveDispute
Parameters
- disputeId string - The ID of the dispute you want more details about.
Return Type
- RetrieveDisputeResponse|error - Success
acceptDispute
function acceptDispute(string disputeId) returns AcceptDisputeResponse|error
AcceptDispute
Parameters
- disputeId string - The ID of the dispute you want to accept.
Return Type
- AcceptDisputeResponse|error - Success
listDisputeEvidence
function listDisputeEvidence(string disputeId, string? cursor) returns ListDisputeEvidenceResponse|error
ListDisputeEvidence
Parameters
- disputeId string - The ID of the dispute.
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see Pagination.
Return Type
- ListDisputeEvidenceResponse|error - Success
createDisputeEvidenceText
function createDisputeEvidenceText(string disputeId, CreateDisputeEvidenceTextRequest payload) returns CreateDisputeEvidenceTextResponse|error
CreateDisputeEvidenceText
Parameters
- disputeId string - The ID of the dispute you want to upload evidence for.
- payload CreateDisputeEvidenceTextRequest - An object containing the fields to POST for the request.
Return Type
- CreateDisputeEvidenceTextResponse|error - Success
retrieveDisputeEvidence
function retrieveDisputeEvidence(string disputeId, string evidenceId) returns RetrieveDisputeEvidenceResponse|error
RetrieveDisputeEvidence
Parameters
- disputeId string - The ID of the dispute that you want to retrieve evidence from.
- evidenceId string - The ID of the evidence to retrieve.
Return Type
- RetrieveDisputeEvidenceResponse|error - Success
deleteDisputeEvidence
function deleteDisputeEvidence(string disputeId, string evidenceId) returns DeleteDisputeEvidenceResponse|error
DeleteDisputeEvidence
Parameters
- disputeId string - The ID of the dispute you want to remove evidence from.
- evidenceId string - The ID of the evidence you want to remove.
Return Type
- DeleteDisputeEvidenceResponse|error - Success
submitEvidence
function submitEvidence(string disputeId) returns SubmitEvidenceResponse|error
SubmitEvidence
Parameters
- disputeId string - The ID of the dispute that you want to submit evidence for.
Return Type
- SubmitEvidenceResponse|error - Success
getEmployees
function getEmployees(string? locationId, string? status, int? 'limit, string? cursor) returns ListEmployeesResponse|error
ListEmployees
Parameters
- locationId string? (default ()) -
- status string? (default ()) - Specifies the EmployeeStatus to filter the employee by.
- 'limit int? (default ()) - The number of employees to be returned on each page.
- cursor string? (default ()) - The token required to retrieve the specified page of results.
Return Type
- ListEmployeesResponse|error - Success
getEmployeesById
function getEmployeesById(string id) returns RetrieveEmployeeResponse|error
RetrieveEmployee
Parameters
- id string - UUID for the employee that was requested.
Return Type
- RetrieveEmployeeResponse|error - Success
listGiftCards
function listGiftCards(string? 'type, string? state, int? 'limit, string? cursor, string? customerId) returns ListGiftCardsResponse|error
ListGiftCards
Parameters
- 'type string? (default ()) - If a type is provided, gift cards of this type are returned (see GiftCardType). If no type is provided, it returns gift cards of all types.
- state string? (default ()) - If the state is provided, it returns the gift cards in the specified state (see GiftCardStatus). Otherwise, it returns the gift cards of all states.
- 'limit int? (default ()) - If a value is provided, it returns only that number of results per page. The maximum number of results allowed per page is 50. The default value is 30.
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, it returns the first page of the results. For more information, see Pagination.
- customerId string? (default ()) - If a value is provided, returns only the gift cards linked to the specified customer
Return Type
- ListGiftCardsResponse|error - Success
createGiftCard
function createGiftCard(CreateGiftCardRequest payload) returns CreateGiftCardResponse|error
CreateGiftCard
Parameters
- payload CreateGiftCardRequest - An object containing the fields to POST for the request.
Return Type
- CreateGiftCardResponse|error - Success
listGiftCardActivities
function listGiftCardActivities(string? giftCardId, string? 'type, string? locationId, string? beginTime, string? endTime, int? 'limit, string? cursor, string? sortOrder) returns ListGiftCardActivitiesResponse|error
ListGiftCardActivities
Parameters
- giftCardId string? (default ()) - If you provide a gift card ID, the endpoint returns activities that belong to the specified gift card. Otherwise, the endpoint returns all gift card activities for the seller.
- 'type string? (default ()) - If you provide a type, the endpoint returns gift card activities of this type. Otherwise, the endpoint returns all types of gift card activities.
- locationId string? (default ()) - If you provide a location ID, the endpoint returns gift card activities for that location. Otherwise, the endpoint returns gift card activities for all locations.
- beginTime string? (default ()) - The timestamp for the beginning of the reporting period, in RFC 3339 format. Inclusive. Default: The current time minus one year.
- endTime string? (default ()) - The timestamp for the end of the reporting period, in RFC 3339 format. Inclusive. Default: The current time.
- 'limit int? (default ()) - If you provide a limit value, the endpoint returns the specified number of results (or less) per page. A maximum value is 100. The default value is 50.
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If you do not provide the cursor, the call returns the first page of the results.
- sortOrder string? (default ()) - The order in which the endpoint returns the activities, based on
created_at
. -ASC
- Oldest to newest. -DESC
- Newest to oldest (default).
Return Type
- ListGiftCardActivitiesResponse|error - Success
createGiftCardActivity
function createGiftCardActivity(CreateGiftCardActivityRequest payload) returns CreateGiftCardActivityResponse|error
CreateGiftCardActivity
Parameters
- payload CreateGiftCardActivityRequest - An object containing the fields to POST for the request.
Return Type
- CreateGiftCardActivityResponse|error - Success
retrieveGiftCardFromGAN
function retrieveGiftCardFromGAN(RetrieveGiftCardFromGANRequest payload) returns RetrieveGiftCardFromGANResponse|error
RetrieveGiftCardFromGAN
Parameters
- payload RetrieveGiftCardFromGANRequest - An object containing the fields to POST for the request.
Return Type
- RetrieveGiftCardFromGANResponse|error - Success
retrieveGiftCardFromNonce
function retrieveGiftCardFromNonce(RetrieveGiftCardFromNonceRequest payload) returns RetrieveGiftCardFromNonceResponse|error
RetrieveGiftCardFromNonce
Parameters
- payload RetrieveGiftCardFromNonceRequest - An object containing the fields to POST for the request.
Return Type
- RetrieveGiftCardFromNonceResponse|error - Success
linkCustomerToGiftCard
function linkCustomerToGiftCard(string giftCardId, LinkCustomerToGiftCardRequest payload) returns LinkCustomerToGiftCardResponse|error
LinkCustomerToGiftCard
Parameters
- giftCardId string - The ID of the gift card to link.
- payload LinkCustomerToGiftCardRequest - An object containing the fields to POST for the request.
Return Type
- LinkCustomerToGiftCardResponse|error - Success
unlinkCustomerFromGiftCard
function unlinkCustomerFromGiftCard(string giftCardId, UnlinkCustomerFromGiftCardRequest payload) returns UnlinkCustomerFromGiftCardResponse|error
UnlinkCustomerFromGiftCard
Parameters
- giftCardId string -
- payload UnlinkCustomerFromGiftCardRequest - An object containing the fields to POST for the request.
Return Type
- UnlinkCustomerFromGiftCardResponse|error - Success
retrieveGiftCard
function retrieveGiftCard(string id) returns RetrieveGiftCardResponse|error
RetrieveGiftCard
Parameters
- id string - The ID of the gift card to retrieve.
Return Type
- RetrieveGiftCardResponse|error - Success
deprecatedRetrieveInventoryAdjustment
function deprecatedRetrieveInventoryAdjustment(string adjustmentId) returns RetrieveInventoryAdjustmentResponse|error
DeprecatedRetrieveInventoryAdjustment
Parameters
- adjustmentId string - ID of the InventoryAdjustment to retrieve.
Return Type
- RetrieveInventoryAdjustmentResponse|error - Success
retrieveInventoryAdjustment
function retrieveInventoryAdjustment(string adjustmentId) returns RetrieveInventoryAdjustmentResponse|error
RetrieveInventoryAdjustment
Parameters
- adjustmentId string - ID of the InventoryAdjustment to retrieve.
Return Type
- RetrieveInventoryAdjustmentResponse|error - Success
deprecatedBatchChangeInventory
function deprecatedBatchChangeInventory(BatchChangeInventoryRequest payload) returns BatchChangeInventoryResponse|error
DeprecatedBatchChangeInventory
Parameters
- payload BatchChangeInventoryRequest - An object containing the fields to POST for the request.
Return Type
- BatchChangeInventoryResponse|error - Success
deprecatedBatchRetrieveInventoryChanges
function deprecatedBatchRetrieveInventoryChanges(BatchRetrieveInventoryChangesRequest payload) returns BatchRetrieveInventoryChangesResponse|error
DeprecatedBatchRetrieveInventoryChanges
Parameters
- payload BatchRetrieveInventoryChangesRequest - An object containing the fields to POST for the request.
Return Type
- BatchRetrieveInventoryChangesResponse|error - Success
deprecatedBatchRetrieveInventoryCounts
function deprecatedBatchRetrieveInventoryCounts(BatchRetrieveInventoryCountsRequest payload) returns BatchRetrieveInventoryCountsResponse|error
DeprecatedBatchRetrieveInventoryCounts
Parameters
- payload BatchRetrieveInventoryCountsRequest - An object containing the fields to POST for the request.
Return Type
- BatchRetrieveInventoryCountsResponse|error - Success
batchChangeInventory
function batchChangeInventory(BatchChangeInventoryRequest payload) returns BatchChangeInventoryResponse|error
BatchChangeInventory
Parameters
- payload BatchChangeInventoryRequest - An object containing the fields to POST for the request.
Return Type
- BatchChangeInventoryResponse|error - Success
batchRetrieveInventoryChanges
function batchRetrieveInventoryChanges(BatchRetrieveInventoryChangesRequest payload) returns BatchRetrieveInventoryChangesResponse|error
BatchRetrieveInventoryChanges
Parameters
- payload BatchRetrieveInventoryChangesRequest - An object containing the fields to POST for the request.
Return Type
- BatchRetrieveInventoryChangesResponse|error - Success
batchRetrieveInventoryCounts
function batchRetrieveInventoryCounts(BatchRetrieveInventoryCountsRequest payload) returns BatchRetrieveInventoryCountsResponse|error
BatchRetrieveInventoryCounts
Parameters
- payload BatchRetrieveInventoryCountsRequest - An object containing the fields to POST for the request.
Return Type
- BatchRetrieveInventoryCountsResponse|error - Success
deprecatedRetrieveInventoryPhysicalCount
function deprecatedRetrieveInventoryPhysicalCount(string physicalCountId) returns RetrieveInventoryPhysicalCountResponse|error
DeprecatedRetrieveInventoryPhysicalCount
Parameters
- physicalCountId string - ID of the InventoryPhysicalCount to retrieve.
Return Type
- RetrieveInventoryPhysicalCountResponse|error - Success
retrieveInventoryPhysicalCount
function retrieveInventoryPhysicalCount(string physicalCountId) returns RetrieveInventoryPhysicalCountResponse|error
RetrieveInventoryPhysicalCount
Parameters
- physicalCountId string - ID of the InventoryPhysicalCount to retrieve.
Return Type
- RetrieveInventoryPhysicalCountResponse|error - Success
retrieveInventoryTransfer
function retrieveInventoryTransfer(string transferId) returns RetrieveInventoryTransferResponse|error
RetrieveInventoryTransfer
Parameters
- transferId string - ID of the InventoryTransfer to retrieve.
Return Type
- RetrieveInventoryTransferResponse|error - Success
retrieveInventoryCount
function retrieveInventoryCount(string catalogObjectId, string? locationIds, string? cursor) returns RetrieveInventoryCountResponse|error
RetrieveInventoryCount
Parameters
- catalogObjectId string - ID of the CatalogObject to retrieve.
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See the Pagination guide for more information.
Return Type
- RetrieveInventoryCountResponse|error - Success
retrieveInventoryChanges
function retrieveInventoryChanges(string catalogObjectId, string? locationIds, string? cursor) returns RetrieveInventoryChangesResponse|error
RetrieveInventoryChanges
Parameters
- catalogObjectId string - ID of the CatalogObject to retrieve.
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See the Pagination guide for more information.
Return Type
- RetrieveInventoryChangesResponse|error - Success
listInvoices
function listInvoices(string locationId, string? cursor, int? 'limit) returns ListInvoicesResponse|error
ListInvoices
Parameters
- locationId string - The ID of the location for which to list invoices.
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see Pagination.
- 'limit int? (default ()) - The maximum number of invoices to return (200 is the maximum
limit
). If not provided, the server uses a default limit of 100 invoices.
Return Type
- ListInvoicesResponse|error - Success
createInvoice
function createInvoice(CreateInvoiceRequest payload) returns CreateInvoiceResponse|error
CreateInvoice
Parameters
- payload CreateInvoiceRequest - An object containing the fields to POST for the request.
Return Type
- CreateInvoiceResponse|error - Success
searchInvoices
function searchInvoices(SearchInvoicesRequest payload) returns SearchInvoicesResponse|error
SearchInvoices
Parameters
- payload SearchInvoicesRequest - An object containing the fields to POST for the request.
Return Type
- SearchInvoicesResponse|error - Success
getInvoice
function getInvoice(string invoiceId) returns GetInvoiceResponse|error
GetInvoice
Parameters
- invoiceId string - The ID of the invoice to retrieve.
Return Type
- GetInvoiceResponse|error - Success
updateInvoice
function updateInvoice(string invoiceId, UpdateInvoiceRequest payload) returns UpdateInvoiceResponse|error
UpdateInvoice
Parameters
- invoiceId string - The ID of the invoice to update.
- payload UpdateInvoiceRequest - An object containing the fields to POST for the request.
Return Type
- UpdateInvoiceResponse|error - Success
deleteInvoice
function deleteInvoice(string invoiceId, int? 'version) returns DeleteInvoiceResponse|error
DeleteInvoice
Parameters
- invoiceId string - The ID of the invoice to delete.
- 'version int? (default ()) - The version of the invoice to delete. If you do not know the version, you can call GetInvoice or ListInvoices.
Return Type
- DeleteInvoiceResponse|error - Success
cancelInvoice
function cancelInvoice(string invoiceId, CancelInvoiceRequest payload) returns CancelInvoiceResponse|error
CancelInvoice
Parameters
- payload CancelInvoiceRequest - An object containing the fields to POST for the request.
Return Type
- CancelInvoiceResponse|error - Success
publishInvoice
function publishInvoice(string invoiceId, PublishInvoiceRequest payload) returns PublishInvoiceResponse|error
PublishInvoice
Parameters
- invoiceId string - The ID of the invoice to publish.
- payload PublishInvoiceRequest - An object containing the fields to POST for the request.
Return Type
- PublishInvoiceResponse|error - Success
listBreakTypes
function listBreakTypes(string? locationId, int? 'limit, string? cursor) returns ListBreakTypesResponse|error
ListBreakTypes
Parameters
- locationId string? (default ()) - Filter the returned
BreakType
results to only those that are associated with the specified location.
- 'limit int? (default ()) - The maximum number of
BreakType
results to return per page. The number can range between 1 and 200. The default is 200.
- cursor string? (default ()) - A pointer to the next page of
BreakType
results to fetch.
Return Type
- ListBreakTypesResponse|error - Success
createBreakType
function createBreakType(CreateBreakTypeRequest payload) returns CreateBreakTypeResponse|error
CreateBreakType
Parameters
- payload CreateBreakTypeRequest - An object containing the fields to POST for the request.
Return Type
- CreateBreakTypeResponse|error - Success
getBreakType
function getBreakType(string id) returns GetBreakTypeResponse|error
GetBreakType
Parameters
- id string - The UUID for the
BreakType
being retrieved.
Return Type
- GetBreakTypeResponse|error - Success
updateBreakType
function updateBreakType(string id, UpdateBreakTypeRequest payload) returns UpdateBreakTypeResponse|error
UpdateBreakType
Parameters
- id string - The UUID for the
BreakType
being updated.
- payload UpdateBreakTypeRequest - An object containing the fields to POST for the request.
Return Type
- UpdateBreakTypeResponse|error - Success
deleteBreakType
function deleteBreakType(string id) returns DeleteBreakTypeResponse|error
DeleteBreakType
Parameters
- id string - The UUID for the
BreakType
being deleted.
Return Type
- DeleteBreakTypeResponse|error - Success
listEmployeeWages
function listEmployeeWages(string? employeeId, int? 'limit, string? cursor) returns ListEmployeeWagesResponse|error
ListEmployeeWages
Parameters
- employeeId string? (default ()) - Filter the returned wages to only those that are associated with the specified employee.
- 'limit int? (default ()) - The maximum number of
EmployeeWage
results to return per page. The number can range between 1 and 200. The default is 200.
- cursor string? (default ()) - A pointer to the next page of
EmployeeWage
results to fetch.
Return Type
- ListEmployeeWagesResponse|error - Success
getEmployeeWage
function getEmployeeWage(string id) returns GetEmployeeWageResponse|error
GetEmployeeWage
Parameters
- id string - The UUID for the
EmployeeWage
being retrieved.
Return Type
- GetEmployeeWageResponse|error - Success
createShift
function createShift(CreateShiftRequest payload) returns CreateShiftResponse|error
CreateShift
Parameters
- payload CreateShiftRequest - An object containing the fields to POST for the request.
Return Type
- CreateShiftResponse|error - Success
searchShifts
function searchShifts(SearchShiftsRequest payload) returns SearchShiftsResponse|error
SearchShifts
Parameters
- payload SearchShiftsRequest - An object containing the fields to POST for the request.
Return Type
- SearchShiftsResponse|error - Success
getShift
function getShift(string id) returns GetShiftResponse|error
GetShift
Parameters
- id string - The UUID for the
Shift
being retrieved.
Return Type
- GetShiftResponse|error - Success
updateShift
function updateShift(string id, UpdateShiftRequest payload) returns UpdateShiftResponse|error
UpdateShift
Parameters
- id string - The ID of the object being updated.
- payload UpdateShiftRequest - An object containing the fields to POST for the request.
Return Type
- UpdateShiftResponse|error - Success
deleteShift
function deleteShift(string id) returns DeleteShiftResponse|error
DeleteShift
Parameters
- id string - The UUID for the
Shift
being deleted.
Return Type
- DeleteShiftResponse|error - Success
listTeamMemberWages
function listTeamMemberWages(string? teamMemberId, int? 'limit, string? cursor) returns ListTeamMemberWagesResponse|error
ListTeamMemberWages
Parameters
- teamMemberId string? (default ()) - Filter the returned wages to only those that are associated with the specified team member.
- 'limit int? (default ()) - The maximum number of
TeamMemberWage
results to return per page. The number can range between 1 and 200. The default is 200.
- cursor string? (default ()) - A pointer to the next page of
EmployeeWage
results to fetch.
Return Type
- ListTeamMemberWagesResponse|error - Success
getTeamMemberWage
function getTeamMemberWage(string id) returns GetTeamMemberWageResponse|error
GetTeamMemberWage
Parameters
- id string - The UUID for the
TeamMemberWage
being retrieved.
Return Type
- GetTeamMemberWageResponse|error - Success
listWorkweekConfigs
function listWorkweekConfigs(int? 'limit, string? cursor) returns ListWorkweekConfigsResponse|error
ListWorkweekConfigs
Parameters
- 'limit int? (default ()) - The maximum number of
WorkweekConfigs
results to return per page.
- cursor string? (default ()) - A pointer to the next page of
WorkweekConfig
results to fetch.
Return Type
- ListWorkweekConfigsResponse|error - Success
updateWorkweekConfig
function updateWorkweekConfig(string id, UpdateWorkweekConfigRequest payload) returns UpdateWorkweekConfigResponse|error
UpdateWorkweekConfig
Parameters
- id string - The UUID for the
WorkweekConfig
object being updated.
- payload UpdateWorkweekConfigRequest - An object containing the fields to POST for the request.
Return Type
- UpdateWorkweekConfigResponse|error - Success
listLocations
function listLocations() returns ListLocationsResponse|error
ListLocations
Return Type
- ListLocationsResponse|error - Success
createLocation
function createLocation(CreateLocationRequest payload) returns CreateLocationResponse|error
CreateLocation
Parameters
- payload CreateLocationRequest - An object containing the fields to POST for the request.
Return Type
- CreateLocationResponse|error - Success
retrieveLocation
function retrieveLocation(string locationId) returns RetrieveLocationResponse|error
RetrieveLocation
Parameters
- locationId string - The ID of the location to retrieve. If you specify the string "main", then the endpoint returns the main location.
Return Type
- RetrieveLocationResponse|error - Success
updateLocation
function updateLocation(string locationId, UpdateLocationRequest payload) returns UpdateLocationResponse|error
UpdateLocation
Parameters
- locationId string - The ID of the location to update.
- payload UpdateLocationRequest - An object containing the fields to POST for the request.
Return Type
- UpdateLocationResponse|error - Success
createCheckout
function createCheckout(string locationId, CreateCheckoutRequest payload) returns CreateCheckoutResponse|error
CreateCheckout
Parameters
- locationId string - The ID of the business location to associate the checkout with.
- payload CreateCheckoutRequest - An object containing the fields to POST for the request.
Return Type
- CreateCheckoutResponse|error - Success
listRefundsByLocation
function listRefundsByLocation(string locationId, string? beginTime, string? endTime, string? sortOrder, string? cursor) returns ListRefundsResponse|error
ListRefunds
Parameters
- locationId string - The ID of the location to list refunds for.
- beginTime string? (default ()) - The beginning of the requested reporting period, in RFC 3339 format. See Date ranges for details on date inclusivity/exclusivity. Default value: The current time minus one year.
- endTime string? (default ()) - The end of the requested reporting period, in RFC 3339 format. See Date ranges for details on date inclusivity/exclusivity. Default value: The current time.
- sortOrder string? (default ()) - The order in which results are listed in the response (
ASC
for oldest first,DESC
for newest first). Default value:DESC
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See Paginating results for more information.
Return Type
- ListRefundsResponse|error - Success
listTransactions
function listTransactions(string locationId, string? beginTime, string? endTime, string? sortOrder, string? cursor) returns ListTransactionsResponse|error
ListTransactions
Parameters
- locationId string - The ID of the location to list transactions for.
- beginTime string? (default ()) - The beginning of the requested reporting period, in RFC 3339 format. See Date ranges for details on date inclusivity/exclusivity. Default value: The current time minus one year.
- endTime string? (default ()) - The end of the requested reporting period, in RFC 3339 format. See Date ranges for details on date inclusivity/exclusivity. Default value: The current time.
- sortOrder string? (default ()) - The order in which results are listed in the response (
ASC
for oldest first,DESC
for newest first). Default value:DESC
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See Paginating results for more information.
Return Type
- ListTransactionsResponse|error - Success
charge
function charge(string locationId, ChargeRequest payload) returns ChargeResponse|error
Charge
Parameters
- locationId string - The ID of the location to associate the created transaction with.
- payload ChargeRequest - An object containing the fields to POST for the request.
Return Type
- ChargeResponse|error - Success
retrieveTransaction
function retrieveTransaction(string locationId, string transactionId) returns RetrieveTransactionResponse|error
RetrieveTransaction
Parameters
- locationId string - The ID of the transaction's associated location.
- transactionId string - The ID of the transaction to retrieve.
Return Type
- RetrieveTransactionResponse|error - Success
captureTransaction
function captureTransaction(string locationId, string transactionId) returns CaptureTransactionResponse|error
CaptureTransaction
Return Type
- CaptureTransactionResponse|error - Success
initiateRefund
function initiateRefund(string locationId, string transactionId, CreateRefundRequest payload) returns CreateRefundResponse|error
CreateRefund
Parameters
- locationId string - The ID of the original transaction's associated location.
- transactionId string - The ID of the original transaction that includes the tender to refund.
- payload CreateRefundRequest - An object containing the fields to POST for the request.
Return Type
- CreateRefundResponse|error - Success
voidTransaction
function voidTransaction(string locationId, string transactionId) returns VoidTransactionResponse|error
VoidTransaction
Return Type
- VoidTransactionResponse|error - Success
createLoyaltyAccount
function createLoyaltyAccount(CreateLoyaltyAccountRequest payload) returns CreateLoyaltyAccountResponse|error
CreateLoyaltyAccount
Parameters
- payload CreateLoyaltyAccountRequest - An object containing the fields to POST for the request.
Return Type
- CreateLoyaltyAccountResponse|error - Success
searchLoyaltyAccounts
function searchLoyaltyAccounts(SearchLoyaltyAccountsRequest payload) returns SearchLoyaltyAccountsResponse|error
SearchLoyaltyAccounts
Parameters
- payload SearchLoyaltyAccountsRequest - An object containing the fields to POST for the request.
Return Type
- SearchLoyaltyAccountsResponse|error - Success
retrieveLoyaltyAccount
function retrieveLoyaltyAccount(string accountId) returns RetrieveLoyaltyAccountResponse|error
RetrieveLoyaltyAccount
Parameters
- accountId string - The ID of the loyalty account to retrieve.
Return Type
- RetrieveLoyaltyAccountResponse|error - Success
accumulateLoyaltyPoints
function accumulateLoyaltyPoints(string accountId, AccumulateLoyaltyPointsRequest payload) returns AccumulateLoyaltyPointsResponse|error
AccumulateLoyaltyPoints
Parameters
- accountId string - The loyalty account ID to which to add the points.
- payload AccumulateLoyaltyPointsRequest - An object containing the fields to POST for the request.
Return Type
- AccumulateLoyaltyPointsResponse|error - Success
adjustLoyaltyPoints
function adjustLoyaltyPoints(string accountId, AdjustLoyaltyPointsRequest payload) returns AdjustLoyaltyPointsResponse|error
AdjustLoyaltyPoints
Parameters
- accountId string - The ID of the loyalty account in which to adjust the points.
- payload AdjustLoyaltyPointsRequest - An object containing the fields to POST for the request.
Return Type
- AdjustLoyaltyPointsResponse|error - Success
searchLoyaltyEvents
function searchLoyaltyEvents(SearchLoyaltyEventsRequest payload) returns SearchLoyaltyEventsResponse|error
SearchLoyaltyEvents
Parameters
- payload SearchLoyaltyEventsRequest - An object containing the fields to POST for the request.
Return Type
- SearchLoyaltyEventsResponse|error - Success
listLoyaltyPrograms
function listLoyaltyPrograms() returns ListLoyaltyProgramsResponse|error
ListLoyaltyPrograms
Return Type
- ListLoyaltyProgramsResponse|error - Success
retrieveLoyaltyProgram
function retrieveLoyaltyProgram(string programId) returns RetrieveLoyaltyProgramResponse|error
RetrieveLoyaltyProgram
Parameters
- programId string - The ID of the loyalty program or the keyword
main
. Either value can be used to retrieve the single loyalty program that belongs to the seller.
Return Type
- RetrieveLoyaltyProgramResponse|error - Success
calculateLoyaltyPoints
function calculateLoyaltyPoints(string programId, CalculateLoyaltyPointsRequest payload) returns CalculateLoyaltyPointsResponse|error
CalculateLoyaltyPoints
Parameters
- programId string - The loyalty program ID, which defines the rules for accruing points.
- payload CalculateLoyaltyPointsRequest - An object containing the fields to POST for the request.
Return Type
- CalculateLoyaltyPointsResponse|error - Success
createLoyaltyReward
function createLoyaltyReward(CreateLoyaltyRewardRequest payload) returns CreateLoyaltyRewardResponse|error
CreateLoyaltyReward
Parameters
- payload CreateLoyaltyRewardRequest - An object containing the fields to POST for the request.
Return Type
- CreateLoyaltyRewardResponse|error - Success
searchLoyaltyRewards
function searchLoyaltyRewards(SearchLoyaltyRewardsRequest payload) returns SearchLoyaltyRewardsResponse|error
SearchLoyaltyRewards
Parameters
- payload SearchLoyaltyRewardsRequest - An object containing the fields to POST for the request.
Return Type
- SearchLoyaltyRewardsResponse|error - Success
retrieveLoyaltyReward
function retrieveLoyaltyReward(string rewardId) returns RetrieveLoyaltyRewardResponse|error
RetrieveLoyaltyReward
Parameters
- rewardId string - The ID of the loyalty reward to retrieve.
Return Type
- RetrieveLoyaltyRewardResponse|error - Success
deleteLoyaltyReward
function deleteLoyaltyReward(string rewardId) returns DeleteLoyaltyRewardResponse|error
DeleteLoyaltyReward
Parameters
- rewardId string - The ID of the loyalty reward to delete.
Return Type
- DeleteLoyaltyRewardResponse|error - Success
redeemLoyaltyReward
function redeemLoyaltyReward(string rewardId, RedeemLoyaltyRewardRequest payload) returns RedeemLoyaltyRewardResponse|error
RedeemLoyaltyReward
Parameters
- rewardId string - The ID of the loyalty reward to redeem.
- payload RedeemLoyaltyRewardRequest - An object containing the fields to POST for the request.
Return Type
- RedeemLoyaltyRewardResponse|error - Success
listMerchants
function listMerchants(int? cursor) returns ListMerchantsResponse|error
ListMerchants
Parameters
- cursor int? (default ()) - The cursor generated by the previous response.
Return Type
- ListMerchantsResponse|error - Success
retrieveMerchant
function retrieveMerchant(string merchantId) returns RetrieveMerchantResponse|error
RetrieveMerchant
Parameters
- merchantId string - The ID of the merchant to retrieve. If the string "me" is supplied as the ID, then retrieve the merchant that is currently accessible to this call.
Return Type
- RetrieveMerchantResponse|error - Success
createOrder
function createOrder(CreateOrderRequest payload) returns CreateOrderResponse|error
CreateOrder
Parameters
- payload CreateOrderRequest - An object containing the fields to POST for the request.
Return Type
- CreateOrderResponse|error - Success
batchRetrieveOrders
function batchRetrieveOrders(BatchRetrieveOrdersRequest payload) returns BatchRetrieveOrdersResponse|error
BatchRetrieveOrders
Parameters
- payload BatchRetrieveOrdersRequest - An object containing the fields to POST for the request.
Return Type
- BatchRetrieveOrdersResponse|error - Success
calculateOrder
function calculateOrder(CalculateOrderRequest payload) returns CalculateOrderResponse|error
CalculateOrder
Parameters
- payload CalculateOrderRequest - An object containing the fields to POST for the request.
Return Type
- CalculateOrderResponse|error - Success
searchOrders
function searchOrders(SearchOrdersRequest payload) returns SearchOrdersResponse|error
SearchOrders
Parameters
- payload SearchOrdersRequest - An object containing the fields to POST for the request.
Return Type
- SearchOrdersResponse|error - Success
getOrderById
function getOrderById(string orderId) returns RetrieveOrderResponse|error
RetrieveOrder
Parameters
- orderId string - The ID of the order to retrieve.
Return Type
- RetrieveOrderResponse|error - Success
updateOrderById
function updateOrderById(string orderId, UpdateOrderRequest payload) returns UpdateOrderResponse|error
UpdateOrder
Parameters
- orderId string - The ID of the order to update.
- payload UpdateOrderRequest - An object containing the fields to POST for the request.
Return Type
- UpdateOrderResponse|error - Success
payOrder
function payOrder(string orderId, PayOrderRequest payload) returns PayOrderResponse|error
PayOrder
Parameters
- orderId string - The ID of the order being paid.
- payload PayOrderRequest - An object containing the fields to POST for the request.
Return Type
- PayOrderResponse|error - Success
getPayments
function getPayments(string? beginTime, string? endTime, string? sortOrder, string? cursor, string? locationId, int? total, string? last4, string? cardBrand, int? 'limit) returns ListPaymentsResponse|error
ListPayments
Parameters
- beginTime string? (default ()) - The timestamp for the beginning of the reporting period, in RFC 3339 format. Inclusive. Default: The current time minus one year.
- endTime string? (default ()) - The timestamp for the end of the reporting period, in RFC 3339 format. Default: The current time.
- sortOrder string? (default ()) - The order in which results are listed: -
ASC
- Oldest to newest. -DESC
- Newest to oldest (default).
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see Pagination.
- locationId string? (default ()) - Limit results to the location supplied. By default, results are returned for the default (main) location associated with the seller.
- total int? (default ()) - The exact amount in the
total_money
for a payment.
- last4 string? (default ()) - The last four digits of a payment card.
- cardBrand string? (default ()) - The brand of the payment card (for example, VISA).
- 'limit int? (default ()) - The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. The default value of 100 is also the maximum allowed value. If the provided value is greater than 100, it is ignored and the default value is used instead. Default:
100
Return Type
- ListPaymentsResponse|error - Success
createPayment
function createPayment(CreatePaymentRequest payload) returns CreatePaymentResponse|error
CreatePayment
Parameters
- payload CreatePaymentRequest - An object containing the fields to POST for the request.
Return Type
- CreatePaymentResponse|error - Success
cancelPaymentByIdempotencyKey
function cancelPaymentByIdempotencyKey(CancelPaymentByIdempotencyKeyRequest payload) returns CancelPaymentByIdempotencyKeyResponse|error
CancelPaymentByIdempotencyKey
Parameters
- payload CancelPaymentByIdempotencyKeyRequest - An object containing the fields to POST for the request.
Return Type
- CancelPaymentByIdempotencyKeyResponse|error - Success
getPayment
function getPayment(string paymentId) returns GetPaymentResponse|error
GetPayment
Parameters
- paymentId string - A unique ID for the desired payment.
Return Type
- GetPaymentResponse|error - Success
updatePayment
function updatePayment(string paymentId, UpdatePaymentRequest payload) returns UpdatePaymentResponse|error
UpdatePayment
Parameters
- paymentId string - The ID of the payment to update.
- payload UpdatePaymentRequest - An object containing the fields to POST for the request.
Return Type
- UpdatePaymentResponse|error - Success
cancelPayment
function cancelPayment(string paymentId) returns CancelPaymentResponse|error
CancelPayment
Parameters
- paymentId string - The ID of the payment to cancel.
Return Type
- CancelPaymentResponse|error - Success
completePayment
function completePayment(string paymentId) returns CompletePaymentResponse|error
CompletePayment
Parameters
- paymentId string - The unique ID identifying the payment to be completed.
Return Type
- CompletePaymentResponse|error - Success
listPaymentRefunds
function listPaymentRefunds(string? beginTime, string? endTime, string? sortOrder, string? cursor, string? locationId, string? status, string? sourceType, int? 'limit) returns ListPaymentRefundsResponse|error
ListPaymentRefunds
Parameters
- beginTime string? (default ()) - The timestamp for the beginning of the requested reporting period, in RFC 3339 format. Default: The current time minus one year.
- endTime string? (default ()) - The timestamp for the end of the requested reporting period, in RFC 3339 format. Default: The current time.
- sortOrder string? (default ()) - The order in which results are listed: -
ASC
- Oldest to newest. -DESC
- Newest to oldest (default).
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see Pagination.
- locationId string? (default ()) - Limit results to the location supplied. By default, results are returned for all locations associated with the seller.
- status string? (default ()) - If provided, only refunds with the given status are returned. For a list of refund status values, see PaymentRefund. Default: If omitted, refunds are returned regardless of their status.
- sourceType string? (default ()) - If provided, only refunds with the given source type are returned. -
CARD
- List refunds only for payments whereCARD
was specified as the payment source. Default: If omitted, refunds are returned regardless of the source type.
- 'limit int? (default ()) - The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. If the supplied value is greater than 100, no more than 100 results are returned. Default: 100
Return Type
- ListPaymentRefundsResponse|error - Success
refundPayment
function refundPayment(RefundPaymentRequest payload) returns RefundPaymentResponse|error
RefundPayment
Parameters
- payload RefundPaymentRequest - An object containing the fields to POST for the request.
Return Type
- RefundPaymentResponse|error - Success
getPaymentRefund
function getPaymentRefund(string refundId) returns GetPaymentRefundResponse|error
GetPaymentRefund
Parameters
- refundId string - The unique ID for the desired
PaymentRefund
.
Return Type
- GetPaymentRefundResponse|error - Success
listSites
function listSites() returns ListSitesResponse|error
ListSites
Return Type
- ListSitesResponse|error - Success
retrieveSnippet
function retrieveSnippet(string siteId) returns RetrieveSnippetResponse|error
RetrieveSnippet
Parameters
- siteId string - The ID of the site that contains the snippet.
Return Type
- RetrieveSnippetResponse|error - Success
upsertSnippet
function upsertSnippet(string siteId, UpsertSnippetRequest payload) returns UpsertSnippetResponse|error
UpsertSnippet
Parameters
- siteId string - The ID of the site where you want to add or update the snippet.
- payload UpsertSnippetRequest - An object containing the fields to POST for the request.
Return Type
- UpsertSnippetResponse|error - Success
deleteSnippet
function deleteSnippet(string siteId) returns DeleteSnippetResponse|error
DeleteSnippet
Parameters
- siteId string - The ID of the site that contains the snippet.
Return Type
- DeleteSnippetResponse|error - Success
createSubscription
function createSubscription(CreateSubscriptionRequest payload) returns CreateSubscriptionResponse|error
CreateSubscription
Parameters
- payload CreateSubscriptionRequest - An object containing the fields to POST for the request.
Return Type
- CreateSubscriptionResponse|error - Success
searchSubscriptions
function searchSubscriptions(SearchSubscriptionsRequest payload) returns SearchSubscriptionsResponse|error
SearchSubscriptions
Parameters
- payload SearchSubscriptionsRequest - An object containing the fields to POST for the request.
Return Type
- SearchSubscriptionsResponse|error - Success
retrieveSubscription
function retrieveSubscription(string subscriptionId) returns RetrieveSubscriptionResponse|error
RetrieveSubscription
Parameters
- subscriptionId string - The ID of the subscription to retrieve.
Return Type
- RetrieveSubscriptionResponse|error - Success
updateSubscription
function updateSubscription(string subscriptionId, UpdateSubscriptionRequest payload) returns UpdateSubscriptionResponse|error
UpdateSubscription
Parameters
- subscriptionId string - The ID for the subscription to update.
- payload UpdateSubscriptionRequest - An object containing the fields to POST for the request.
Return Type
- UpdateSubscriptionResponse|error - Success
cancelSubscription
function cancelSubscription(string subscriptionId) returns CancelSubscriptionResponse|error
CancelSubscription
Parameters
- subscriptionId string - The ID of the subscription to cancel.
Return Type
- CancelSubscriptionResponse|error - Success
listSubscriptionEvents
function listSubscriptionEvents(string subscriptionId, string? cursor, int? 'limit) returns ListSubscriptionEventsResponse|error
ListSubscriptionEvents
Parameters
- subscriptionId string - The ID of the subscription to retrieve the events for.
- cursor string? (default ()) - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. For more information, see Pagination.
- 'limit int? (default ()) - The upper limit on the number of subscription events to return in the response. Default:
200
Return Type
- ListSubscriptionEventsResponse|error - Success
resumeSubscription
function resumeSubscription(string subscriptionId) returns ResumeSubscriptionResponse|error
ResumeSubscription
Parameters
- subscriptionId string - The ID of the subscription to resume.
Return Type
- ResumeSubscriptionResponse|error - Success
createTeamMember
function createTeamMember(CreateTeamMemberRequest payload) returns CreateTeamMemberResponse|error
CreateTeamMember
Parameters
- payload CreateTeamMemberRequest - An object containing the fields to POST for the request.
Return Type
- CreateTeamMemberResponse|error - Success
bulkCreateTeamMembers
function bulkCreateTeamMembers(BulkCreateTeamMembersRequest payload) returns BulkCreateTeamMembersResponse|error
BulkCreateTeamMembers
Parameters
- payload BulkCreateTeamMembersRequest - An object containing the fields to POST for the request.
Return Type
- BulkCreateTeamMembersResponse|error - Success
bulkUpdateTeamMembers
function bulkUpdateTeamMembers(BulkUpdateTeamMembersRequest payload) returns BulkUpdateTeamMembersResponse|error
BulkUpdateTeamMembers
Parameters
- payload BulkUpdateTeamMembersRequest - An object containing the fields to POST for the request.
Return Type
- BulkUpdateTeamMembersResponse|error - Success
searchTeamMembers
function searchTeamMembers(SearchTeamMembersRequest payload) returns SearchTeamMembersResponse|error
SearchTeamMembers
Parameters
- payload SearchTeamMembersRequest - An object containing the fields to POST for the request.
Return Type
- SearchTeamMembersResponse|error - Success
retrieveTeamMember
function retrieveTeamMember(string teamMemberId) returns RetrieveTeamMemberResponse|error
RetrieveTeamMember
Parameters
- teamMemberId string - The ID of the team member to retrieve.
Return Type
- RetrieveTeamMemberResponse|error - Success
updateTeamMember
function updateTeamMember(string teamMemberId, UpdateTeamMemberRequest payload) returns UpdateTeamMemberResponse|error
UpdateTeamMember
Parameters
- teamMemberId string - The ID of the team member to update.
- payload UpdateTeamMemberRequest - An object containing the fields to POST for the request.
Return Type
- UpdateTeamMemberResponse|error - Success
retrieveWageSetting
function retrieveWageSetting(string teamMemberId) returns RetrieveWageSettingResponse|error
RetrieveWageSetting
Parameters
- teamMemberId string - The ID of the team member for which to retrieve the wage setting.
Return Type
- RetrieveWageSettingResponse|error - Success
updateWageSetting
function updateWageSetting(string teamMemberId, UpdateWageSettingRequest payload) returns UpdateWageSettingResponse|error
UpdateWageSetting
Parameters
- teamMemberId string - The ID of the team member for which to update the
WageSetting
object.
- payload UpdateWageSettingRequest - An object containing the fields to POST for the request.
Return Type
- UpdateWageSettingResponse|error - Success
createTerminalCheckout
function createTerminalCheckout(CreateTerminalCheckoutRequest payload) returns CreateTerminalCheckoutResponse|error
CreateTerminalCheckout
Parameters
- payload CreateTerminalCheckoutRequest - An object containing the fields to POST for the request.
Return Type
- CreateTerminalCheckoutResponse|error - Success
searchTerminalCheckouts
function searchTerminalCheckouts(SearchTerminalCheckoutsRequest payload) returns SearchTerminalCheckoutsResponse|error
SearchTerminalCheckouts
Parameters
- payload SearchTerminalCheckoutsRequest - An object containing the fields to POST for the request.
Return Type
- SearchTerminalCheckoutsResponse|error - Success
getTerminalCheckout
function getTerminalCheckout(string checkoutId) returns GetTerminalCheckoutResponse|error
GetTerminalCheckout
Parameters
- checkoutId string - The unique ID for the desired
TerminalCheckout
.
Return Type
- GetTerminalCheckoutResponse|error - Success
cancelTerminalCheckout
function cancelTerminalCheckout(string checkoutId) returns CancelTerminalCheckoutResponse|error
CancelTerminalCheckout
Parameters
- checkoutId string - The unique ID for the desired
TerminalCheckout
.
Return Type
- CancelTerminalCheckoutResponse|error - Success
createTerminalRefund
function createTerminalRefund(CreateTerminalRefundRequest payload) returns CreateTerminalRefundResponse|error
CreateTerminalRefund
Parameters
- payload CreateTerminalRefundRequest - An object containing the fields to POST for the request.
Return Type
- CreateTerminalRefundResponse|error - Success
searchTerminalRefunds
function searchTerminalRefunds(SearchTerminalRefundsRequest payload) returns SearchTerminalRefundsResponse|error
SearchTerminalRefunds
Parameters
- payload SearchTerminalRefundsRequest - An object containing the fields to POST for the request.
Return Type
- SearchTerminalRefundsResponse|error - Success
getTerminalRefund
function getTerminalRefund(string terminalRefundId) returns GetTerminalRefundResponse|error
GetTerminalRefund
Parameters
- terminalRefundId string - The unique ID for the desired
TerminalRefund
.
Return Type
- GetTerminalRefundResponse|error - Success
cancelTerminalRefund
function cancelTerminalRefund(string terminalRefundId) returns CancelTerminalRefundResponse|error
CancelTerminalRefund
Parameters
- terminalRefundId string - The unique ID for the desired
TerminalRefund
.
Return Type
- CancelTerminalRefundResponse|error - Success
Records
squareup: AcceptDisputeRequest
Defines the request parameters for the AcceptDispute
endpoint.
squareup: AcceptDisputeResponse
Defines the fields in an AcceptDispute
response.
Fields
- dispute Dispute? - Represents a dispute a cardholder initiated with their bank.
- errors Error[]? - Information about errors encountered during the request.
squareup: AccumulateLoyaltyPointsRequest
A request to accumulate points for a purchase.
Fields
- accumulate_points LoyaltyEventAccumulatePoints - Provides metadata when the event
type
isACCUMULATE_POINTS
.
- idempotency_key string - A unique string that identifies the
AccumulateLoyaltyPoints
request. Keys can be any valid string but must be unique for every request.
squareup: AccumulateLoyaltyPointsResponse
A response containing the resulting loyalty event.
Fields
- errors Error[]? - Any errors that occurred during the request.
- event LoyaltyEvent? - Provides information about a loyalty event. For more information, see Loyalty events.
squareup: ACHDetails
ACH-specific details about BANK_ACCOUNT
type payments with the transfer_type
of ACH
.
Fields
- account_number_suffix string? - The last few digits of the bank account number.
- account_type string? - The type of the bank account performing the transfer. The account type can be
CHECKING
,SAVINGS
, orUNKNOWN
.
- routing_number string? - The routing number for the bank account.
squareup: AddGroupToCustomerRequest
Defines the fields that are included in the request body of a request to the AddGroupToCustomer endpoint.
squareup: AddGroupToCustomerResponse
Defines the fields that are included in the response body of a request to the AddGroupToCustomer endpoint.
Fields
- errors Error[]? - Any errors that occurred during the request.
squareup: AdditionalRecipient
Represents an additional recipient (other than the merchant) receiving a portion of this tender.
Fields
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- description string? - The description of the additional recipient.
- location_id string - The location ID for a recipient (other than the merchant) receiving a portion of this tender.
- receivable_id string? - The unique ID for this AdditionalRecipientReceivable, assigned by the server.
squareup: Address
Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them.
For example, sales tax software may charge different amounts of sales tax
based on the postal code, and some software is only available in
certain states due to compliance reasons.
For the remaining address components, the Address
type provides the
address_line_1
and address_line_2
fields for free-form data entry.
These fields are free-form because the remaining address components have
too many variations around the world and typical software does not parse
these components. These fields enable users to enter anything they want.
Note that, in the current implementation, all other Address
type fields are blank.
These include address_line_3
, sublocality_2
, sublocality_3
,
administrative_district_level_2
, administrative_district_level_3
,
first_name
, last_name
, and organization
.
When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
Fields
- address_line_1 string? - The first line of the address.
Fields that start with
address_line
provide the address's most specific details, like street number, street name, and building name. They do not provide less specific details like city, state/province, or country (these details are provided in other fields).
- address_line_2 string? - The second line of the address, if any.
- address_line_3 string? - The third line of the address, if any.
- administrative_district_level_1 string? - A civil entity within the address's country. In the US, this is the state.
- administrative_district_level_2 string? - A civil entity within the address's
administrative_district_level_1
. In the US, this is the county.
- administrative_district_level_3 string? - A civil entity within the address's
administrative_district_level_2
, if any.
- country string? - The address's country, in ISO 3166-1-alpha-2 format.
- first_name string? - Optional first name when it's representing recipient.
- last_name string? - Optional last name when it's representing recipient.
- locality string? - The city or town of the address.
- organization string? - Optional organization name when it's representing recipient.
- postal_code string? - The address's postal code.
- sublocality string? - A civil region within the address's
locality
, if any.
- sublocality_2 string? - A civil region within the address's
sublocality
, if any.
- sublocality_3 string? - A civil region within the address's
sublocality_2
, if any.
squareup: AdjustLoyaltyPointsRequest
A request to adjust (add or subtract) points manually.
Fields
- adjust_points LoyaltyEventAdjustPoints - Provides metadata when the event
type
isADJUST_POINTS
.
- idempotency_key string - A unique string that identifies this
AdjustLoyaltyPoints
request. Keys can be any valid string, but must be unique for every request.
squareup: AdjustLoyaltyPointsResponse
A response that includes the loyalty event that resulted from the successful API call.
Fields
- errors Error[]? - Any errors that occurred during the request.
- event LoyaltyEvent? - Provides information about a loyalty event. For more information, see Loyalty events.
squareup: ApiKeysConfig
Provides API key configurations needed when communicating with a remote HTTP endpoint.
Fields
- authorization string - Represents API key
Authorization
squareup: AppointmentSegment
Defines an appointment segment of a booking.
Fields
- duration_minutes int - The time span in minutes of an appointment segment.
- service_variation_id string - The ID of the CatalogItemVariation object representing the service booked in this segment.
- service_variation_version int - The current version of the item variation representing the service booked in this segment.
- team_member_id string - The ID of the TeamMember object representing the team member booked in this segment.
squareup: Availability
Describes a slot available for booking, encapsulating appointment segments, the location and starting time.
Fields
- appointment_segments AppointmentSegment[]? - The list of appointment segments available for booking
- location_id string? - The ID of the location available for booking.
- start_at string? - The RFC 3339 timestamp specifying the beginning time of the slot available for booking.
squareup: BankAccount
Represents a bank account. For more information about linking a bank account to a Square account, see Bank Accounts API.
Fields
- account_number_suffix string - The last few digits of the account number.
- account_type string - The financial purpose of the associated bank account.
- bank_name string? - Read only. Name of actual financial institution. For example "Bank of America".
- country string - The ISO 3166 Alpha-2 country code where the bank account is based.
- creditable boolean - Indicates whether it is possible for Square to send money to this bank account.
- currency string - The 3-character ISO 4217 currency code indicating the operating
currency of the bank account. For example, the currency code for US dollars
is
USD
.
- debit_mandate_reference_id string? - Reference identifier that will be displayed to UK bank account owners when collecting direct debit authorization. Only required for UK bank accounts.
- debitable boolean - Indicates whether it is possible for Square to take money from this bank account.
- fingerprint string? - A Square-assigned, unique identifier for the bank account based on the account information. The account fingerprint can be used to compare account entries and determine if the they represent the same real-world bank account.
- holder_name string - Name of the account holder. This name must match the name on the targeted bank account record.
- id string - The unique, Square-issued identifier for the bank account.
- location_id string? - The location to which the bank account belongs.
- primary_bank_identification_number string - Primary identifier for the bank. For more information, see Bank Accounts API.
- reference_id string? - Client-provided identifier for linking the banking account to an entity in a third-party system (for example, a bank account number or a user identifier).
- secondary_bank_identification_number string? - Secondary identifier for the bank. For more information, see Bank Accounts API.
- status string - Read-only. The current verification status of this BankAccount object.
- 'version int? - The current version of the
BankAccount
.
squareup: BankAccountPaymentDetails
Additional details about BANK_ACCOUNT type payments.
Fields
- account_ownership_type string? - The ownership type of the bank account performing the transfer.
The type can be
INDIVIDUAL
,COMPANY
, orUNKNOWN
.
- ach_details ACHDetails? - ACH-specific details about
BANK_ACCOUNT
type payments with thetransfer_type
ofACH
.
- bank_name string? - The name of the bank associated with the bank account.
- country string? - The two-letter ISO code representing the country the bank account is located in.
- errors Error[]? - Information about errors encountered during the request.
- fingerprint string? - Uniquely identifies the bank account for this seller and can be used to determine if payments are from the same bank account.
- statement_description string? - The statement description as sent to the bank.
- transfer_type string? - The type of the bank transfer. The type can be
ACH
orUNKNOWN
.
squareup: BatchChangeInventoryRequest
Fields
- changes InventoryChange[]? - The set of physical counts and inventory adjustments to be made. Changes are applied based on the client-supplied timestamp and may be sent out of order.
- idempotency_key string - A client-supplied, universally unique identifier (UUID) for the request. See Idempotency in the API Development 101 section for more information.
- ignore_unchanged_counts boolean? - Indicates whether the current physical count should be ignored if
the quantity is unchanged since the last physical count. Default:
true
.
squareup: BatchChangeInventoryResponse
Fields
- changes InventoryChange[]? - Changes created for the request.
- counts InventoryCount[]? - The current counts for all objects referenced in the request.
- errors Error[]? - Any errors that occurred during the request.
squareup: BatchDeleteCatalogObjectsRequest
Fields
- object_ids string[]? - The IDs of the CatalogObjects to be deleted. When an object is deleted, other objects in the graph that depend on that object will be deleted as well (for example, deleting a CatalogItem will delete its CatalogItemVariation.
squareup: BatchDeleteCatalogObjectsResponse
Fields
- deleted_object_ids string[]? - The IDs of all CatalogObjects deleted by this request.
- errors Error[]? - Any errors that occurred during the request.
squareup: BatchRetrieveCatalogObjectsRequest
Fields
- catalog_version int? - The specific version of the catalog objects to be included in the response.
This allows you to retrieve historical versions of objects. The specified version value is matched against
the CatalogObjects'
version
attribute.
- include_related_objects boolean? - If
true
, the response will include additional objects that are related to the requested objects, as follows: If theobjects
field of the response contains a CatalogItem, its associated CatalogCategory objects, CatalogTax objects, CatalogImage objects and CatalogModifierLists will be returned in therelated_objects
field of the response. If theobjects
field of the response contains a CatalogItemVariation, its parent CatalogItem will be returned in therelated_objects
field of the response.
- object_ids string[] - The IDs of the CatalogObjects to be retrieved.
squareup: BatchRetrieveCatalogObjectsResponse
Fields
- errors Error[]? - Any errors that occurred during the request.
- objects CatalogObject[]? - A list of CatalogObjects returned.
- related_objects CatalogObject[]? - A list of CatalogObjects referenced by the object in the
objects
field.
squareup: BatchRetrieveInventoryChangesRequest
Fields
- catalog_object_ids string[]? - The filter to return results by
CatalogObject
ID. The filter is only applicable when set. The default value is null.
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See the Pagination guide for more information.
- location_ids string[]? - The filter to return results by
Location
ID. The filter is only applicable when set. The default value is null.
- states string[]? - The filter to return
ADJUSTMENT
query results byInventoryState
. This filter is only applied when set. The default value is null.
- types string[]? - The filter to return results by
InventoryChangeType
values other thanTRANSFER
. The default value is[PHYSICAL_COUNT, ADJUSTMENT]
.
- updated_after string? - The filter to return results with their
calculated_at
value
after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (1970-01-01T00:00:00Z
).
- updated_before string? - The filter to return results with their
created_at
orcalculated_at
value
strictly before the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (1970-01-01T00:00:00Z
).
squareup: BatchRetrieveInventoryChangesResponse
Fields
- changes InventoryChange[]? - The current calculated inventory changes for the requested objects and locations.
- cursor string? - The pagination cursor to be used in a subsequent request. If unset, this is the final response. See the Pagination guide for more information.
- errors Error[]? - Any errors that occurred during the request.
squareup: BatchRetrieveInventoryCountsRequest
Fields
- catalog_object_ids string[]? - The filter to return results by
CatalogObject
ID. The filter is applicable only when set. The default is null.
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See the Pagination guide for more information.
- location_ids string[]? - The filter to return results by
Location
ID. This filter is applicable only when set. The default is null.
- states string[]? - The filter to return results by
InventoryState
. The filter is only applicable when set. Ignored are untracked states ofNONE
,SOLD
, andUNLINKED_RETURN
. The default is null.
- updated_after string? - The filter to return results with their
calculated_at
value after the given time as specified in an RFC 3339 timestamp. The default value is the UNIX epoch of (1970-01-01T00:00:00Z
).
squareup: BatchRetrieveInventoryCountsResponse
Fields
- counts InventoryCount[]? - The current calculated inventory counts for the requested objects and locations.
- cursor string? - The pagination cursor to be used in a subsequent request. If unset, this is the final response. See the Pagination guide for more information.
- errors Error[]? - Any errors that occurred during the request.
squareup: BatchRetrieveOrdersRequest
Defines the fields that are included in requests to the
BatchRetrieveOrders
endpoint.
Fields
- location_id string? - The ID of the location for these orders. This field is optional: omit it to retrieve orders within the scope of the current authorization's merchant ID.
- order_ids BatchretrieveordersrequestOrderidsItemsString[] - The IDs of the orders to retrieve. A maximum of 100 orders can be retrieved per request.
squareup: BatchRetrieveOrdersResponse
Defines the fields that are included in the response body of
a request to the BatchRetrieveOrders
endpoint.
Fields
- errors Error[]? - Any errors that occurred during the request.
- orders Order[]? - The requested orders. This will omit any requested orders that do not exist.
squareup: BatchUpsertCatalogObjectsRequest
Fields
- batches CatalogObjectBatch[] - A batch of CatalogObjects to be inserted/updated atomically.
The objects within a batch will be inserted in an all-or-nothing fashion, i.e., if an error occurs
attempting to insert or update an object within a batch, the entire batch will be rejected. However, an error
in one batch will not affect other batches within the same request.
For each object, its
updated_at
field is ignored and replaced with a current timestamp, and itsis_deleted
field must not be set totrue
. To modify an existing object, supply its ID. To create a new object, use an ID starting with#
. These IDs may be used to create relationships between an object and attributes of other objects that reference it. For example, you can create a CatalogItem with ID#ABC
and a CatalogItemVariation with itsitem_id
attribute set to#ABC
in order to associate the CatalogItemVariation with its parent CatalogItem. Any#
-prefixed IDs are valid only within a single atomic batch, and will be replaced by server-generated IDs. Each batch may contain up to 1,000 objects. The total number of objects across all batches for a single request may not exceed 10,000. If either of these limits is violated, an error will be returned and no objects will be inserted or updated.
- idempotency_key string - A value you specify that uniquely identifies this request among all your requests. A common way to create a valid idempotency key is to use a Universally unique identifier (UUID). If you're unsure whether a particular request was successful, you can reattempt it with the same idempotency key without worrying about creating duplicate objects. See Idempotency for more information.
squareup: BatchUpsertCatalogObjectsResponse
Fields
- errors Error[]? - Any errors that occurred during the request.
- id_mappings CatalogIdMapping[]? - The mapping between client and server IDs for this upsert.
- objects CatalogObject[]? - The created successfully created CatalogObjects.
squareup: 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.
Fields
- appointment_segments AppointmentSegment[]? - A list of appointment segments for this booking.
- created_at string? - The timestamp specifying the creation time of this booking, in RFC 3339 format.
- customer_note string? - The free-text field for the customer to supply notes about the booking. For example, the note can be preferences that cannot be expressed by supported attributes of a relevant CatalogObject instance.
- id string? - A unique ID of this object representing a booking.
- seller_note string? - The free-text field for the seller to supply notes about the booking. For example, the note can be preferences that cannot be expressed by supported attributes of a specific CatalogObject instance. This field should not be visible to customers.
- start_at string? - The timestamp specifying the starting time of this booking, in RFC 3339 format.
- status string? - The status of the booking, describing where the booking stands with respect to the booking state machine.
- updated_at string? - The timestamp specifying the most recent update time of this booking, in RFC 3339 format.
- 'version int? - The revision number for the booking used for optimistic concurrency.
squareup: Break
A record of an employee's break during a shift.
Fields
- break_type_id string - The
BreakType
that thisBreak
was templated on.
- end_at string? - RFC 3339; follows the same timezone information as
Shift
. Precision up to the minute is respected; seconds are truncated.
- expected_duration string - Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of the break.
- id string? - The UUID for this object.
- is_paid boolean - Whether this break counts towards time worked for compensation purposes.
- name string - A human-readable name.
- start_at string - RFC 3339; follows the same timezone information as
Shift
. Precision up to the minute is respected; seconds are truncated.
squareup: BreakType
A defined break template that sets an expectation for possible Break
instances on a Shift
.
Fields
- break_name string - A human-readable name for this type of break. The name is displayed to employees in Square products.
- created_at string? - A read-only timestamp in RFC 3339 format.
- expected_duration string - Format: RFC-3339 P[n]Y[n]M[n]DT[n]H[n]M[n]S. The expected length of this break. Precision less than minutes is truncated.
- id string? - The UUID for this object.
- is_paid boolean - Whether this break counts towards time worked for compensation purposes.
- location_id string - The ID of the business location this type of break applies to.
- updated_at string? - A read-only timestamp in RFC 3339 format.
- 'version int? - Used for resolving concurrency issues. The request fails if the version provided does not match the server version at the time of the request. If a value is not provided, Square's servers execute a "blind" write; potentially overwriting another writer's data.
squareup: BulkCreateTeamMembersRequest
Represents a bulk create request for TeamMember
objects.
Fields
- team_members record {} - The data used to create the
TeamMember
objects. Each key is theidempotency_key
that maps to theCreateTeamMemberRequest
.
squareup: BulkCreateTeamMembersResponse
Represents a response from a bulk create request containing the created TeamMember
objects or error messages.
Fields
- errors Error[]? - The errors that occurred during the request.
- team_members record {}? - The successfully created
TeamMember
objects. Each key is theidempotency_key
that maps to theCreateTeamMemberRequest
.
squareup: BulkUpdateTeamMembersRequest
Represents a bulk update request for TeamMember
objects.
Fields
- team_members record {} - The data used to update the
TeamMember
objects. Each key is theteam_member_id
that maps to theUpdateTeamMemberRequest
.
squareup: BulkUpdateTeamMembersResponse
Represents a response from a bulk update request containing the updated TeamMember
objects or error messages.
Fields
- errors Error[]? - The errors that occurred during the request.
- team_members record {}? - The successfully updated
TeamMember
objects. Each key is theteam_member_id
that maps to theUpdateTeamMemberRequest
.
squareup: BusinessAppointmentSettings
The service appointment settings, including where and how the service is provided.
Fields
- alignment_time string? - The time unit of the service duration for bookings.
- any_team_member_booking_enabled boolean? - Indicates whether a customer can choose from all available time slots and have a staff member assigned
automatically (
true
) or not (false
).
- cancellation_fee_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- cancellation_policy string? - The cancellation policy adopted by the seller.
- cancellation_policy_text string? - The free-form text of the seller's cancellation policy.
- cancellation_window_seconds int? - The cut-off time in seconds for allowing clients to cancel or reschedule an appointment.
- location_types string[]? - Types of the location allowed for bookings.
- max_appointments_per_day_limit int? - The maximum number of daily appointments per team member or per location.
- max_appointments_per_day_limit_type string? - Indicates whether the daily appointment limit applies to team members or to business locations.
- max_booking_lead_time_seconds int? - The maximum lead time in seconds before a service can be booked. Bookings must be created at most this far ahead of the booking's starting time.
- min_booking_lead_time_seconds int? - The minimum lead time in seconds before a service can be booked. Bookings must be created at least this far ahead of the booking's starting time.
- multiple_service_booking_enabled boolean? - Indicates whether a customer can book multiple services in a single online booking.
- skip_booking_flow_staff_selection boolean? - Indicates whether customers has an assigned staff member (
true
) or can select s staff member of their choice (false
).
squareup: BusinessBookingProfile
Fields
- allow_user_cancel boolean? - Indicates whether customers can cancel or reschedule their own bookings (
true
) or not (false
).
- booking_enabled boolean? - Indicates whether the seller is open for booking.
- booking_policy string? - The policy for the seller to automatically accept booking requests (
ACCEPT_ALL
) or not (REQUIRES_ACCEPTANCE
).
- business_appointment_settings BusinessAppointmentSettings? - The service appointment settings, including where and how the service is provided.
- created_at string? - The RFC 3339 timestamp specifying the booking's creation time.
- customer_timezone_choice string? - The choice of customer's time zone information of a booking. The Square online booking site and all notifications to customers uses either the seller location’s time zone or the time zone the customer chooses at booking.
- seller_id string? - The ID of the seller, obtainable using the Merchants API.
squareup: BusinessHours
Represents the hours of operation for a business location.
Fields
- periods BusinessHoursPeriod[]? - The list of time periods during which the business is open. There may be at most 10 periods per day.
squareup: BusinessHoursPeriod
Represents a period of time during which a business location is open.
Fields
- day_of_week string? - The day of week for this time period.
- end_local_time string? - The end time of a business hours period, specified in local time using partial-time RFC 3339 format.
- start_local_time string? - The start time of a business hours period, specified in local time using partial-time RFC 3339 format.
squareup: CalculateLoyaltyPointsRequest
A request to calculate the points that a buyer can earn from a specified purchase.
Fields
- transaction_amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
squareup: CalculateLoyaltyPointsResponse
A response that includes the points that the buyer can earn from a specified purchase.
Fields
- errors Error[]? - Any errors that occurred during the request.
- points int? - The points that the buyer can earn from a specified purchase.
squareup: CalculateOrderRequest
Fields
- 'order Order - Contains all information related to a single order to process with Square,
including line items that specify the products to purchase.
Order
objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.
- proposed_rewards OrderReward[]? - Identifies one or more loyalty reward tiers to apply during the order calculation.
The discounts defined by the reward tiers are added to the order only to preview the
effect of applying the specified rewards. The rewards do not correspond to actual
redemptions; that is, no
reward
s are created. Therefore, the rewardid
s are random strings used only to reference the reward tier.
squareup: CalculateOrderResponse
Fields
- errors Error[]? - Any errors that occurred during the request.
- 'order Order? - Contains all information related to a single order to process with Square,
including line items that specify the products to purchase.
Order
objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.
squareup: CancelBookingRequest
Fields
- booking_version int? - The revision number for the booking used for optimistic concurrency.
- idempotency_key string? - A unique key to make this request an idempotent operation.
squareup: CancelBookingResponse
Fields
- booking 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.
- errors Error[]? - Any errors that occurred during the request.
squareup: CancelInvoiceRequest
Describes a CancelInvoice
request.
Fields
- 'version int - The version of the invoice to cancel. If you do not know the version, you can call GetInvoice or ListInvoices.
squareup: CancelInvoiceResponse
The response returned by the CancelInvoice
request.
Fields
- errors Error[]? - Information about errors encountered during the request.
- invoice Invoice? - Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see Manage Invoices Using the Invoices API.
squareup: CancelPaymentByIdempotencyKeyRequest
Describes a request to cancel a payment using CancelPaymentByIdempotencyKey.
Fields
- idempotency_key string - The
idempotency_key
identifying the payment to be canceled.
squareup: CancelPaymentByIdempotencyKeyResponse
Defines the response returned by
CancelPaymentByIdempotencyKey.
On success, errors
is empty.
Fields
- errors Error[]? - Any errors that occurred during the request.
squareup: CancelPaymentRequest
Describes the request to cancel (void) a payment using CancelPayment. You can only cancel a payment that is approved (not completed). For more information, see Delayed capture of a payment.
squareup: CancelPaymentResponse
Defines the response returned by CancelPayment.
Fields
- errors Error[]? - Information about errors encountered during the request.
- payment Payment? - Represents a payment processed by the Square API.
squareup: CancelSubscriptionRequest
Defines parameters in a CancelSubscription endpoint request.
squareup: CancelSubscriptionResponse
Defines fields that are included in a CancelSubscription response.
Fields
- errors Error[]? - Information about errors encountered during the request.
- subscription Subscription? - Represents a customer subscription to a subscription plan.
For an overview of the
Subscription
type, see Subscription object.
squareup: CancelTerminalCheckoutRequest
squareup: CancelTerminalCheckoutResponse
Fields
- checkout TerminalCheckout? -
- errors Error[]? - Information about errors encountered during the request.
squareup: CancelTerminalRefundRequest
squareup: CancelTerminalRefundResponse
Fields
- errors Error[]? - Information about errors encountered during the request.
- refund TerminalRefund? -
squareup: CaptureTransactionRequest
squareup: CaptureTransactionResponse
Defines the fields that are included in the response body of a request to the CaptureTransaction endpoint.
Fields
- errors Error[]? - Any errors that occurred during the request.
squareup: Card
Represents the payment details of a card to be used for payments. These details are determined by the payment token generated by Web Payments SDK.
Fields
- billing_address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- bin string? - The first six digits of the card number, known as the Bank Identification Number (BIN). Only the Payments API returns this field.
- card_brand string? - The card's brand.
- card_type string? - The type of the card. The Card object includes this field only in response to Payments API calls.
- cardholder_name string? - The name of the cardholder.
- customer_id string? - The ID of a customer created using the Customers API to be associated with the card.
- enabled boolean? - Indicates whether or not a card can be used for payments.
- exp_month int? - The expiration month of the associated card as an integer between 1 and 12.
- exp_year int? - The four-digit year of the card's expiration date.
- fingerprint string? - Not currently set. Intended as a Square-assigned identifier, based on the card number, to identify the card across multiple locations within a single application.
- id string? - Unique ID for this card. Generated by Square.
- last_4 string? - The last 4 digits of the card number.
- prepaid_type string? - Indicates whether the Card is prepaid or not. The Card object includes this field only in response to Payments API calls.
- reference_id string? - An optional user-defined reference ID that associates this card with another entity in an external system. For example, a customer ID from an external customer management system.
- 'version int? - Current version number of the card. Increments with each card update. Requests to update an existing Card object will be rejected unless the version in the request matches the current version for the Card.
squareup: CardPaymentDetails
Reflects the current status of a card payment. Contains only non-confidential information.
Fields
- application_cryptogram string? - For EMV payments, the cryptogram generated for the payment.
- application_identifier string? - For EMV payments, the application ID identifies the EMV application used for the payment.
- application_name string? - For EMV payments, the human-readable name of the EMV application used for the payment.
- auth_result_code string? - The status code returned by the card issuer that describes the payment's authorization status.
- avs_status string? - The status code returned from the Address Verification System (AVS) check. The code can be
AVS_ACCEPTED
,AVS_REJECTED
, orAVS_NOT_CHECKED
.
- card Card? - Represents the payment details of a card to be used for payments. These details are determined by the payment token generated by Web Payments SDK.
- card_payment_timeline CardPaymentTimeline? - The timeline for card payments.
- cvv_status string? - The status code returned from the Card Verification Value (CVV) check. The code can be
CVV_ACCEPTED
,CVV_REJECTED
, orCVV_NOT_CHECKED
.
- device_details DeviceDetails? - Details about the device that took the payment.
- entry_method string? - The method used to enter the card's details for the payment. The method can be
KEYED
,SWIPED
,EMV
,ON_FILE
, orCONTACTLESS
.
- errors Error[]? - Information about errors encountered during the request.
- refund_requires_card_presence boolean? - Whether the card must be physically present for the payment to
be refunded. If set to
true
, the card must be present.
- statement_description string? - The statement description sent to the card networks. Note: The actual statement description varies and is likely to be truncated and appended with additional information on a per issuer basis.
- status string? - The card payment's current state. The state can be AUTHORIZED, CAPTURED, VOIDED, or FAILED.
- verification_method string? - For EMV payments, the method used to verify the cardholder's identity. The method can be
PIN
,SIGNATURE
,PIN_AND_SIGNATURE
,ON_DEVICE
, orNONE
.
- verification_results string? - For EMV payments, the results of the cardholder verification. The result can be
SUCCESS
,FAILURE
, orUNKNOWN
.
squareup: CardPaymentTimeline
The timeline for card payments.
Fields
- authorized_at string? - The timestamp when the payment was authorized, in RFC 3339 format.
- captured_at string? - The timestamp when the payment was captured, in RFC 3339 format.
- voided_at string? - The timestamp when the payment was voided, in RFC 3339 format.
squareup: CashDrawerDevice
Fields
- id string? - The device Square-issued ID
- name string? - The device merchant-specified name.
squareup: CashDrawerShift
This model gives the details of a cash drawer shift. The cash_payment_money, cash_refund_money, cash_paid_in_money, and cash_paid_out_money fields are all computed by summing their respective event types.
Fields
- cash_paid_in_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- cash_paid_out_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- cash_payment_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- cash_refunds_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- closed_at string? - The time when the shift was closed, in ISO 8601 format.
- closed_cash_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- closing_employee_id string? - The ID of the employee that closed the cash drawer shift by auditing the cash drawer contents.
- description string? - The free-form text description of a cash drawer by an employee.
- device CashDrawerDevice? -
- employee_ids string[]? - The IDs of all employees that were logged into Square Point of Sale at any point while the cash drawer shift was open.
- ended_at string? - The time when the shift ended, in ISO 8601 format.
- ending_employee_id string? - The ID of the employee that ended the cash drawer shift.
- expected_cash_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- id string? - The shift unique ID.
- opened_at string? - The time when the shift began, in ISO 8601 format.
- opened_cash_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- opening_employee_id string? - The ID of the employee that started the cash drawer shift.
- state string? - The shift current state.
squareup: CashDrawerShiftEvent
Fields
- created_at string? - The event time in ISO 8601 format.
- description string? - An optional description of the event, entered by the employee that created the event.
- employee_id string? - The ID of the employee that created the event.
- event_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- event_type string? - The type of cash drawer shift event.
- id string? - The unique ID of the event.
squareup: CashDrawerShiftSummary
The summary of a closed cash drawer shift. This model contains only the money counted to start a cash drawer shift, counted at the end of the shift, and the amount that should be in the drawer at shift end based on summing all cash drawer shift events.
Fields
- closed_at string? - The shift close time in ISO 8601 format.
- closed_cash_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- description string? - An employee free-text description of a cash drawer shift.
- ended_at string? - The shift end time in ISO 8601 format.
- expected_cash_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- id string? - The shift unique ID.
- opened_at string? - The shift start time in ISO 8601 format.
- opened_cash_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- state string? - The shift current state.
squareup: CashPaymentDetails
Stores details about a cash payment. Contains only non-confidential information. For more information, see Take Cash Payments.
Fields
- buyer_supplied_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- change_back_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
squareup: CatalogCategory
A category to which a CatalogItem
instance belongs.
Fields
- name string? - The category name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.
squareup: CatalogCustomAttributeDefinition
Contains information defining a custom attribute. Custom attributes are intended to store additional information about a catalog object or to associate a catalog object with an entity in another system. Do not use custom attributes to store any sensitive information (personally identifiable information, card details, etc.). Read more about custom attributes
Fields
- allowed_object_types string[] - The set of Catalog Object Types that this Custom Attribute may be applied to.
Currently, only
ITEM
andITEM_VARIATION
are allowed. At least one type must be included.
- app_visibility string? - The visibility of a custom attribute to applications other than the application that created the attribute.
- custom_attribute_usage_count int? - Read-only. The number of custom attributes that reference this
custom attribute definition. Set by the server in response to a ListCatalog
request with
include_counts
set totrue
. If the actual count is greater than 100,custom_attribute_usage_count
will be set to100
.
- description string? - Seller-oriented description of the meaning of this Custom Attribute, any constraints that the seller should observe, etc. May be displayed as a tooltip in Square UIs.
- 'key string? - The name of the desired custom attribute key that can be used to access
the custom attribute value on catalog objects. Cannot be modified after the
custom attribute definition has been created.
Must be between 1 and 60 characters, and may only contain the characters
[a-zA-Z0-9_-]
.
- name string - The name of this definition for API and seller-facing UI purposes. The name must be unique within the (merchant, application) pair. Required. May not be empty and may not exceed 255 characters. Can be modified after creation.
- number_config CatalogCustomAttributeDefinitionNumberConfig? -
- selection_config CatalogCustomAttributeDefinitionSelectionConfig? - Configuration associated with
SELECTION
-type custom attribute definitions.
- seller_visibility string? - The visibility of a custom attribute in seller-facing UIs (including Square Point of Sale applications and Square Dashboard). May be modified.
- source_application SourceApplication? - Provides information about the application used to generate a change.
- string_config CatalogCustomAttributeDefinitionStringConfig? - Configuration associated with Custom Attribute Definitions of type
STRING
.
- 'type string - The type of this custom attribute. Cannot be modified after creation. Required.
squareup: CatalogCustomAttributeDefinitionNumberConfig
Fields
- precision int? - An integer between 0 and 5 that represents the maximum number of
positions allowed after the decimal in number custom attribute values
For example:
- if the precision is 0, the quantity can be 1, 2, 3, etc.
- if the precision is 1, the quantity can be 0.1, 0.2, etc.
- if the precision is 2, the quantity can be 0.01, 0.12, etc.
squareup: CatalogCustomAttributeDefinitionSelectionConfig
Configuration associated with SELECTION
-type custom attribute definitions.
Fields
- allowed_selections CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection[]? - The set of valid
CatalogCustomAttributeSelections
. Up to a maximum of 100 selections can be defined. Can be modified.
- max_allowed_selections int? - The maximum number of selections that can be set. The maximum value for this attribute is 100. The default value is 1. The value can be modified, but changing the value will not affect existing custom attribute values on objects. Clients need to handle custom attributes with more selected values than allowed by this limit.
squareup: CatalogCustomAttributeDefinitionSelectionConfigCustomAttributeSelection
A named selection for this SELECTION
-type custom attribute definition.
Fields
- name string - Selection name, unique within
allowed_selections
.
- uid string? - Unique ID set by Square.
squareup: CatalogCustomAttributeDefinitionStringConfig
Configuration associated with Custom Attribute Definitions of type STRING
.
Fields
- enforce_uniqueness boolean? - If true, each Custom Attribute instance associated with this Custom Attribute Definition must have a unique value within the seller's catalog. For example, this may be used for a value like a SKU that should not be duplicated within a seller's catalog. May not be modified after the definition has been created.
squareup: CatalogCustomAttributeValue
An instance of a custom attribute. Custom attributes can be defined and
added to ITEM
and ITEM_VARIATION
type catalog objects.
Read more about custom attributes.
Fields
- boolean_value boolean? - A
true
orfalse
value. Populated iftype
=BOOLEAN
.
- custom_attribute_definition_id string? - Read-only. The id of the CatalogCustomAttributeDefinition this value belongs to.
- 'key string? - Read-only. A copy of key from the associated
CatalogCustomAttributeDefinition
.
- name string? - The name of the custom attribute.
- number_value string? - Populated if
type
=NUMBER
. Contains a string representation of a decimal number, using a.
as the decimal separator.
- selection_uid_values string[]? - One or more choices from
allowed_selections
. Populated iftype
=SELECTION
.
- string_value string? - The string value of the custom attribute. Populated if
type
=STRING
.
- 'type string? - Read-only. A copy of type from the associated
CatalogCustomAttributeDefinition
.
squareup: CatalogDiscount
A discount applicable to items.
Fields
- amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- discount_type string? - Indicates whether the discount is a fixed amount or percentage, or entered at the time of sale.
- label_color string? - The color of the discount display label in the Square Point of Sale app. This must be a valid hex color code.
- modify_tax_basis string? - Indicates whether this discount should reduce the price used to calculate tax.
Most discounts should use
MODIFY_TAX_BASIS
. However, in some circumstances taxes must be calculated based on an item's price, ignoring a particular discount. For example, in many US jurisdictions, a manufacturer coupon or instant rebate reduces the price a customer pays but does not reduce the sale price used to calculate how much sales tax is due. In this case, the discount representing that manufacturer coupon should haveDO_NOT_MODIFY_TAX_BASIS
for this field. If you are unsure whether you need to use this field, consult your tax professional.
- name string? - The discount name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.
- percentage string? - The percentage of the discount as a string representation of a decimal number, using a
.
as the decimal separator and without a%
sign. A value of7.5
corresponds to7.5%
. Specify a percentage of0
ifdiscount_type
isVARIABLE_PERCENTAGE
. Do not use this field for amount-based or variable discounts.
- pin_required boolean? - Indicates whether a mobile staff member needs to enter their PIN to apply the discount to a payment in the Square Point of Sale app.
squareup: CatalogIdMapping
A mapping between a temporary client-supplied ID and a permanent server-generated ID.
When calling UpsertCatalogObject or BatchUpsertCatalogObjects to create a CatalogObject instance, you can supply a temporary ID for the to-be-created object, especially when the object is to be referenced elsewhere in the same request body. This temporary ID can be any string unique within the call, but must be prefixed by "#".
After the request is submitted and the object created, a permanent server-generated ID is assigned to the new object. The permanent ID is unique across the Square catalog.
Fields
- client_object_id string? - The client-supplied temporary
#
-prefixed ID for a newCatalogObject
.
- object_id string? - The permanent ID for the CatalogObject created by the server.
squareup: CatalogImage
An image file to use in Square catalogs. It can be associated with catalog items, item variations, and categories.
Fields
- name string? - The internal name to identify this image in calls to the Square API. This is a searchable attribute for use in applicable query filters using the SearchCatalogObjects. It is not unique and should not be shown in a buyer facing context.
- url string? - The URL of this image, generated by Square after an image is uploaded using the CreateCatalogImage endpoint.
squareup: CatalogInfoRequest
squareup: CatalogInfoResponse
Fields
- errors Error[]? - Any errors that occurred during the request.
- limits CatalogInfoResponseLimits? -
- standard_unit_description_group StandardUnitDescriptionGroup? - Group of standard measurement units.
squareup: CatalogInfoResponseLimits
Fields
- batch_delete_max_object_ids int? - The maximum number of object IDs that may be included in a single
/v2/catalog/batch-delete
request.
- batch_retrieve_max_object_ids int? - The maximum number of object IDs that may appear in a
/v2/catalog/batch-retrieve
request.
- batch_upsert_max_objects_per_batch int? - The maximum number of objects that may appear within a single batch in a
/v2/catalog/batch-upsert
request.
- batch_upsert_max_total_objects int? - The maximum number of objects that may appear across all batches in a
/v2/catalog/batch-upsert
request.
- search_max_page_limit int? - The maximum number of results that may be returned in a page of a
/v2/catalog/search
response.
- update_item_modifier_lists_max_item_ids int? - The maximum number of item IDs that may be included in a single
/v2/catalog/update-item-modifier-lists
request.
- update_item_modifier_lists_max_modifier_lists_to_disable int? - The maximum number of modifier list IDs to be disabled that may be included in
a single
/v2/catalog/update-item-modifier-lists
request.
- update_item_modifier_lists_max_modifier_lists_to_enable int? - The maximum number of modifier list IDs to be enabled that may be included in
a single
/v2/catalog/update-item-modifier-lists
request.
- update_item_taxes_max_item_ids int? - The maximum number of item IDs that may be included in a single
/v2/catalog/update-item-taxes
request.
- update_item_taxes_max_taxes_to_disable int? - The maximum number of tax IDs to be disabled that may be included in a single
/v2/catalog/update-item-taxes
request.
- update_item_taxes_max_taxes_to_enable int? - The maximum number of tax IDs to be enabled that may be included in a single
/v2/catalog/update-item-taxes
request.
squareup: CatalogItem
A CatalogObject instance of the ITEM
type, also referred to as an item, in the catalog.
Fields
- abbreviation string? - The text of the item's display label in the Square Point of Sale app. Only up to the first five characters of the string are used. This attribute is searchable, and its value length is of Unicode code points.
- available_electronically boolean? - If
true
, the item can be added to electronically fulfilled orders from the merchant's online store.
- available_for_pickup boolean? - If
true
, the item can be added to pickup orders from the merchant's online store.
- available_online boolean? - If
true
, the item can be added to shipping orders from the merchant's online store.
- category_id string? - The ID of the item's category, if any.
- description string? - The item's description. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.
- item_options CatalogItemOptionForItem[]? - List of item options IDs for this item. Used to manage and group item variations in a specified order. Maximum: 6 item options.
- label_color string? - The color of the item's display label in the Square Point of Sale app. This must be a valid hex color code.
- modifier_list_info CatalogItemModifierListInfo[]? - A set of
CatalogItemModifierListInfo
objects representing the modifier lists that apply to this item, along with the overrides and min and max limits that are specific to this item. Modifier lists may also be added to or deleted from an item usingUpdateItemModifierLists
.
- name string? - The item's name. This is a searchable attribute for use in applicable query filters, its value must not be empty, and the length is of Unicode code points.
- product_type string? - The product type of the item. May not be changed once an item has been created.
Only items of product type
REGULAR
orAPPOINTMENTS_SERVICE
may be created by this API; items with other product types are read-only.
- skip_modifier_screen boolean? - If
false
, the Square Point of Sale app will present theCatalogItem
's details screen immediately, allowing the merchant to chooseCatalogModifier
s before adding the item to the cart. This is the default behavior. Iftrue
, the Square Point of Sale app will immediately add the item to the cart with the pre-selected modifiers, and merchants can edit modifiers by drilling down onto the item's details. Third-party clients are encouraged to implement similar behaviors.
- sort_name string? - A name to sort the item by. If this name is unspecified, namely, the
sort_name
field is absent, the regularname
field is used for sorting. It is currently supported for sellers of the Japanese locale only.
- tax_ids string[]? - A set of IDs indicating the taxes enabled for
this item. When updating an item, any taxes listed here will be added to the item.
Taxes may also be added to or deleted from an item using
UpdateItemTaxes
.
- variations CatalogObject[]? - A list of CatalogItemVariation objects for this item. An item must have at least one variation.
squareup: CatalogItemModifierListInfo
Options to control the properties of a CatalogModifierList
applied to a CatalogItem
instance.
Fields
- enabled boolean? - If
true
, enable thisCatalogModifierList
. The default value istrue
.
- max_selected_modifiers int? - If 0 or larger, the largest number of
CatalogModifier
s that can be selected from thisCatalogModifierList
.
- min_selected_modifiers int? - If 0 or larger, the smallest number of
CatalogModifier
s that must be selected from thisCatalogModifierList
.
- modifier_list_id string - The ID of the
CatalogModifierList
controlled by thisCatalogModifierListInfo
.
- modifier_overrides CatalogModifierOverride[]? - A set of
CatalogModifierOverride
objects that override whether a givenCatalogModifier
is enabled by default.
squareup: CatalogItemOption
A group of variations for a CatalogItem
.
Fields
- description string? - The item option's human-readable description. Displayed in the Square Point of Sale app for the seller and in the Online Store or on receipts for the buyer. This is a searchable attribute for use in applicable query filters.
- display_name string? - The item option's display name for the customer. This is a searchable attribute for use in applicable query filters.
- name string? - The item option's display name for the seller. Must be unique across all item options. This is a searchable attribute for use in applicable query filters.
- show_colors boolean? - If true, display colors for entries in
values
when present.
- values CatalogObject[]? - A list of CatalogObjects containing the
CatalogItemOptionValue
s for this item.
squareup: CatalogItemOptionForItem
An option that can be assigned to an item. For example, a t-shirt item may offer a color option or a size option.
Fields
- item_option_id string? - The unique id of the item option, used to form the dimensions of the item option matrix in a specified order.
squareup: CatalogItemOptionValue
An enumerated value that can link a
CatalogItemVariation
to an item option as one of
its item option values.
Fields
- color string? - The HTML-supported hex color for the item option (e.g., "#ff8d4e85").
Only displayed if
show_colors
is enabled on the parentItemOption
. When left unset,color
defaults to white ("#ffffff") whenshow_colors
is enabled on the parentItemOption
.
- description string? - A human-readable description for the option value. This is a searchable attribute for use in applicable query filters.
- item_option_id string? - Unique ID of the associated item option.
- name string? - Name of this item option value. This is a searchable attribute for use in applicable query filters.
- ordinal int? - Determines where this option value appears in a list of option values.
squareup: CatalogItemOptionValueForItemVariation
A CatalogItemOptionValue
links an item variation to an item option as
an item option value. For example, a t-shirt item may offer a color option and
a size option. An item option value would represent each variation of t-shirt:
For example, "Color:Red, Size:Small" or "Color:Blue, Size:Medium".
Fields
- item_option_id string? - The unique id of an item option.
- item_option_value_id string? - The unique id of the selected value for the item option.
squareup: CatalogItemVariation
An item variation (i.e., product) in the Catalog object model. Each item may have a maximum of 250 item variations.
Fields
- available_for_booking boolean? - If the
CatalogItem
that owns this item variation is of typeAPPOINTMENTS_SERVICE
, a bool representing whether this service is available for booking.
- inventory_alert_threshold int? - If the inventory quantity for the variation is less than or equal to this value and
inventory_alert_type
isLOW_QUANTITY
, the variation displays an alert in the merchant dashboard. This value is always an integer.
- inventory_alert_type string? - Indicates whether the item variation displays an alert when its inventory quantity is less than or equal
to its
inventory_alert_threshold
.
- item_id string? - The ID of the
CatalogItem
associated with this item variation.
- item_option_values CatalogItemOptionValueForItemVariation[]? - List of item option values associated with this item variation. Listed in the same order as the item options of the parent item.
- location_overrides ItemVariationLocationOverrides[]? - Per-location price and inventory overrides.
- measurement_unit_id string? - ID of the ‘CatalogMeasurementUnit’ that is used to measure the quantity sold of this item variation. If left unset, the item will be sold in whole quantities.
- name string? - The item variation's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.
- ordinal int? - The order in which this item variation should be displayed. This value is read-only. On writes, the ordinal
for each item variation within a parent
CatalogItem
is set according to the item variations's position. On reads, the value is not guaranteed to be sequential or unique.
- price_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- pricing_type string? - Indicates whether the item variation's price is fixed or determined at the time of sale.
- service_duration int? - If the
CatalogItem
that owns this item variation is of typeAPPOINTMENTS_SERVICE
, then this is the duration of the service in milliseconds. For example, a 30 minute appointment would have the value1800000
, which is equal to 30 (minutes) * 60 (seconds per minute) * 1000 (milliseconds per second).
- sku string? - The item variation's SKU, if any. This is a searchable attribute for use in applicable query filters.
- stockable boolean? - Whether stock is counted directly on this variation (TRUE) or only on its components (FALSE). For backward compatibility missing values will be interpreted as TRUE.
- stockable_conversion CatalogStockConversion? - Represents the rule of conversion between a stockable CatalogItemVariation
and a non-stockable sell-by or receive-by
CatalogItemVariation
that share the same underlying stock.
- team_member_ids string[]? - Tokens of employees that can perform the service represented by this variation. Only valid for
variations of type
APPOINTMENTS_SERVICE
.
- track_inventory boolean? - If
true
, inventory tracking is active for the variation.
- upc string? - The universal product code (UPC) of the item variation, if any. This is a searchable attribute for use in applicable query filters. The value of this attribute should be a number of 12-14 digits long. This restriction is enforced on the Square Seller Dashboard, Square Point of Sale or Retail Point of Sale apps, where this attribute shows in the GTIN field. If a non-compliant UPC value is assigned to this attribute using the API, the value is not editable on the Seller Dashboard, Square Point of Sale or Retail Point of Sale apps unless it is updated to fit the expected format.
- user_data string? - Arbitrary user metadata to associate with the item variation. This attribute value length is of Unicode code points.
squareup: CatalogMeasurementUnit
Represents the unit used to measure a CatalogItemVariation
and
specifies the precision for decimal quantities.
Fields
- measurement_unit MeasurementUnit? - Represents a unit of measurement to use with a quantity, such as ounces
or inches. Exactly one of the following fields are required:
custom_unit
,area_unit
,length_unit
,volume_unit
, andweight_unit
.
- precision int? - An integer between 0 and 5 that represents the maximum number of
positions allowed after the decimal in quantities measured with this unit.
For example:
- if the precision is 0, the quantity can be 1, 2, 3, etc.
- if the precision is 1, the quantity can be 0.1, 0.2, etc.
- if the precision is 2, the quantity can be 0.01, 0.12, etc.
squareup: CatalogModifier
A modifier applicable to items at the time of sale.
Fields
- modifier_list_id string? - The ID of the
CatalogModifierList
associated with this modifier.
- name string? - The modifier name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.
- ordinal int? - Determines where this
CatalogModifier
appears in theCatalogModifierList
.
- price_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
squareup: CatalogModifierList
A list of modifiers applicable to items at the time of sale.
For example, a "Condiments" modifier list applicable to a "Hot Dog" item
may contain "Ketchup", "Mustard", and "Relish" modifiers.
Use the selection_type
field to specify whether or not multiple selections from
the modifier list are allowed.
Fields
- modifiers CatalogObject[]? - The options included in the
CatalogModifierList
. You must include at least oneCatalogModifier
. Each CatalogObject must have typeMODIFIER
and containCatalogModifier
data.
- name string? - The name for the
CatalogModifierList
instance. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.
- ordinal int? - Determines where this modifier list appears in a list of
CatalogModifierList
values.
- selection_type string? - Indicates whether multiple options from the modifier list
can be applied to a single
CatalogItem
.
squareup: CatalogModifierOverride
Options to control how to override the default behavior of the specified modifier.
Fields
- modifier_id string - The ID of the
CatalogModifier
whose default behavior is being overridden.
- on_by_default boolean? - If
true
, thisCatalogModifier
should be selected by default for thisCatalogItem
.
squareup: CatalogObject
The wrapper object for the Catalog entries of a given object type.
The type of a particular CatalogObject
is determined by the value of the
type
attribute and only the corresponding data attribute can be set on the CatalogObject
instance.
For example, the following list shows some instances of CatalogObject
of a given type
and
their corresponding data attribute that can be set:
- For a
CatalogObject
of theITEM
type, set theitem_data
attribute to yield theCatalogItem
object. - For a
CatalogObject
of theITEM_VARIATION
type, set theitem_variation_data
attribute to yield theCatalogItemVariation
object. - For a
CatalogObject
of theMODIFIER
type, set themodifier_data
attribute to yield theCatalogModifier
object. - For a
CatalogObject
of theMODIFIER_LIST
type, set themodifier_list_data
attribute to yield theCatalogModifierList
object. - For a
CatalogObject
of theCATEGORY
type, set thecategory_data
attribute to yield theCatalogCategory
object. - For a
CatalogObject
of theDISCOUNT
type, set thediscount_data
attribute to yield theCatalogDiscount
object. - For a
CatalogObject
of theTAX
type, set thetax_data
attribute to yield theCatalogTax
object. - For a
CatalogObject
of theIMAGE
type, set theimage_data
attribute to yield theCatalogImageData
object. - For a
CatalogObject
of theQUICK_AMOUNTS_SETTINGS
type, set thequick_amounts_settings_data
attribute to yield theCatalogQuickAmountsSettings
object. - For a
CatalogObject
of thePRICING_RULE
type, set thepricing_rule_data
attribute to yield theCatalogPricingRule
object. - For a
CatalogObject
of theTIME_PERIOD
type, set thetime_period_data
attribute to yield theCatalogTimePeriod
object. - For a
CatalogObject
of thePRODUCT_SET
type, set theproduct_set_data
attribute to yield theCatalogProductSet
object. - For a
CatalogObject
of theSUBSCRIPTION_PLAN
type, set thesubscription_plan_data
attribute to yield theCatalogSubscriptionPlan
object.
For a more detailed discussion of the Catalog data model, please see the Design a Catalog guide.
Fields
- absent_at_location_ids string[]? - A list of locations where the object is not present, even if
present_at_all_locations
istrue
. This can include locations that are deactivated.
- catalog_v1_ids CatalogV1Id[]? - The Connect v1 IDs for this object at each location where it is present, where they differ from the object's Connect V2 ID. The field will only be present for objects that have been created or modified by legacy APIs.
- category_data CatalogCategory? - A category to which a
CatalogItem
instance belongs.
- custom_attribute_definition_data CatalogCustomAttributeDefinition? - Contains information defining a custom attribute. Custom attributes are intended to store additional information about a catalog object or to associate a catalog object with an entity in another system. Do not use custom attributes to store any sensitive information (personally identifiable information, card details, etc.). Read more about custom attributes
- custom_attribute_values record {}? - A map (key-value pairs) of application-defined custom attribute values. The value of a key-value pair
is a CatalogCustomAttributeValue object. The key is the
key
attribute value defined in the associated CatalogCustomAttributeDefinition object defined by the application making the request. If theCatalogCustomAttributeDefinition
object is defined by another application, theCatalogCustomAttributeDefinition
's key attribute value is prefixed by the defining application ID. For example, if theCatalogCustomAttributeDefinition
has akey
attribute of"cocoa_brand"
and the defining application ID is"abcd1234"
, the key in the map is"abcd1234:cocoa_brand"
if the application making the request is different from the application defining the custom attribute definition. Otherwise, the key used in the map is simply"cocoa_brand"
. Application-defined custom attributes that are set at a global (location-independent) level. Custom attribute values are intended to store additional information about a catalog object or associations with an entity in another system. Do not use custom attributes to store any sensitive information (personally identifiable information, card details, etc.).
- discount_data CatalogDiscount? - A discount applicable to items.
- id string - An identifier to reference this object in the catalog. When a new
CatalogObject
is inserted, the client should set the id to a temporary identifier starting with a "#
" character. Other objects being inserted or updated within the same request may use this identifier to refer to the new object. When the server receives the new object, it will supply a unique identifier that replaces the temporary identifier for all future references.
- image_data CatalogImage? - An image file to use in Square catalogs. It can be associated with catalog items, item variations, and categories.
- image_id string? - Identifies the
CatalogImage
attached to thisCatalogObject
.
- is_deleted boolean? - If
true
, the object has been deleted from the database. Must befalse
for new objects being inserted. When deleted, theupdated_at
field will equal the deletion time.
- item_data CatalogItem? - A CatalogObject instance of the
ITEM
type, also referred to as an item, in the catalog.
- item_option_data CatalogItemOption? - A group of variations for a
CatalogItem
.
- item_option_value_data CatalogItemOptionValue? - An enumerated value that can link a
CatalogItemVariation
to an item option as one of its item option values.
- item_variation_data CatalogItemVariation? - An item variation (i.e., product) in the Catalog object model. Each item may have a maximum of 250 item variations.
- measurement_unit_data CatalogMeasurementUnit? - Represents the unit used to measure a
CatalogItemVariation
and specifies the precision for decimal quantities.
- modifier_data CatalogModifier? - A modifier applicable to items at the time of sale.
- modifier_list_data CatalogModifierList? - A list of modifiers applicable to items at the time of sale.
For example, a "Condiments" modifier list applicable to a "Hot Dog" item
may contain "Ketchup", "Mustard", and "Relish" modifiers.
Use the
selection_type
field to specify whether or not multiple selections from the modifier list are allowed.
- present_at_all_locations boolean? - If
true
, this object is present at all locations (including future locations), except where specified in theabsent_at_location_ids
field. Iffalse
, this object is not present at any locations (including future locations), except where specified in thepresent_at_location_ids
field. If not specified, defaults totrue
.
- present_at_location_ids string[]? - A list of locations where the object is present, even if
present_at_all_locations
isfalse
. This can include locations that are deactivated.
- pricing_rule_data CatalogPricingRule? - Defines how discounts are automatically applied to a set of items that match the pricing rule during the active time period.
- product_set_data CatalogProductSet? - Represents a collection of catalog objects for the purpose of applying a
PricingRule
. Including a catalog object will include all of its subtypes. For example, including a category in a product set will include all of its items and associated item variations in the product set. Including an item in a product set will also include its item variations.
- quick_amounts_settings_data CatalogQuickAmountsSettings? - A parent Catalog Object model represents a set of Quick Amounts and the settings control the amounts.
- subscription_plan_data CatalogSubscriptionPlan? - Describes a subscription plan. For more information, see Set Up and Manage a Subscription Plan.
- tax_data CatalogTax? - A tax applicable to an item.
- time_period_data CatalogTimePeriod? - Represents a time period - either a single period or a repeating period.
- 'type string - The type of this object. Each object type has expected
properties expressed in a structured format within its corresponding
*_data
field below.
- 'version int? - The version of the object. When updating an object, the version supplied must match the version in the database, otherwise the write will be rejected as conflicting.
squareup: CatalogObjectBatch
A batch of catalog objects.
Fields
- objects CatalogObject[] - A list of CatalogObjects belonging to this batch.
squareup: CatalogObjectReference
A reference to a Catalog object at a specific version. In general this is used as an entry point into a graph of catalog objects, where the objects exist at a specific version.
Fields
- catalog_version int? - The version of the object.
- object_id string? - The ID of the referenced object.
squareup: CatalogPricingRule
Defines how discounts are automatically applied to a set of items that match the pricing rule during the active time period.
Fields
- apply_products_id string? - Deprecated: Please use the
exclude_products_id
field to apply an exclude set instead. Exclude sets allow better control over quantity ranges and offer more flexibility for which matched items receive a discount.CatalogProductSet
to apply the pricing to. An apply rule matches within the subset of the cart that fits the match rules (the match set). An apply rule can only match once in the match set. If not supplied, the pricing will be applied to all products in the match set. Other products retain their base price, or a price generated by other rules.
- customer_group_ids_any string[]? - A list of IDs of customer groups, the members of which are eligible for discounts specified in this pricing rule.
Notice that a group ID is generated by the Customers API.
If this field is not set, the specified discount applies to matched products sold to anyone whether the buyer
has a customer profile created or not. If this
customer_group_ids_any
field is set, the specified discount applies only to matched products sold to customers belonging to the specified customer groups.
- discount_id string? - Unique ID for the
CatalogDiscount
to take off the price of all matched items.
- exclude_products_id string? -
CatalogProductSet
to exclude from the pricing rule. An exclude rule matches within the subset of the cart that fits the match rules (the match set). An exclude rule can only match once in the match set. If not supplied, the pricing will be applied to all products in the match set. Other products retain their base price, or a price generated by other rules.
- exclude_strategy string? - If an
exclude_products_id
was given, controls which subset of matched products is excluded from any discounts. Default value:LEAST_EXPENSIVE
- match_products_id string? - Unique ID for the
CatalogProductSet
that will be matched by this rule. A match rule matches within the entire cart, and can match multiple times. This field will always be set.
- name string? - User-defined name for the pricing rule. For example, "Buy one get one free" or "10% off".
- time_period_ids string[]? - A list of unique IDs for the catalog time periods when this pricing rule is in effect. If left unset, the pricing rule is always in effect.
- valid_from_date string? - Represents the date the Pricing Rule is valid from. Represented in RFC 3339 full-date format (YYYY-MM-DD).
- valid_from_local_time string? - Represents the local time the pricing rule should be valid from. Represented in RFC 3339 partial-time format (HH:MM:SS). Partial seconds will be truncated.
- valid_until_date string? - Represents the date the Pricing Rule is valid until. Represented in RFC 3339 full-date format (YYYY-MM-DD).
- valid_until_local_time string? - Represents the local time the pricing rule should be valid until. Represented in RFC 3339 partial-time format (HH:MM:SS). Partial seconds will be truncated.
squareup: CatalogProductSet
Represents a collection of catalog objects for the purpose of applying a
PricingRule
. Including a catalog object will include all of its subtypes.
For example, including a category in a product set will include all of its
items and associated item variations in the product set. Including an item in
a product set will also include its item variations.
Fields
- all_products boolean? - If set to
true
, the product set will include every item in the catalog. Only one ofproduct_ids_all
,product_ids_any
, orall_products
can be set.
- name string? - User-defined name for the product set. For example, "Clearance Items" or "Winter Sale Items".
- product_ids_all string[]? - Unique IDs for any
CatalogObject
included in this product set. All objects in this set must be included in an order for a pricing rule to apply. Only one ofproduct_ids_all
,product_ids_any
, orall_products
can be set. Max: 500 catalog object IDs.
- product_ids_any string[]? - Unique IDs for any
CatalogObject
included in this product set. Any number of these catalog objects can be in an order for a pricing rule to apply. This can be used withproduct_ids_all
in a parentCatalogProductSet
to match groups of products for a bulk discount, such as a discount for an entree and side combo. Only one ofproduct_ids_all
,product_ids_any
, orall_products
can be set. Max: 500 catalog object IDs.
- quantity_exact int? - If set, there must be exactly this many items from
products_any
orproducts_all
in the cart for the discount to apply. Cannot be combined with eitherquantity_min
orquantity_max
.
- quantity_max int? - If set, the pricing rule will apply to a maximum of this many items from
products_any
orproducts_all
.
- quantity_min int? - If set, there must be at least this many items from
products_any
orproducts_all
in a cart for the discount to apply. Seequantity_exact
. Defaults to 0 ifquantity_exact
,quantity_min
andquantity_max
are all unspecified.
squareup: CatalogQuery
A query composed of one or more different types of filters to narrow the scope of targeted objects when calling the SearchCatalogObjects
endpoint.
Although a query can have multiple filters, only certain query types can be combined per call to SearchCatalogObjects. Any combination of the following types may be used together:
- exact_query
- prefix_query
- range_query
- sorted_attribute_query
- text_query All other query types cannot be combined with any others.
When a query filter is based on an attribute, the attribute must be searchable. Searchable attributes are listed as follows, along their parent types that can be searched for with applicable query filters.
- Searchable attribute and objects queryable by searchable attributes **
name
:CatalogItem
,CatalogItemVariation
,CatalogCategory
,CatalogTax
,CatalogDiscount
,CatalogModifier
, 'CatalogModifierList,
CatalogItemOption,
CatalogItemOptionValueMISSING[] MISSING[
]-description
:CatalogItem
,CatalogItemOptionValue
abbreviation
:CatalogItem
upc
:CatalogItemVariation
sku
:CatalogItemVariation
caption
:CatalogImage
display_name
:CatalogItemOption
For example, to search for CatalogItem objects by searchable attributes, you can use
the "name"
, "description"
, or "abbreviation"
attribute in an applicable query filter.
Fields
- exact_query CatalogQueryExact? - The query filter to return the search result by exact match of the specified attribute name and value.
- item_variations_for_item_option_values_query CatalogQueryItemVariationsForItemOptionValues? - The query filter to return the item variations containing the specified item option value IDs.
- items_for_item_options_query CatalogQueryItemsForItemOptions? - The query filter to return the items containing the specified item option IDs.
- items_for_modifier_list_query CatalogQueryItemsForModifierList? - The query filter to return the items containing the specified modifier list IDs.
- items_for_tax_query CatalogQueryItemsForTax? - The query filter to return the items containing the specified tax IDs.
- prefix_query CatalogQueryPrefix? - The query filter to return the search result whose named attribute values are prefixed by the specified attribute value.
- range_query CatalogQueryRange? - The query filter to return the search result whose named attribute values fall between the specified range.
- set_query CatalogQuerySet? - The query filter to return the search result(s) by exact match of the specified
attribute_name
and any of theattribute_values
.
- sorted_attribute_query CatalogQuerySortedAttribute? - The query expression to specify the key to sort search results.
- text_query 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.
squareup: CatalogQueryExact
The query filter to return the search result by exact match of the specified attribute name and value.
Fields
- attribute_name string - The name of the attribute to be searched. Matching of the attribute name is exact.
- attribute_value string - The desired value of the search attribute. Matching of the attribute value is case insensitive and can be partial. For example, if a specified value of "sma", objects with the named attribute value of "Small", "small" are both matched.
squareup: CatalogQueryItemsForItemOptions
The query filter to return the items containing the specified item option IDs.
Fields
- item_option_ids string[]? - A set of
CatalogItemOption
IDs to be used to find associatedCatalogItem
s. All Items that contain all of the given Item Options (in any order) will be returned.
squareup: CatalogQueryItemsForModifierList
The query filter to return the items containing the specified modifier list IDs.
Fields
- modifier_list_ids string[] - A set of
CatalogModifierList
IDs to be used to find associatedCatalogItem
s.
squareup: CatalogQueryItemsForTax
The query filter to return the items containing the specified tax IDs.
Fields
- tax_ids string[] - A set of
CatalogTax
IDs to be used to find associatedCatalogItem
s.
squareup: CatalogQueryItemVariationsForItemOptionValues
The query filter to return the item variations containing the specified item option value IDs.
Fields
- item_option_value_ids string[]? - A set of
CatalogItemOptionValue
IDs to be used to find associatedCatalogItemVariation
s. All ItemVariations that contain all of the given Item Option Values (in any order) will be returned.
squareup: CatalogQueryPrefix
The query filter to return the search result whose named attribute values are prefixed by the specified attribute value.
Fields
- attribute_name string - The name of the attribute to be searched.
- attribute_prefix string - The desired prefix of the search attribute value.
squareup: CatalogQueryRange
The query filter to return the search result whose named attribute values fall between the specified range.
Fields
- attribute_max_value int? - The desired maximum value for the search attribute (inclusive).
- attribute_min_value int? - The desired minimum value for the search attribute (inclusive).
- attribute_name string - The name of the attribute to be searched.
squareup: CatalogQuerySet
The query filter to return the search result(s) by exact match of the specified attribute_name
and any of
the attribute_values
.
Fields
- attribute_name string - The name of the attribute to be searched. Matching of the attribute name is exact.
- attribute_values string[] - The desired values of the search attribute. Matching of the attribute values is exact and case insensitive. A maximum of 250 values may be searched in a request.
squareup: CatalogQuerySortedAttribute
The query expression to specify the key to sort search results.
Fields
- attribute_name string - The attribute whose value is used as the sort key.
- initial_attribute_value string? - The first attribute value to be returned by the query. Ascending sorts will return only objects with this value or greater, while descending sorts will return only objects with this value or less. If unset, start at the beginning (for ascending sorts) or end (for descending sorts).
- sort_order string? - The desired sort order,
"ASC"
(ascending) or"DESC"
(descending).
squareup: 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.
Fields
- keywords string[] - A list of 1, 2, or 3 search keywords. Keywords with fewer than 3 characters are ignored.
squareup: CatalogQuickAmount
Represents a Quick Amount in the Catalog.
Fields
- amount Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- ordinal int? - The order in which this Quick Amount should be displayed.
- score int? - Describes the ranking of the Quick Amount provided by machine learning model, in the range [0, 100]. MANUAL type amount will always have score = 100.
- 'type string - Represents the type of the Quick Amount.
squareup: CatalogQuickAmountsSettings
A parent Catalog Object model represents a set of Quick Amounts and the settings control the amounts.
Fields
- amounts CatalogQuickAmount[]? - Represents a set of Quick Amounts at this location.
- eligible_for_auto_amounts boolean? - Represents location's eligibility for auto amounts
The boolean should be consistent with whether there are AUTO amounts in the
amounts
.
- option string - Represents the option seller currently uses on Quick Amounts.
squareup: CatalogStockConversion
Represents the rule of conversion between a stockable CatalogItemVariation
and a non-stockable sell-by or receive-by CatalogItemVariation
that
share the same underlying stock.
Fields
- nonstockable_quantity string - The converted equivalent quantity of the non-stockable CatalogItemVariation
in its measurement unit. The
stockable_quantity
value and thisnonstockable_quantity
value together define the conversion ratio between stockable item variation and the non-stockable item variation. It accepts a decimal number in a string format that can take up to 10 digits before the decimal point and up to 5 digits after the decimal point.
- stockable_item_variation_id string - References to the stockable CatalogItemVariation
for this stock conversion. Selling, receiving or recounting the non-stockable
CatalogItemVariation
defined with a stock conversion results in adjustments of this stockableCatalogItemVariation
. This immutable field must reference a stockableCatalogItemVariation
that shares the parent CatalogItem of the convertedCatalogItemVariation.
- stockable_quantity string - The quantity of the stockable item variation (as identified by
stockable_item_variation_id
) equivalent to the non-stockable item variation quantity (as specified innonstockable_quantity
) as defined by this stock conversion. It accepts a decimal number in a string format that can take up to 10 digits before the decimal point and up to 5 digits after the decimal point.
squareup: CatalogSubscriptionPlan
Describes a subscription plan. For more information, see Set Up and Manage a Subscription Plan.
Fields
- name string - The name of the plan.
- phases SubscriptionPhase[] - A list of SubscriptionPhase containing the SubscriptionPhase for this plan.
squareup: CatalogTax
A tax applicable to an item.
Fields
- applies_to_custom_amounts boolean? - If
true
, the fee applies to custom amounts entered into the Square Point of Sale app that are not associated with a particularCatalogItem
.
- calculation_phase string? - Whether the tax is calculated based on a payment's subtotal or total.
- enabled boolean? - A Boolean flag to indicate whether the tax is displayed as enabled (
true
) in the Square Point of Sale app or not (false
).
- inclusion_type string? - Whether the tax is
ADDITIVE
orINCLUSIVE
.
- name string? - The tax's name. This is a searchable attribute for use in applicable query filters, and its value length is of Unicode code points.
- percentage string? - The percentage of the tax in decimal form, using a
'.'
as the decimal separator and without a'%'
sign. A value of7.5
corresponds to 7.5%.
squareup: CatalogTimePeriod
Represents a time period - either a single period or a repeating period.
Fields
- event string? - An iCalendar (RFC 5545) event, which
specifies the name, timing, duration and recurrence of this time period.
Example:
OnlyDTSTART:20190707T180000 DURATION:P2H RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR
SUMMARY
,DTSTART
,DURATION
andRRULE
fields are supported.DTSTART
must be in local (unzoned) time format. Note that whileBEGIN:VEVENT
andEND:VEVENT
is not required in the request. The response will always include them.
squareup: CatalogV1Id
A Square API V1 identifier of an item, including the object ID and its associated location ID.
Fields
- catalog_v1_id string? - The ID for an object used in the Square API V1, if the object ID differs from the Square API V2 object ID.
- location_id string? - The ID of the
Location
this Connect V1 ID is associated with.
squareup: ChargeRequest
Defines the parameters that can be included in the body of a request to the Charge endpoint.
Deprecated - recommend using CreatePayment
Fields
- additional_recipients AdditionalRecipient[]? - The basic primitive of multi-party transaction. The value is optional.
The transaction facilitated by you can be split from here.
If you provide this value, the
amount_money
value in your additional_recipients must not be more than 90% of theamount_money
value in the charge request. Thelocation_id
must be the valid location of the app owner merchant. This field requires thePAYMENTS_WRITE_ADDITIONAL_RECIPIENTS
OAuth permission. This field is currently not supported in sandbox.
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- billing_address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- buyer_email_address string? - The buyer's email address, if available. This value is optional, but this transaction is ineligible for chargeback protection if it is not provided.
- card_nonce string? - A payment token generated from the Card.tokenize() that represents the card
to charge.
The application that provides a payment token to this endpoint must be the
same application that generated the payment token with the Web Payments SDK.
Otherwise, the nonce is invalid.
Do not provide a value for this field if you provide a value for
customer_card_id
.
- customer_card_id string? - The ID of the customer card on file to charge. Do
not provide a value for this field if you provide a value for
card_nonce
. If you provide this value, you must also provide a value forcustomer_id
.
- customer_id string? - The ID of the customer to associate this transaction with. This field
is required if you provide a value for
customer_card_id
, and optional otherwise.
- delay_capture boolean? - If
true
, the request will only perform an Auth on the provided card. You can then later perform either a Capture (with the CaptureTransaction endpoint) or a Void (with the VoidTransaction endpoint). Default value:false
- idempotency_key string - A value you specify that uniquely identifies this transaction among transactions you've created. If you're unsure whether a particular transaction succeeded, you can reattempt it with the same idempotency key without worrying about double-charging the buyer. See Idempotency keys for more information.
- note string? - An optional note to associate with the transaction. This value cannot exceed 60 characters.
- order_id string? - The ID of the order to associate with this transaction.
If you provide this value, the
amount_money
value of your request must exactly match the value of the order'stotal_money
field.
- reference_id string? - An optional ID you can associate with the transaction for your own purposes (such as to associate the transaction with an entity ID in your own database). This value cannot exceed 40 characters.
- shipping_address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- verification_token string? - A token generated by SqPaymentForm's verifyBuyer() that represents customer's device info and 3ds challenge result.
squareup: ChargeRequestAdditionalRecipient
Represents an additional recipient (other than the merchant) entitled to a portion of the tender. Support is currently limited to USD, CAD and GBP currencies
Fields
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- description string - The description of the additional recipient.
- location_id string - The location ID for a recipient (other than the merchant) receiving a portion of the tender.
squareup: ChargeResponse
Defines the fields that are included in the response body of a request to the Charge endpoint.
One of errors
or transaction
is present in a given response (never both).
Fields
- errors Error[]? - Any errors that occurred during the request.
- 'transaction Transaction? - Represents a transaction processed with Square, either with the
Connect API or with Square Point of Sale.
The
tenders
field of this object lists all methods of payment used to pay in the transaction.
squareup: CheckAppointmentsOnboardedRequest
squareup: Checkout
Square Checkout lets merchants accept online payments for supported payment types using a checkout workflow hosted on squareup.com.
Fields
- additional_recipients AdditionalRecipient[]? - Additional recipients (other than the merchant) receiving a portion of this checkout. For example, fees assessed on the purchase by a third party integration.
- ask_for_shipping_address boolean? - If
true
, Square Checkout will collect shipping information on your behalf and store that information with the transaction information in your Square Dashboard. Default:false
.
- checkout_page_url string? - The URL that the buyer's browser should be redirected to after the checkout is completed.
- created_at string? - The time when the checkout was created, in RFC 3339 format.
- id string? - ID generated by Square Checkout when a new checkout is requested.
- merchant_support_email string? - The email address to display on the Square Checkout confirmation page and confirmation email that the buyer can use to contact the merchant. If this value is not set, the confirmation page and email will display the primary email address associated with the merchant's Square account. Default: none; only exists if explicitly set.
- 'order Order? - Contains all information related to a single order to process with Square,
including line items that specify the products to purchase.
Order
objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.
- pre_populate_buyer_email string? - If provided, the buyer's email is pre-populated on the checkout page as an editable text field. Default: none; only exists if explicitly set.
- pre_populate_shipping_address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- redirect_url string? - The URL to redirect to after checkout is completed with
checkoutId
, Square'sorderId
,transactionId
, andreferenceId
appended as URL parameters. For example, if the provided redirect_url ishttp://www.example.com/order-complete
, a successful transaction redirects the customer to: <pre><code>http://www.example.com/order-complete?checkoutId=xxxxxx&orderId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx</code></pre> If you do not provide a redirect URL, Square Checkout will display an order confirmation page on your behalf; however Square strongly recommends that you provide a redirect URL so you can verify the transaction results and finalize the order through your existing/normal confirmation workflow.
squareup: ClientHttp1Settings
Provides settings related to HTTP/1.x protocol.
Fields
- keepAlive KeepAlive(default http:KEEPALIVE_AUTO) - Specifies whether to reuse a connection for multiple requests
- chunking Chunking(default http:CHUNKING_AUTO) - The chunking behaviour of the request
- proxy ProxyConfig? - Proxy server related options
squareup: CompletePaymentRequest
Describes a request to complete (capture) a payment using CompletePayment.
By default, payments are set to autocomplete
immediately after they are created.
To complete payments manually, set autocomplete
to false
.
squareup: CompletePaymentResponse
Defines the response returned byCompletePayment.
Fields
- errors Error[]? - Information about errors encountered during the request.
- payment Payment? - Represents a payment processed by the Square API.
squareup: ConnectionConfig
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Fields
- auth BearerTokenConfig|OAuth2RefreshTokenGrantConfig|ApiKeysConfig - Provides Auth configurations needed when communicating with a remote HTTP endpoint.
- httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
- http1Settings ClientHttp1Settings? - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings? - Configurations related to HTTP/2 protocol
- timeout decimal(default 60) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded
/x-forwarded
header
- poolConfig PoolConfiguration? - Configurations associated with request pooling
- cache CacheConfig? - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding
) header
- circuitBreaker CircuitBreakerConfig? - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig RetryConfig? - Configurations associated with retrying
- responseLimits ResponseLimitConfigs? - Configurations associated with inbound response size limits
- secureSocket ClientSecureSocket? - SSL/TLS-related options
- proxy ProxyConfig? - Proxy server related options
- validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
squareup: Coordinates
Latitude and longitude coordinates.
Fields
- latitude decimal? - The latitude of the coordinate expressed in degrees.
- longitude decimal? - The longitude of the coordinate expressed in degrees.
squareup: CreateBookingRequest
Fields
- booking 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.
- idempotency_key string? - A unique key to make this request an idempotent operation.
squareup: CreateBookingResponse
Fields
- booking 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.
- errors Error[]? - Any errors that occurred during the request.
squareup: CreateBreakTypeRequest
A request to create a new BreakType
.
Fields
- break_type BreakType - A defined break template that sets an expectation for possible
Break
instances on aShift
.
- idempotency_key string? - A unique string value to ensure the idempotency of the operation.
squareup: CreateBreakTypeResponse
The response to the request to create a BreakType
. The response contains
the created BreakType
object and might contain a set of Error
objects if
the request resulted in errors.
Fields
- break_type BreakType? - A defined break template that sets an expectation for possible
Break
instances on aShift
.
- errors Error[]? - Any errors that occurred during the request.
squareup: CreateCardRequest
Creates a card from the source (nonce, payment id, etc). Accessible via HTTP requests at POST https://connect.squareup.com/v2/cards
Fields
- card Card - Represents the payment details of a card to be used for payments. These details are determined by the payment token generated by Web Payments SDK.
- idempotency_key string - A unique string that identifies this CreateCard request. Keys can be any valid string and must be unique for every request. Max: 45 characters See Idempotency keys for more information.
- source_id string - The ID of the source which represents the card information to be stored. This can be a card nonce or a payment id.
- verification_token string? - An identifying token generated by Payments.verifyBuyer(). Verification tokens encapsulate customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity. See the SCA Overview.
squareup: CreateCardResponse
Defines the fields that are included in the response body of a request to the CreateCard endpoint.
Note: if there are errors processing the request, the card field will not be present.
Fields
- card Card? - Represents the payment details of a card to be used for payments. These details are determined by the payment token generated by Web Payments SDK.
- errors Error[]? - Information on errors encountered during the request.
squareup: CreateCheckoutRequest
Defines the parameters that can be included in the body of
a request to the CreateCheckout
endpoint.
Fields
- additional_recipients ChargeRequestAdditionalRecipient[]? - The basic primitive of a multi-party transaction. The value is optional.
The transaction facilitated by you can be split from here.
If you provide this value, the
amount_money
value in youradditional_recipients
field cannot be more than 90% of thetotal_money
calculated by Square for your order. Thelocation_id
must be a valid seller location where the checkout is occurring. This field requiresPAYMENTS_WRITE_ADDITIONAL_RECIPIENTS
OAuth permission. This field is currently not supported in the Square Sandbox.
- ask_for_shipping_address boolean? - If
true
, Square Checkout collects shipping information on your behalf and stores that information with the transaction information in the Square Seller Dashboard. Default:false
.
- idempotency_key string - A unique string that identifies this checkout among others you have created. It can be any valid string but must be unique for every order sent to Square Checkout for a given location ID. The idempotency key is used to avoid processing the same order more than once. If you are unsure whether a particular checkout was created successfully, you can attempt it again with the same idempotency key and all the same other parameters without worrying about creating duplicates. You should use a random number/string generator native to the language you are working in to generate strings for your idempotency keys. For more information, see Idempotency.
- merchant_support_email string? - The email address to display on the Square Checkout confirmation page and confirmation email that the buyer can use to contact the seller. If this value is not set, the confirmation page and email display the primary email address associated with the seller's Square account. Default: none; only exists if explicitly set.
- note string? - An optional note to associate with the
checkout
object. This value cannot exceed 60 characters.
- 'order CreateOrderRequest -
- pre_populate_buyer_email string? - If provided, the buyer's email is prepopulated on the checkout page as an editable text field. Default: none; only exists if explicitly set.
- pre_populate_shipping_address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- redirect_url string? - The URL to redirect to after the checkout is completed with
checkoutId
,transactionId
, andreferenceId
appended as URL parameters. For example, if the provided redirect URL ishttp://www.example.com/order-complete
, a successful transaction redirects the customer to: <pre><code>http://www.example.com/order-complete?checkoutId=xxxxxx&referenceId=xxxxxx&transactionId=xxxxxx</code></pre> If you do not provide a redirect URL, Square Checkout displays an order confirmation page on your behalf; however, it is strongly recommended that you provide a redirect URL so you can verify the transaction results and finalize the order through your existing/normal confirmation workflow. Default: none; only exists if explicitly set.
squareup: CreateCheckoutResponse
Defines the fields that are included in the response body of
a request to the CreateCheckout
endpoint.
Fields
- checkout Checkout? - Square Checkout lets merchants accept online payments for supported payment types using a checkout workflow hosted on squareup.com.
- errors Error[]? - Any errors that occurred during the request.
squareup: CreateCustomerCardRequest
Defines the fields that are included in the request body of a request
to the CreateCustomerCard
endpoint.
Fields
- billing_address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- card_nonce string - A card nonce representing the credit card to link to the customer. Card nonces are generated by the Square payment form when customers enter their card information. For more information, see Walkthrough: Integrate Square Payments in a Website. NOTE: Card nonces generated by digital wallets (such as Apple Pay) cannot be used to create a customer card.
- cardholder_name string? - The full name printed on the credit card.
- verification_token string? - An identifying token generated by Payments.verifyBuyer(). Verification tokens encapsulate customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity.
squareup: CreateCustomerCardResponse
Defines the fields that are included in the response body of
a request to the CreateCustomerCard
endpoint.
Either errors
or card
is present in a given response (never both).
Fields
- card Card? - Represents the payment details of a card to be used for payments. These details are determined by the payment token generated by Web Payments SDK.
- errors Error[]? - Any errors that occurred during the request.
squareup: CreateCustomerGroupRequest
Defines the body parameters that can be included in a request to the CreateCustomerGroup endpoint.
Fields
- group CustomerGroup - Represents a group of customer profiles. Customer groups can be created, be modified, and have their membership defined using the Customers API or within the Customer Directory in the Square Seller Dashboard or Point of Sale.
- idempotency_key string? - The idempotency key for the request. For more information, see Idempotency.
squareup: CreateCustomerGroupResponse
Defines the fields that are included in the response body of a request to the CreateCustomerGroup endpoint.
Either errors
or group
is present in a given response (never both).
Fields
- errors Error[]? - Any errors that occurred during the request.
- group CustomerGroup? - Represents a group of customer profiles. Customer groups can be created, be modified, and have their membership defined using the Customers API or within the Customer Directory in the Square Seller Dashboard or Point of Sale.
squareup: CreateCustomerRequest
Defines the body parameters that can be included in a request to the
CreateCustomer
endpoint.
Fields
- address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- birthday string? - The birthday associated with the customer profile, in RFC 3339 format. The year is optional. The timezone and time are not allowed.
For example,
0000-09-21T00:00:00-00:00
represents a birthday on September 21 and1998-09-21T00:00:00-00:00
represents a birthday on September 21, 1998. You can also specify this value inYYYY-MM-DD
format.
- company_name string? - A business name associated with the customer profile.
- email_address string? - The email address associated with the customer profile.
- family_name string? - The family name (that is, the last name) associated with the customer profile.
- given_name string? - The given name (that is, the first name) associated with the customer profile.
- idempotency_key string? - The idempotency key for the request. For more information, see Idempotency.
- nickname string? - A nickname for the customer profile.
- note string? - A custom note associated with the customer profile.
- phone_number string? - The 11-digit phone number associated with the customer profile.
- reference_id string? - An optional second ID used to associate the customer profile with an entity in another system.
squareup: CreateCustomerResponse
Defines the fields that are included in the response body of
a request to the CreateCustomer
endpoint.
Either errors
or customer
is present in a given response (never both).
Fields
- customer Customer? - Represents a Square customer profile in the Customer Directory of a Square seller.
- errors Error[]? - Any errors that occurred during the request.
squareup: CreateDeviceCodeRequest
Fields
- device_code DeviceCode -
- idempotency_key string - A unique string that identifies this CreateDeviceCode request. Keys can be any valid string but must be unique for every CreateDeviceCode request. See Idempotency keys for more information.
squareup: CreateDeviceCodeResponse
Fields
- device_code DeviceCode? -
- errors Error[]? - Any errors that occurred during the request.
squareup: CreateDisputeEvidenceTextRequest
Defines the parameters for a CreateDisputeEvidenceText
request.
Fields
- evidence_text string - The evidence string.
- evidence_type string? - The type of evidence you are uploading.
- idempotency_key string - The Unique ID. For more information, see Idempotency.
squareup: CreateDisputeEvidenceTextResponse
Defines the fields in a CreateDisputeEvidenceText
response.
Fields
- errors Error[]? - Any errors that occurred during the request.
- evidence DisputeEvidence? -
squareup: CreateGiftCardActivityRequest
A request to create a gift card activity.
Fields
- gift_card_activity GiftCardActivity - Represents an action performed on a gift card that affects its state or balance.
- idempotency_key string - A unique string that identifies the
CreateGiftCardActivity
request.
squareup: CreateGiftCardActivityResponse
A response that contains a GiftCardActivity
that was created.
The response might contain a set of Error
objects if the request resulted in errors.
Fields
- errors Error[]? - Any errors that occurred during the request.
- gift_card_activity GiftCardActivity? - Represents an action performed on a gift card that affects its state or balance.
squareup: CreateGiftCardRequest
A request to create a gift card.
Fields
- gift_card GiftCard - Represents a Square gift card.
- idempotency_key string - A unique string that identifies the
CreateGiftCard
request.
- location_id string - The location ID where the gift card that will be created should be registered.
squareup: CreateGiftCardResponse
A response that contains a GiftCard
. The response might contain a set of Error
objects if the request
resulted in errors.
Fields
- errors Error[]? - Any errors that occurred during the request.
- gift_card GiftCard? - Represents a Square gift card.
squareup: CreateInvoiceRequest
Describes a CreateInvoice
request.
Fields
- idempotency_key string? - A unique string that identifies the
CreateInvoice
request. If you do not provideidempotency_key
(or provide an empty string as the value), the endpoint treats each request as independent. For more information, see Idempotency.
- invoice Invoice - Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see Manage Invoices Using the Invoices API.
squareup: CreateInvoiceResponse
The response returned by the CreateInvoice
request.
Fields
- errors Error[]? - Information about errors encountered during the request.
- invoice Invoice? - Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see Manage Invoices Using the Invoices API.
squareup: CreateLocationRequest
Request object for the CreateLocation endpoint.
Fields
- location Location? -
squareup: CreateLocationResponse
Response object returned by the CreateLocation endpoint.
Fields
- errors Error[]? - Information on errors encountered during the request.
- location Location? -
squareup: CreateLoyaltyAccountRequest
A request to create a new loyalty account.
Fields
- idempotency_key string - A unique string that identifies this
CreateLoyaltyAccount
request. Keys can be any valid string, but must be unique for every request.
- loyalty_account LoyaltyAccount - Describes a loyalty account. For more information, see Manage Loyalty Accounts Using the Loyalty API.
squareup: CreateLoyaltyAccountResponse
A response that includes loyalty account created.
Fields
- errors Error[]? - Any errors that occurred during the request.
- loyalty_account LoyaltyAccount? - Describes a loyalty account. For more information, see Manage Loyalty Accounts Using the Loyalty API.
squareup: CreateLoyaltyRewardRequest
A request to create a loyalty reward.
Fields
- idempotency_key string - A unique string that identifies this
CreateLoyaltyReward
request. Keys can be any valid string, but must be unique for every request.
- reward LoyaltyReward - Represents a contract to redeem loyalty points for a reward tier discount. Loyalty rewards can be in an ISSUED, REDEEMED, or DELETED state. For more information, see Redeem loyalty rewards.
squareup: CreateLoyaltyRewardResponse
A response that includes the loyalty reward created.
Fields
- errors Error[]? - Any errors that occurred during the request.
- reward LoyaltyReward? - Represents a contract to redeem loyalty points for a reward tier discount. Loyalty rewards can be in an ISSUED, REDEEMED, or DELETED state. For more information, see Redeem loyalty rewards.
squareup: CreateMobileAuthorizationCodeRequest
Defines the body parameters that can be provided in a request to the CreateMobileAuthorizationCode endpoint.
Fields
- location_id string? - The Square location ID the authorization code should be tied to.
squareup: CreateMobileAuthorizationCodeResponse
Defines the fields that are included in the response body of a request to the CreateMobileAuthorizationCode endpoint.
Fields
- authorization_code string? - Generated authorization code that connects a mobile application instance to a Square account.
- 'error Error? - Represents an error encountered during a request to the Connect API. See Handling errors for more information.
squareup: CreateOrderRequest
Fields
- idempotency_key string? - A value you specify that uniquely identifies this order among orders you have created. If you are unsure whether a particular order was created successfully, you can try it again with the same idempotency key without worrying about creating duplicate orders. For more information, see Idempotency.
- 'order Order? - Contains all information related to a single order to process with Square,
including line items that specify the products to purchase.
Order
objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.
squareup: CreateOrderResponse
Defines the fields that are included in the response body of
a request to the CreateOrder
endpoint.
Either errors
or order
is present in a given response, but never both.
Fields
- errors Error[]? - Any errors that occurred during the request.
- 'order Order? - Contains all information related to a single order to process with Square,
including line items that specify the products to purchase.
Order
objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.
squareup: CreatePaymentRequest
Describes a request to create a payment using CreatePayment.
Fields
- accept_partial_authorization boolean? - If set to
true
and charging a Square Gift Card, a payment might be returned withamount_money
equal to less than what was requested. For example, a request for $20 when charging a Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose to prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card payment. This field cannot betrue
whenautocomplete = true
. For more information, see Partial amount with Square Gift Cards. Default: false
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- app_fee_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- autocomplete boolean? - If set to
true
, this payment will be completed when possible. If set tofalse
, this payment is held in an approved state until either explicitly completed (captured) or canceled (voided). For more information, see Delayed capture. Default: true
- billing_address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- buyer_email_address string? - The buyer's email address.
- cash_details CashPaymentDetails? - Stores details about a cash payment. Contains only non-confidential information. For more information, see Take Cash Payments.
- delay_duration string? - The duration of time after the payment's creation when Square automatically cancels the
payment. This automatic cancellation applies only to payments that do not reach a terminal state
(COMPLETED, CANCELED, or FAILED) before the
delay_duration
time period. This parameter should be specified as a time duration, in RFC 3339 format, with a minimum value of 1 minute. Note: This feature is only supported for card payments. This parameter can only be set for a delayed capture payment (autocomplete=false
). Default:- Card-present payments: "PT36H" (36 hours) from the creation time.
- Card-not-present payments: "P7D" (7 days) from the creation time.
- external_details ExternalPaymentDetails? - Stores details about an external payment. Contains only non-confidential information. For more information, see Take External Payments.
- idempotency_key string - A unique string that identifies this
CreatePayment
request. Keys can be any valid string but must be unique for everyCreatePayment
request. Max: 45 characters Note: The number of allowed characters might be less than the stated maximum, if multi-byte characters are used. For more information, see Idempotency.
- location_id string? - The location ID to associate with the payment. If not specified, the default location is used.
- note string? - An optional note to be entered by the developer when creating a payment. Limit 500 characters.
- order_id string? - Associates a previously created order with this payment.
- reference_id string? - A user-defined ID to associate with the payment. You can use this field to associate the payment to an entity in an external system (for example, you might specify an order ID that is generated by a third-party shopping cart). Limit 40 characters.
- shipping_address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- source_id string - The ID for the source of funds for this payment. This can be a payment token (card nonce) generated by the Square payment form or a card on file made with the Customers API. If recording a payment that the seller received outside of Square, specify either "CASH" or "EXTERNAL". For more information, see Take Payments.
- statement_description_identifier string? - Optional additional payment information to include on the customer's card statement
as part of the statement description. This can be, for example, an invoice number, ticket number,
or short description that uniquely identifies the purchase.
Note that the
statement_description_identifier
might get truncated on the statement description to fit the required information including the Square identifier (SQ *) and name of the seller taking the payment.
- tip_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- verification_token string? - An identifying token generated by payments.verifyBuyer(). Verification tokens encapsulate customer device information and 3-D Secure challenge results to indicate that Square has verified the buyer identity. For more information, see SCA Overview.
squareup: CreatePaymentResponse
Defines the response returned by CreatePayment.
If there are errors processing the request, the payment
field might not be
present, or it might be present with a status of FAILED
.
Fields
- errors Error[]? - Information about errors encountered during the request.
- payment Payment? - Represents a payment processed by the Square API.
squareup: CreateRefundRequest
Defines the body parameters that can be included in a request to the CreateRefund endpoint.
Deprecated - recommend using RefundPayment
Fields
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- idempotency_key string - A value you specify that uniquely identifies this refund among refunds you've created for the tender. If you're unsure whether a particular refund succeeded, you can reattempt it with the same idempotency key without worrying about duplicating the refund. See Idempotency keys for more information.
- reason string? - A description of the reason for the refund.
Default value:
Refund via API
- tender_id string - The ID of the tender to refund.
A
Transaction
has one or moretenders
(i.e., methods of payment) associated with it, and you refund each tender separately with the Connect API.
squareup: CreateRefundResponse
Defines the fields that are included in the response body of a request to the CreateRefund endpoint.
One of errors
or refund
is present in a given response (never both).
Fields
- errors Error[]? - Any errors that occurred during the request.
- refund Refund? - Represents a refund processed for a Square transaction.
squareup: CreateShiftRequest
Represents a request to create a Shift
.
Fields
- idempotency_key string? - A unique string value to ensure the idempotency of the operation.
- shift Shift - A record of the hourly rate, start, and end times for a single work shift for an employee. This might include a record of the start and end times for breaks taken during the shift.
squareup: CreateShiftResponse
The response to a request to create a Shift
. The response contains
the created Shift
object and might contain a set of Error
objects if
the request resulted in errors.
Fields
- errors Error[]? - Any errors that occurred during the request.
- shift Shift? - A record of the hourly rate, start, and end times for a single work shift for an employee. This might include a record of the start and end times for breaks taken during the shift.
squareup: CreateSubscriptionRequest
Defines parameters in a CreateSubscription endpoint request.
Fields
- canceled_date string? - The date when the subscription should be canceled, in YYYY-MM-DD format (for example, 2025-02-29). This overrides the plan configuration if it comes before the date the subscription would otherwise end.
- card_id string? - The ID of the customer card to charge. If not specified, Square sends an invoice via email. For an example to create a customer and add a card on file, see Subscriptions Walkthrough.
- idempotency_key string? - A unique string that identifies this
CreateSubscription
request. If you do not provide a unique string (or provide an empty string as the value), the endpoint treats each request as independent. For more information, see Idempotency keys.
- location_id string - The ID of the location the subscription is associated with.
- plan_id string - The ID of the subscription plan created using the Catalog API. For more information, see Set Up and Manage a Subscription Plan and Subscriptions Walkthrough.
- price_override_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- start_date string? - The start date of the subscription, in YYYY-MM-DD format. For example, 2013-01-15. If the start date is left empty, the subscription begins immediately.
- tax_percentage string? - The tax to add when billing the subscription.
The percentage is expressed in decimal form, using a
'.'
as the decimal separator and without a'%'
sign. For example, a value of 7.5 corresponds to 7.5%.
- timezone string? - The timezone that is used in date calculations for the subscription. If unset, defaults to the location timezone. If a timezone is not configured for the location, defaults to "America/New_York". Format: the IANA Timezone Database identifier for the location timezone. For a list of time zones, see List of tz database time zones.
squareup: CreateSubscriptionResponse
Defines the fields that are included in the response from the CreateSubscription endpoint.
Fields
- errors Error[]? - Information about errors encountered during the request.
- subscription Subscription? - Represents a customer subscription to a subscription plan.
For an overview of the
Subscription
type, see Subscription object.
squareup: CreateTeamMemberRequest
Represents a create request for a TeamMember
object.
Fields
- idempotency_key string? - A unique string that identifies this
CreateTeamMember
request. Keys can be any valid string, but must be unique for every request. For more information, see Idempotency. The minimum length is 1 and the maximum length is 45.
- team_member TeamMember? - A record representing an individual team member for a business.
squareup: CreateTeamMemberResponse
Represents a response from a create request containing the created TeamMember
object or error messages.
Fields
- errors Error[]? - The errors that occurred during the request.
- team_member TeamMember? - A record representing an individual team member for a business.
squareup: CreateTerminalCheckoutRequest
Fields
- checkout TerminalCheckout -
- idempotency_key string - A unique string that identifies this
CreateCheckout
request. Keys can be any valid string but must be unique for everyCreateCheckout
request. See Idempotency keys for more information.
squareup: CreateTerminalCheckoutResponse
Fields
- checkout TerminalCheckout? -
- errors Error[]? - Information about errors encountered during the request.
squareup: CreateTerminalRefundRequest
Fields
- idempotency_key string - A unique string that identifies this
CreateRefund
request. Keys can be any valid string but must be unique for everyCreateRefund
request. See Idempotency keys for more information.
- refund TerminalRefund? -
squareup: CreateTerminalRefundResponse
Fields
- errors Error[]? - Information about errors encountered during the request.
- refund TerminalRefund? -
squareup: CustomAttributeFilter
Supported custom attribute query expressions for calling the SearchCatalogItems endpoint to search for items or item variations.
Fields
- bool_filter boolean? - A query expression to filter items or item variations by matching their custom attributes'
boolean_value
property values against the specified Boolean expression.
- custom_attribute_definition_id string? - A query expression to filter items or item variations by matching their custom attributes'
custom_attribute_definition_id
property value against the the specified id.
- 'key string? - A query expression to filter items or item variations by matching their custom attributes'
key
property value against the specified key.
- number_filter Range? - The range of a number value between the specified lower and upper bounds.
- selection_uids_filter string[]? - A query expression to filter items or item variations by matching their custom attributes'
selection_uid_values
values against the specified selection uids.
- string_filter string? - A query expression to filter items or item variations by matching their custom attributes'
string_value
property value against the specified text.
squareup: Customer
Represents a Square customer profile in the Customer Directory of a Square seller.
Fields
- address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- birthday string? - The birthday associated with the customer profile, in RFC 3339 format. The year is optional. The timezone and time are not allowed.
For example,
0000-09-21T00:00:00-00:00
represents a birthday on September 21 and1998-09-21T00:00:00-00:00
represents a birthday on September 21, 1998.
- cards Card[]? - Payment details of the credit, debit, and gift cards stored on file for the customer profile.
DEPRECATED at version 2021-06-16. Replaced by calling ListCards (for credit and debit cards on file)
or ListGiftCards (for gift cards on file) and including the
customer_id
query parameter. For more information, see Migrate to the Cards API and Gift Cards API.
- company_name string? - A business name associated with the customer profile.
- created_at string? - The timestamp when the customer profile was created, in RFC 3339 format.
- creation_source string? - A creation source represents the method used to create the customer profile.
- email_address string? - The email address associated with the customer profile.
- family_name string? - The family (i.e., last) name associated with the customer profile.
- given_name string? - The given (i.e., first) name associated with the customer profile.
- group_ids string[]? - The IDs of customer groups the customer belongs to.
- id string? - A unique Square-assigned ID for the customer profile.
- nickname string? - A nickname for the customer profile.
- note string? - A custom note associated with the customer profile.
- phone_number string? - The 11-digit phone number associated with the customer profile.
- preferences CustomerPreferences? - Represents communication preferences for the customer profile.
- reference_id string? - An optional second ID used to associate the customer profile with an entity in another system.
- segment_ids string[]? - The IDs of segments the customer belongs to.
- updated_at string? - The timestamp when the customer profile was last updated, in RFC 3339 format.
- 'version int? - The Square-assigned version number of the customer profile. The version number is incremented each time an update is committed to the customer profile, except for changes to customer segment membership and cards on file.
squareup: CustomerCreationSourceFilter
The creation source filter.
If one or more creation sources are set, customer profiles are included in, or excluded from, the result if they match at least one of the filter criteria.
Fields
- rule string? - Indicates whether a customer profile matching the filter criteria
should be included in the result or excluded from the result.
Default:
INCLUDE
.
- values string[]? - The list of creation sources used as filtering criteria.
squareup: CustomerFilter
Represents a set of CustomerQuery
filters used to limit the set of
customers returned by the SearchCustomers endpoint.
Fields
- created_at TimeRange? - Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
- creation_source CustomerCreationSourceFilter? - The creation source filter. If one or more creation sources are set, customer profiles are included in, or excluded from, the result if they match at least one of the filter criteria.
- email_address CustomerTextFilter? - A filter to select customers based on exact or fuzzy matching of customer attributes against a specified query. Depending on the customer attributes, the filter can be case-sensitive. This filter can be exact or fuzzy, but it cannot be both.
- group_ids FilterValue? - A filter to select resources based on an exact field value. For any given value, the value can only be in one property. Depending on the field, either all properties can be set or only a subset will be available. Refer to the documentation of the field.
- phone_number CustomerTextFilter? - A filter to select customers based on exact or fuzzy matching of customer attributes against a specified query. Depending on the customer attributes, the filter can be case-sensitive. This filter can be exact or fuzzy, but it cannot be both.
- reference_id CustomerTextFilter? - A filter to select customers based on exact or fuzzy matching of customer attributes against a specified query. Depending on the customer attributes, the filter can be case-sensitive. This filter can be exact or fuzzy, but it cannot be both.
- updated_at TimeRange? - Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
squareup: CustomerGroup
Represents a group of customer profiles.
Customer groups can be created, be modified, and have their membership defined using the Customers API or within the Customer Directory in the Square Seller Dashboard or Point of Sale.
Fields
- created_at string? - The timestamp when the customer group was created, in RFC 3339 format.
- id string? - A unique Square-generated ID for the customer group.
- name string - The name of the customer group.
- updated_at string? - The timestamp when the customer group was last updated, in RFC 3339 format.
squareup: CustomerPreferences
Represents communication preferences for the customer profile.
Fields
- email_unsubscribed boolean? - Indicates whether the customer has unsubscribed from marketing campaign emails. A value of
true
means that the customer chose to opt out of email marketing from the current Square seller or from all Square sellers. This value is read-only from the Customers API.
squareup: CustomerQuery
Represents a query (including filtering criteria, sorting criteria, or both) used to search for customer profiles.
Fields
- filter CustomerFilter? - Represents a set of
CustomerQuery
filters used to limit the set of customers returned by the SearchCustomers endpoint.
- sort CustomerSort? - Specifies how searched customers profiles are sorted, including the sort key and sort order.
squareup: CustomerSegment
Represents a group of customer profiles that match one or more predefined filter criteria.
Segments (also known as Smart Groups) are defined and created within the Customer Directory in the Square Seller Dashboard or Point of Sale.
Fields
- created_at string? - The timestamp when the segment was created, in RFC 3339 format.
- id string? - A unique Square-generated ID for the segment.
- name string - The name of the segment.
- updated_at string? - The timestamp when the segment was last updated, in RFC 3339 format.
squareup: CustomerSort
Specifies how searched customers profiles are sorted, including the sort key and sort order.
Fields
- 'field string? - Use one or more customer attributes as the sort key to sort searched customer profiles.
For example, use the creation date (
created_at
) of customers or default attributes as the sort key. Default:DEFAULT
.
- 'order string? - Indicates the order in which results should be sorted based on the
sort field value. Strings use standard alphabetic comparison
to determine order. Strings representing numbers are sorted as strings.
Default:
ASC
.
squareup: CustomerTextFilter
A filter to select customers based on exact or fuzzy matching of customer attributes against a specified query. Depending on the customer attributes, the filter can be case-sensitive. This filter can be exact or fuzzy, but it cannot be both.
Fields
- exact string? - Use the exact filter to select customers whose attributes match exactly the specified query.
- fuzzy string? - Use the fuzzy filter to select customers whose attributes match the specified query in a fuzzy manner. When the fuzzy option is used, search queries are tokenized, and then each query token must be matched somewhere in the searched attribute. For single token queries, this is effectively the same behavior as a partial match operation.
squareup: DateRange
A range defined by two dates. Used for filtering a query for Connect v2 objects that have date properties.
Fields
- end_date string? - A string in
YYYY-MM-DD
format, such as2017-10-31
, per the ISO 8601 extended format for calendar dates. The end of a date range (inclusive).
- start_date string? - A string in
YYYY-MM-DD
format, such as2017-10-31
, per the ISO 8601 extended format for calendar dates. The beginning of a date range (inclusive).
squareup: DeleteBreakTypeRequest
A request to delete a BreakType
.
squareup: DeleteBreakTypeResponse
The response to a request to delete a BreakType
. The response might contain a set
of Error
objects if the request resulted in errors.
Fields
- errors Error[]? - Any errors that occurred during the request.
squareup: DeleteCatalogObjectRequest
squareup: DeleteCatalogObjectResponse
Fields
- deleted_object_ids string[]? - The IDs of all catalog objects deleted by this request. Multiple IDs may be returned when associated objects are also deleted, for example a catalog item variation will be deleted (and its ID included in this field) when its parent catalog item is deleted.
- errors Error[]? - Any errors that occurred during the request.
squareup: DeleteCustomerCardRequest
Defines the fields that are included in requests to the
DeleteCustomerCard
endpoint.
squareup: DeleteCustomerCardResponse
Defines the fields that are included in the response body of
a request to the DeleteCustomerCard
endpoint.
Fields
- errors Error[]? - Any errors that occurred during the request.
squareup: DeleteCustomerGroupRequest
Defines the fields that can be included in a request to the DeleteCustomerGroup endpoint.
squareup: DeleteCustomerGroupResponse
Defines the fields that are included in the response body of a request to the DeleteCustomerGroup endpoint.
Fields
- errors Error[]? - Any errors that occurred during the request.
squareup: DeleteCustomerRequest
Defines the fields that are included in a request to the DeleteCustomer
endpoint.
Fields
- 'version int? - The current version of the customer profile. As a best practice, you should include this parameter to enable optimistic concurrency control. For more information, see Delete a customer profile.
squareup: DeleteCustomerResponse
Defines the fields that are included in the response body of
a request to the DeleteCustomer
endpoint.
Fields
- errors Error[]? - Any errors that occurred during the request.
squareup: DeleteDisputeEvidenceRequest
Defines the parameters for a DeleteDisputeEvidence
request.
squareup: DeleteDisputeEvidenceResponse
Defines the fields in a DeleteDisputeEvidence
response.
Fields
- errors Error[]? - Information about errors encountered during the request.
squareup: DeleteInvoiceRequest
Describes a DeleteInvoice
request.
Fields
- 'version int? - The version of the invoice to delete. If you do not know the version, you can call GetInvoice or ListInvoices.
squareup: DeleteInvoiceResponse
Describes a DeleteInvoice
response.
Fields
- errors Error[]? - Information about errors encountered during the request.
squareup: DeleteLoyaltyRewardRequest
A request to delete a loyalty reward.
squareup: DeleteLoyaltyRewardResponse
A response returned by the API call.
Fields
- errors Error[]? - Any errors that occurred during the request.
squareup: DeleteShiftRequest
A request to delete a Shift
.
squareup: DeleteShiftResponse
The response to a request to delete a Shift
. The response might contain a set of
Error
objects if the request resulted in errors.
Fields
- errors Error[]? - Any errors that occurred during the request.
squareup: DeleteSnippetRequest
Represents a DeleteSnippet
request.
squareup: DeleteSnippetResponse
Represents a DeleteSnippet
response.
Fields
- errors Error[]? - Any errors that occurred during the request.
squareup: DeprecatedCreateDisputeEvidenceFileRequest
Defines the parameters for a DeprecatedCreateDisputeEvidenceFile
request.
Fields
- content_type string? - The MIME type of the uploaded file. The type can be image/heic, image/heif, image/jpeg, application/pdf, image/png, or image/tiff.
- evidence_type string? - The type of evidence you are uploading.
- idempotency_key string - The Unique ID. For more information, see Idempotency.
squareup: DeprecatedCreateDisputeEvidenceFileResponse
Defines the fields in a DeprecatedCreateDisputeEvidenceFile
response.
Fields
- errors Error[]? - Any errors that occurred during the request.
- evidence DisputeEvidence? -
squareup: DeprecatedCreateDisputeEvidenceTextRequest
Defines the parameters for a DeprecatedCreateDisputeEvidenceText
request.
Fields
- evidence_text string - The evidence string.
- evidence_type string? - The type of evidence you are uploading.
- idempotency_key string - The Unique ID. For more information, see Idempotency.
squareup: DeprecatedCreateDisputeEvidenceTextResponse
Defines the fields in a DeprecatedCreateDisputeEvidenceText
response.
Fields
- errors Error[]? - Any errors that occurred during the request.
- evidence DisputeEvidence? -
squareup: Device
Fields
- id string? - The device's Square-issued ID.
- name string? - The device's merchant-specified name.
squareup: DeviceCheckoutOptions
Fields
- device_id string - The unique ID of the device intended for this
TerminalCheckout
. A list ofDeviceCode
objects can be retrieved from the /v2/devices/codes endpoint. Match aDeviceCode.device_id
value withdevice_id
to get the associated device code.
- skip_receipt_screen boolean? - Instructs the device to skip the receipt screen. Defaults to false.
- tip_settings TipSettings? -
squareup: DeviceCode
Fields
- code string? - The unique code that can be used to login.
- created_at string? - When this DeviceCode was created. Timestamp in RFC 3339 format.
- device_id string? - The unique id of the device that used this code. Populated when the device is paired up.
- id string? - The unique id for this device code.
- location_id string? - The location assigned to this code.
- name string? - An optional user-defined name for the device code.
- pair_by string? - When this DeviceCode will expire and no longer login. Timestamp in RFC 3339 format.
- paired_at string? - When this DeviceCode was paired. Timestamp in RFC 3339 format.
- product_type string - The targeting product type of the device code.
- status string? - The pairing status of the device code.
- status_changed_at string? - When this DeviceCode's status was last changed. Timestamp in RFC 3339 format.
squareup: DeviceDetails
Details about the device that took the payment.
Fields
- device_id string? - The Square-issued ID of the device.
- device_installation_id string? - The Square-issued installation ID for the device.
- device_name string? - The name of the device set by the seller.
squareup: DigitalWalletDetails
Additional details about WALLET
type payments. Contains only non-confidential information.
Fields
- status string? - The status of the
WALLET
payment. The status can beAUTHORIZED
,CAPTURED
,VOIDED
, orFAILED
.
squareup: DisableCardRequest
Disables the card, preventing any further updates or charges. Disabling an already disabled card is allowed but has no effect. Accessible via HTTP requests at POST https://connect.squareup.com/v2/cards/{card_id}/disable
squareup: DisableCardResponse
Defines the fields that are included in the response body of a request to the DisableCard endpoint.
Note: if there are errors processing the request, the card field will not be present.
Fields
- card Card? - Represents the payment details of a card to be used for payments. These details are determined by the payment token generated by Web Payments SDK.
- errors Error[]? - Information on errors encountered during the request.
squareup: Dispute
Represents a dispute a cardholder initiated with their bank.
Fields
- amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- brand_dispute_id string? - The ID of the dispute in the card brand system, generated by the card brand.
- card_brand string? - The card brand used in the disputed payment.
- created_at string? - The timestamp when the dispute was created, in RFC 3339 format.
- dispute_id string? - The unique ID for this
Dispute
, generated by Square.
- disputed_payment DisputedPayment? - The payment the cardholder disputed.
- due_at string? - The time when the next action is due, in RFC 3339 format.
- evidence_ids DisputeEvidenceidsItemsString[]? - The IDs of the evidence associated with the dispute.
- id string? - The unique ID for this
Dispute
, generated by Square.
- location_id string? - The ID of the location where the dispute originated.
- reason string? - The dispute reason why the cardholder initiated the dispute with their bank.
- reported_at string? - The timestamp when the dispute was reported, in RFC 3339 format.
- reported_date string? - The timestamp when the dispute was reported, in RFC 3339 format.
- state string? - The current state of this dispute.
- updated_at string? - The timestamp when the dispute was last updated, in RFC 3339 format.
- 'version int? - The current version of the
Dispute
.
squareup: DisputedPayment
The payment the cardholder disputed.
Fields
- payment_id string? - Square-generated unique ID of the payment being disputed.
squareup: DisputeEvidence
Fields
- dispute_id string? - The ID of the dispute the evidence is associated with.
- evidence_file DisputeEvidenceFile? - A file to be uploaded as dispute evidence.
- evidence_id string? - The Square-generated ID of the evidence.
- evidence_text string? - Raw text
- evidence_type string? - The type of the evidence.
- id string? - The Square-generated ID of the evidence.
- uploaded_at string? - The time when the next action is due, in RFC 3339 format.
squareup: DisputeEvidenceCreatedWebhook
Published when evidence is added to a Dispute from the Disputes Dashboard in the Seller Dashboard, the Square Point of Sale app, or by calling either CreateDisputeEvidenceFile or CreateDisputeEvidenceText.
Fields
- created_at string? - Timestamp of when the webhook event was created, in RFC 3339 format.
- event_id string? - A unique ID for the webhook event.
- location_id string? - The ID of the target location associated with the event.
- merchant_id string? - The ID of the target merchant associated with the event.
- 'type string? - The type of event this represents.
squareup: DisputeEvidenceCreatedWebhookData
Fields
- id string? - ID of the affected dispute.
- 'object DisputeEvidenceCreatedWebhookObject? -
- 'type string? - Name of the affected dispute's type.
squareup: DisputeEvidenceCreatedWebhookObject
Fields
- 'object Dispute? - Represents a dispute a cardholder initiated with their bank.
squareup: DisputeEvidenceFile
A file to be uploaded as dispute evidence.
Fields
- filename string? - The file name including the file extension. For example: "receipt.tiff".
- filetype string? - Dispute evidence files must be application/pdf, image/heic, image/heif, image/jpeg, image/png, or image/tiff formats.
squareup: Employee
An employee object that is used by the external API.
Fields
- created_at string? - A read-only timestamp in RFC 3339 format.
- email string? - The employee's email address
- first_name string? - The employee's first name.
- id string? - UUID for this object.
- is_owner boolean? - Whether this employee is the owner of the merchant. Each merchant has one owner employee, and that employee has full authority over the account.
- last_name string? - The employee's last name.
- location_ids string[]? - A list of location IDs where this employee has access to.
- phone_number string? - The employee's phone number in E.164 format, i.e. "+12125554250"
- status string? - Specifies the status of the employees being fetched.
- updated_at string? - A read-only timestamp in RFC 3339 format.
squareup: EmployeeWage
The hourly wage rate that an employee earns on a Shift
for doing the job
specified by the title
property of this object. Deprecated at version 2020-08-26. Use TeamMemberWage
instead.
Fields
- employee_id string? - The
Employee
that this wage is assigned to.
- hourly_rate Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- id string? - The UUID for this object.
- title string? - The job title that this wage relates to.
squareup: Error
Represents an error encountered during a request to the Connect API.
See Handling errors for more information.
Fields
- category string - The high-level category for the error.
- code string - The specific code of the error.
- detail string? - A human-readable description of the error for debugging purposes.
- 'field string? - The name of the field provided in the original request (if any) that the error pertains to.
squareup: ExternalPaymentDetails
Stores details about an external payment. Contains only non-confidential information. For more information, see Take External Payments.
Fields
- 'source string - A description of the external payment source. For example, "Food Delivery Service".
- source_fee_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- source_id string? - An ID to associate the payment to its originating source.
- 'type string - The type of external payment the seller received. It can be one of the following:
- CHECK - Paid using a physical check.
- BANK_TRANSFER - Paid using external bank transfer.
- OTHER_GIFT_CARD - Paid using a non-Square gift card.
- CRYPTO - Paid using a crypto currency.
- SQUARE_CASH - Paid using Square Cash App.
- SOCIAL - Paid using peer-to-peer payment applications.
- EXTERNAL - A third-party application gathered this payment outside of Square.
- EMONEY - Paid using an E-money provider.
- CARD - A credit or debit card that Square does not support.
- STORED_BALANCE - Use for house accounts, store credit, and so forth.
- FOOD_VOUCHER - Restaurant voucher provided by employers to employees to pay for meals
- OTHER - A type not listed here.
squareup: FilterValue
A filter to select resources based on an exact field value. For any given value, the value can only be in one property. Depending on the field, either all properties can be set or only a subset will be available.
Refer to the documentation of the field.
Fields
- all string[]? - A list of terms that must be present on the field of the resource.
- 'any string[]? - A list of terms where at least one of them must be present on the field of the resource.
- none string[]? - A list of terms that must not be present on the field the resource
squareup: GetBankAccountByV1IdRequest
Request object for fetching a specific BankAccount
by the object ID.
squareup: GetBankAccountByV1IdResponse
Response object returned by GetBankAccountByV1Id.
Fields
- bank_account BankAccount? - Represents a bank account. For more information about linking a bank account to a Square account, see Bank Accounts API.
- errors Error[]? - Information on errors encountered during the request.
squareup: GetBankAccountRequest
Request object to fetch a specific BankAccount
by the object ID.
squareup: GetBankAccountResponse
Response object returned by GetBankAccount
.
Fields
- bank_account BankAccount? - Represents a bank account. For more information about linking a bank account to a Square account, see Bank Accounts API.
- errors Error[]? - Information on errors encountered during the request.
squareup: GetBreakTypeRequest
A request to get a BreakType
by ID.
squareup: GetBreakTypeResponse
The response to a request to get a BreakType
. The response contains
the requested BreakType
objects and might contain a set of Error
objects if
the request resulted in errors.
Fields
- break_type BreakType? - A defined break template that sets an expectation for possible
Break
instances on aShift
.
- errors Error[]? - Any errors that occurred during the request.
squareup: GetDeviceCodeRequest
squareup: GetDeviceCodeResponse
Fields
- device_code DeviceCode? -
- errors Error[]? - Any errors that occurred during the request.
squareup: GetEmployeeWageRequest
A request to get an EmployeeWage
.
squareup: GetEmployeeWageResponse
A response to a request to get an EmployeeWage
. The response contains
the requested EmployeeWage
objects and might contain a set of Error
objects if
the request resulted in errors.
Fields
- employee_wage EmployeeWage? - The hourly wage rate that an employee earns on a
Shift
for doing the job specified by thetitle
property of this object. Deprecated at version 2020-08-26. UseTeamMemberWage
instead.
- errors Error[]? - Any errors that occurred during the request.
squareup: GetInvoiceRequest
Describes a GetInvoice
request.
squareup: GetInvoiceResponse
Describes a GetInvoice
response.
Fields
- errors Error[]? - Information about errors encountered during the request.
- invoice Invoice? - Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see Manage Invoices Using the Invoices API.
squareup: GetPaymentRefundRequest
Describes a request to retrieve a refund using GetPaymentRefund.
squareup: GetPaymentRefundResponse
Defines the response returned by GetRefund.
Note: If there are errors processing the request, the refund field might not be present or it might be present in a FAILED state.
Fields
- errors Error[]? - Information about errors encountered during the request.
- refund PaymentRefund? - Represents a refund of a payment made using Square. Contains information about the original payment and the amount of money refunded.
squareup: GetPaymentRequest
Describes a request to retrieve a payment using GetPayment.
squareup: GetPaymentResponse
Defines the response returned by GetPayment.
Fields
- errors Error[]? - Information about errors encountered during the request.
- payment Payment? - Represents a payment processed by the Square API.
squareup: GetShiftRequest
A request to get a Shift
by ID.
squareup: GetShiftResponse
A response to a request to get a Shift
. The response contains
the requested Shift
object and might contain a set of Error
objects if
the request resulted in errors.
Fields
- errors Error[]? - Any errors that occurred during the request.
- shift Shift? - A record of the hourly rate, start, and end times for a single work shift for an employee. This might include a record of the start and end times for breaks taken during the shift.
squareup: GetTeamMemberWageRequest
A request to get a TeamMemberWage
.
squareup: GetTeamMemberWageResponse
A response to a request to get a TeamMemberWage
. The response contains
the requested TeamMemberWage
objects and might contain a set of Error
objects if
the request resulted in errors.
Fields
- errors Error[]? - Any errors that occurred during the request.
- team_member_wage TeamMemberWage? - The hourly wage rate that a team member earns on a
Shift
for doing the job specified by thetitle
property of this object.
squareup: GetTerminalCheckoutRequest
squareup: GetTerminalCheckoutResponse
Fields
- checkout TerminalCheckout? -
- errors Error[]? - Information about errors encountered during the request.
squareup: GetTerminalRefundRequest
squareup: GetTerminalRefundResponse
Fields
- errors Error[]? - Information about errors encountered during the request.
- refund TerminalRefund? -
squareup: GiftCard
Represents a Square gift card.
Fields
- balance_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- created_at string? - The timestamp when the gift card was created, in RFC 3339 format.
In the case of a digital gift card, it is the time when you create a card
(using the Square Point of Sale application, Seller Dashboard, or Gift Cards API).
In the case of a plastic gift card, it is the time when Square associates the card with the seller at the time of activation.
- customer_ids GiftcardCustomeridsItemsString[]? - The IDs of the customers to whom this gift card is linked.
- gan string? - The gift card account number.
- gan_source GANSource? -
- id string? - The Square-assigned ID of the gift card.
- state Status? -
- 'type Type -
squareup: GiftCardActivity
Represents an action performed on a gift card that affects its state or balance.
Fields
- activate_activity_details GiftCardActivityActivate? - Describes a gift card activity of the ACTIVATE type.
- adjust_decrement_activity_details GiftCardActivityAdjustDecrement? - Describes a gift card activity of the ADJUST_DECREMENT type.
- adjust_increment_activity_details GiftCardActivityAdjustIncrement? - Describes a gift card activity of the ADJUST_INCREMENT type.
- block_activity_details GiftCardActivityBlock? - Describes a gift card activity of the BLOCK type.
- clear_balance_activity_details GiftCardActivityClearBalance? - Describes a gift card activity of the CLEAR_BALANCE type.
- created_at string? - The timestamp when the gift card activity was created, in RFC 3339 format.
- deactivate_activity_details GiftCardActivityDeactivate? - Describes a gift card activity of the DEACTIVATE type.
- gift_card_balance_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- gift_card_gan string? - The gift card GAN. The GAN is not required if
gift_card_id
is present.
- gift_card_id string? - The gift card ID. The ID is not required if a GAN is present.
- id string? - The unique ID of the gift card activity.
- import_activity_details GiftCardActivityImport? - Describes a gift card activity of the IMPORT type and the
GiftCardGANSource
is OTHER (a third-party gift card).
- import_reversal_activity_details GiftCardActivityImportReversal? - Present only when GiftCardActivityType is IMPORT_REVERSAL and GiftCardGANSource is OTHER
- load_activity_details GiftCardActivityLoad? - Present only when
GiftCardActivityType
is LOAD.
- location_id string - The ID of the location at which the activity occurred.
- redeem_activity_details GiftCardActivityRedeem? - Present only when
GiftCardActivityType
is REDEEM.
- refund_activity_details GiftCardActivityRefund? - Present only when
GiftCardActivityType
is REFUND.
- 'type Type -
- unblock_activity_details GiftCardActivityUnblock? - Present only when
GiftCardActivityType
is UNBLOCK.
- unlinked_activity_refund_activity_details GiftCardActivityUnlinkedActivityRefund? - Present only when
GiftCardActivityType
is UNLINKED_ACTIVITY_REFUND.
squareup: GiftCardActivityActivate
Describes a gift card activity of the ACTIVATE type.
Fields
- amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- buyer_payment_instrument_ids string[]? - Required if your application does not use the Square Orders API. This is a list of client-provided payment instrument IDs. Square uses this information to perform compliance checks. If you use the Square Orders API, Square has the necessary instrument IDs to perform necessary compliance checks.
- line_item_uid string? - The
line_item_uid
of the gift card line item in an order. This is required if your application uses the Square Orders API.
- order_id string? - The ID of the order associated with the activity. This is required if your application uses the Square Orders API.
- reference_id string? - If your application does not use the Square Orders API, you can optionally use this field to associate the gift card activity with a client-side entity.
squareup: GiftCardActivityAdjustDecrement
Describes a gift card activity of the ADJUST_DECREMENT type.
Fields
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- reason Reason -
squareup: GiftCardActivityAdjustIncrement
Describes a gift card activity of the ADJUST_INCREMENT type.
Fields
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- reason Reason -
squareup: GiftCardActivityBlock
Describes a gift card activity of the BLOCK type.
Fields
- reason Reason -
squareup: GiftCardActivityClearBalance
Describes a gift card activity of the CLEAR_BALANCE type.
Fields
- reason Reason -
squareup: GiftCardActivityDeactivate
Describes a gift card activity of the DEACTIVATE type.
Fields
- reason Reason -
squareup: GiftCardActivityImport
Describes a gift card activity of the IMPORT type and the GiftCardGANSource
is OTHER
(a third-party gift card).
Fields
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
squareup: GiftCardActivityImportReversal
Present only when GiftCardActivityType is IMPORT_REVERSAL and GiftCardGANSource is OTHER
Fields
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
squareup: GiftCardActivityLoad
Present only when GiftCardActivityType
is LOAD.
Fields
- amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- buyer_payment_instrument_ids string[]? - If you are not using the Orders API, this field is required because it is used to identify a buyer to perform compliance checks.
- line_item_uid string? - The
line_item_uid
of the gift card’s line item in the order associated with the activity. It is populated along withorder_id
and is required if using the Square Orders API.
- order_id string? - The
order_id
of the order associated with the activity. It is populated along withline_item_uid
and is required if using the Square Orders API.
- reference_id string? - A client-specified ID to associate an entity, in another system, with this gift card activity. This can be used to track the order or payment related information when the Square Orders API is not being used.
squareup: GiftCardActivityRedeem
Present only when GiftCardActivityType
is REDEEM.
Fields
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- payment_id string? - When the Square Payments API is used, Redeem is not called on the Gift Cards API.
However, when Square reads a Redeem activity from the Gift Cards API, developers need to know the
associated
payment_id
.
- reference_id string? - A client-specified ID to associate an entity, in another system, with this gift card activity. This can be used to track the order or payment related information when the Square Orders API is not being used.
squareup: GiftCardActivityRefund
Present only when GiftCardActivityType
is REFUND.
Fields
- amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- payment_id string? - When the Square Payments API is used, Refund is not called on the Gift Cards API. However, when Square reads a Refund activity from the Gift Cards API, the developer needs to know the ID of the payment (made using this gift card) that is being refunded.
- redeem_activity_id string - The ID for the Redeem activity that needs to be refunded. Hence, the activity it refers to has to be of the REDEEM type.
- reference_id string? - A client-specified ID to associate an entity, in another system, with this gift card activity. This can be used to track the order or payment related information when the Square Orders API is not being used.
squareup: GiftCardActivityUnblock
Present only when GiftCardActivityType
is UNBLOCK.
Fields
- reason Reason -
squareup: GiftCardActivityUnlinkedActivityRefund
Present only when GiftCardActivityType
is UNLINKED_ACTIVITY_REFUND.
Fields
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- payment_id string? - When using the Square Payments API, the ID of the payment that was refunded to this gift card.
- reference_id string? - A client-specified ID to associate an entity, in another system, with this gift card activity. This can be used to track the order or payment related information when the Square Payments API is not being used.
squareup: InventoryAdjustment
Represents a change in state or quantity of product inventory at a particular time and location.
Fields
- adjustment_group InventoryAdjustmentGroup? -
- catalog_object_id string? - The Square-generated ID of the CatalogObject being tracked.
- catalog_object_type string? - The type of the
CatalogObject being tracked. Tracking is only
supported for the
ITEM_VARIATION
type.
- created_at string? - An RFC 3339-formatted timestamp that indicates when the inventory adjustment is received.
- from_state string? - The inventory state of the related quantity of items before the adjustment.
- goods_receipt_id string? - The Square-generated ID of the goods receipt that caused the adjustment. Only relevant for state transitions from the Square for Retail app.
- id string? - A unique ID generated by Square for the
InventoryAdjustment
.
- occurred_at string? - A client-generated RFC 3339-formatted timestamp that indicates when
the inventory adjustment took place. For inventory adjustment updates, the
occurred_at
timestamp cannot be older than 24 hours or in the future relative to the time of the request.
- purchase_order_id string? - The Square-generated ID of the purchase order that caused the adjustment. Only relevant for state transitions from the Square for Retail app.
- quantity string? - The number of items affected by the adjustment as a decimal string. Can support up to 5 digits after the decimal point.
- reference_id string? - An optional ID provided by the application to tie the
InventoryAdjustment
to an external system.
- refund_id string? - The Square-generated ID of the [Refund][#type-refund] that caused the adjustment. Only relevant for refund-related state transitions.
- 'source SourceApplication? - Provides information about the application used to generate a change.
- to_state string? - The inventory state of the related quantity of items after the adjustment.
- total_price_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- transaction_id string? - The Square-generated ID of the [Transaction][#type-transaction] that caused the adjustment. Only relevant for payment-related state transitions.
squareup: InventoryAdjustmentGroup
Fields
- from_state string? - Representative
from_state
for adjustments within the group. For example, for a group adjustment fromIN_STOCK
toSOLD
, there can be two component adjustments in the group: one fromIN_STOCK
toCOMPOSED
and the other one fromCOMPOSED
toSOLD
. Here, the representativefrom_state
for theInventoryAdjustmentGroup
isIN_STOCK
.
- id string? - A unique ID generated by Square for the
InventoryAdjustmentGroup
.
- root_adjustment_id string? - The inventory adjustment of the composed variation.
- to_state string? - Representative
to_state
for adjustments within group. For example, for a group adjustment fromIN_STOCK
toSOLD
, the two component adjustments in the group can be fromIN_STOCK
toCOMPOSED
and fromCOMPOSED
toSOLD
. Here, the representativeto_state
of theInventoryAdjustmentGroup
isSOLD
.
squareup: InventoryChange
Represents a single physical count, inventory, adjustment, or transfer that is part of the history of inventory changes for a particular CatalogObject instance.
Fields
- adjustment InventoryAdjustment? - Represents a change in state or quantity of product inventory at a particular time and location.
- measurement_unit CatalogMeasurementUnit? - Represents the unit used to measure a
CatalogItemVariation
and specifies the precision for decimal quantities.
- measurement_unit_id string? - The ID of the CatalogMeasurementUnit object representing the catalog measurement unit associated with the inventory change.
- physical_count 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. For example, a physical count might come from an employee counting the item variations on hand or from syncing with an external system.
- transfer InventoryTransfer? - Represents the transfer of a quantity of product inventory at a particular time from one location to another.
- 'type string? - Indicates how the inventory change is applied. See InventoryChangeType for all possible values.
squareup: InventoryCount
Represents Square-estimated quantity of items in a particular state at a particular seller location based on the known history of physical counts and inventory adjustments.
Fields
- calculated_at string? - An RFC 3339-formatted timestamp that indicates when the most recent physical count or adjustment affecting the estimated count is received.
- catalog_object_id string? - The Square-generated ID of the CatalogObject being tracked.
- catalog_object_type string? - The type of the
CatalogObject being tracked. Tracking is only
supported for the
ITEM_VARIATION
type.
- is_estimated boolean? - Whether the inventory count is for composed variation (TRUE) or not (FALSE). If true, the inventory count will not be present in the response of any of these endpoints: BatchChangeInventory, BatchRetrieveInventoryChanges, BatchRetrieveInventoryCounts, and RetrieveInventoryChanges.
- quantity string? - The number of items affected by the estimated count as a decimal string. Can support up to 5 digits after the decimal point.
- state string? - The current inventory state for the related quantity of items.
squareup: 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. For example, a physical count might come from an employee counting the item variations on hand or from syncing with an external system.
Fields
- catalog_object_id string? - The Square-generated ID of the CatalogObject being tracked.
- catalog_object_type string? - The type of the
CatalogObject being tracked. Tracking is only
supported for the
ITEM_VARIATION
type.
- created_at string? - An RFC 3339-formatted timestamp that indicates when the physical count is received.
- id string? - A unique Square-generated ID for the InventoryPhysicalCount.
- occurred_at string? - A client-generated RFC 3339-formatted timestamp that indicates when
the physical count was examined. For physical count updates, the
occurred_at
timestamp cannot be older than 24 hours or in the future relative to the time of the request.
- quantity string? - The number of items affected by the physical count as a decimal string. The number can support up to 5 digits after the decimal point.
- reference_id string? - An optional ID provided by the application to tie the InventoryPhysicalCount to an external system.
- 'source SourceApplication? - Provides information about the application used to generate a change.
- state string? - The current inventory state for the related quantity of items.
squareup: InventoryTransfer
Represents the transfer of a quantity of product inventory at a particular time from one location to another.
Fields
- catalog_object_id string? - The Square-generated ID of the CatalogObject being tracked.
- catalog_object_type string? - The type of the
CatalogObject being tracked.Tracking is only
supported for the
ITEM_VARIATION
type.
- created_at string? - An RFC 3339-formatted timestamp that indicates when Square received the transfer request.
- id string? - A unique ID generated by Square for the
InventoryTransfer
.
- occurred_at string? - A client-generated RFC 3339-formatted timestamp that indicates when
the transfer took place. For write actions, the
occurred_at
timestamp cannot be older than 24 hours or in the future relative to the time of the request.
- quantity string? - The number of items affected by the transfer as a decimal string. Can support up to 5 digits after the decimal point.
- reference_id string? - An optional ID provided by the application to tie the
InventoryTransfer
to an external system.
- 'source SourceApplication? - Provides information about the application used to generate a change.
- state string? - The inventory state for the quantity of items being transferred.
squareup: Invoice
Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see Manage Invoices Using the Invoices API.
Fields
- accepted_payment_methods InvoiceAcceptedPaymentMethods? - The payment methods that customers can use to pay an invoice on the Square-hosted invoice page.
- created_at string? - The timestamp when the invoice was created, in RFC 3339 format.
- custom_fields InvoiceCustomField[]? - Additional seller-defined fields to render on the invoice. These fields are visible to sellers and buyers on the Square-hosted invoice page and in emailed or PDF copies of invoices. For more information, see Custom fields. Adding custom fields to an invoice requires an Invoices Plus subscription. Max: 2 custom fields
- delivery_method InvoiceDeliveryMethodinvoicedeliverymethod? -
- description string? - The description of the invoice. This is visible to the customer receiving the invoice.
- id string? - The Square-assigned ID of the invoice.
- invoice_number string? - A user-friendly invoice number. The value is unique within a location. If not provided when creating an invoice, Square assigns a value. It increments from 1 and padded with zeros making it 7 characters long (for example, 0000001 and 0000002).
- location_id string? - The ID of the location that this invoice is associated with.
If specified in a
CreateInvoice
request, the value must match thelocation_id
of the associated order.
- next_payment_amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- order_id string? - The ID of the order for which the invoice is created.
This field is required when creating an invoice, and the order must be in the
OPEN
state. To view the line items and other information for the associated order, call the RetrieveOrder endpoint using the order ID.
- payment_requests InvoicePaymentRequest[]? - The payment schedule for the invoice, represented by one or more payment requests that
define payment settings, such as amount due and due date. An invoice supports the following payment request combinations:
- One balance
- One deposit with one balance
- 2–12 installments
- One deposit with 2–12 installments
INSTALLMENT
payment requests to an invoice requires an Invoices Plus subscription.
- primary_recipient InvoiceRecipient? - Provides customer data that Square uses to deliver an invoice.
- public_url string? - The URL of the Square-hosted invoice page.
After you publish the invoice using the
PublishInvoice
endpoint, Square hosts the invoice page and returns the page URL in the response.
- scheduled_at string? - The timestamp when the invoice is scheduled for processing, in RFC 3339 format. After the invoice is published, Square processes the invoice on the specified date, according to the delivery method and payment request settings. If the field is not set, Square processes the invoice immediately after it is published.
- status string? - The status of the invoice.
- subscription_id string? - The ID of the subscription associated with the invoice. This field is present only on subscription billing invoices.
- timezone string? - The time zone used to interpret calendar dates on the invoice, such as
due_date
. When an invoice is created, this field is set to thetimezone
specified for the seller location. The value cannot be changed. For example, a paymentdue_date
of 2021-03-09 with atimezone
of America/Los_Angeles becomes overdue at midnight on March 9 in America/Los_Angeles (which equals a UTC timestamp of 2021-03-10T08:00:00Z).
- title string? - The title of the invoice.
- updated_at string? - The timestamp when the invoice was last updated, in RFC 3339 format.
- 'version int? - The Square-assigned version number, which is incremented each time an update is committed to the invoice.
squareup: InvoiceAcceptedPaymentMethods
The payment methods that customers can use to pay an invoice on the Square-hosted invoice page.
Fields
- bank_account boolean? - Indicates whether bank transfer payments are accepted. The default value is
false
. This option is allowed only for invoices that have a single payment request of typeBALANCE
.
- card boolean? - Indicates whether credit card or debit card payments are accepted. The default value is
false
.
- square_gift_card boolean? - Indicates whether Square gift card payments are accepted. The default value is
false
.
squareup: InvoiceCustomField
An additional seller-defined and customer-facing field to include on the invoice. For more information, see Custom fields.
Adding custom fields to an invoice requires an Invoices Plus subscription.
Fields
- label string? - The label or title of the custom field. This field is required for a custom field.
- placement string? - The location of the custom field on the invoice. This field is required for a custom field.
- value string? - The text of the custom field. If omitted, only the label is rendered.
squareup: InvoiceFilter
Describes query filters to apply.
Fields
- customer_ids string[]? - Limits the search to the specified customers, within the specified locations. Specifying a customer is optional. In the current implementation, a maximum of one customer can be specified.
- location_ids string[] - Limits the search to the specified locations. A location is required. In the current implementation, only one location can be specified.
squareup: InvoicePaymentReminder
Describes a payment request reminder (automatic notification) that Square sends
to the customer. You configure a reminder relative to the payment request
due_date
.
Fields
- message string? - The reminder message.
- relative_scheduled_days int? - The number of days before (a negative number) or after (a positive number)
the payment request
due_date
when the reminder is sent. For example, -3 indicates that the reminder should be sent 3 days before the payment requestdue_date
.
- sent_at string? - If sent, the timestamp when the reminder was sent, in RFC 3339 format.
- status string? - The status of the reminder.
- uid string? - A Square-assigned ID that uniquely identifies the reminder within the
InvoicePaymentRequest
.
squareup: InvoicePaymentRequest
Represents a payment request for an invoice. Invoices can specify a maximum
of 13 payment requests, with up to 12 INSTALLMENT
request types. For more information,
see Payment requests.
Adding INSTALLMENT
payment requests to an invoice requires an
Invoices Plus subscription.
Fields
- automatic_payment_source string? - The payment method for an automatic payment.
The default value is
NONE
.
- computed_amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- due_date string? - The due date (in the invoice's time zone) for the payment request, in
YYYY-MM-DD
format. This field is required to create a payment request. After this date, the invoice becomes overdue. For example, a paymentdue_date
of 2021-03-09 with atimezone
of America/Los_Angeles becomes overdue at midnight on March 9 in America/Los_Angeles (which equals a UTC timestamp of 2021-03-10T08:00:00Z).
- fixed_amount_requested_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- percentage_requested string? - Specifies the amount for the payment request in percentage:
- When the payment
request_type
isDEPOSIT
, it is the percentage of the order's total amount. - When the payment
request_type
isINSTALLMENT
, it is the percentage of the order's total less the deposit, if requested. The sum of thepercentage_requested
in all installment payment requests must be equal to 100.
request_type
isBALANCE
or when the payment request specifies thefixed_amount_requested_money
field. - When the payment
- reminders InvoicePaymentReminder[]? - A list of one or more reminders to send for the payment request.
- request_method string? - Indicates how Square processes the payment request. DEPRECATED at version 2021-01-21. Replaced by the
Invoice.delivery_method
andInvoicePaymentRequest.automatic_payment_source
fields. One of the following is required when creating an invoice:- (Recommended) The
delivery_method
field of the invoice. To configure an automatic payment, theautomatic_payment_source
field of the payment request is also required. - This
request_method
field. Note thatinvoice
objects returned in responses do not includerequest_method
.
- (Recommended) The
- request_type string? - Identifies the payment request type. This type defines how the payment request amount is determined. This field is required to create a payment request.
- rounding_adjustment_included_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- tipping_enabled boolean? - If set to true, the Square-hosted invoice page (the
public_url
field of the invoice) provides a place for the customer to pay a tip. This field is allowed only on the final payment request
and the paymentrequest_type
must beBALANCE
orINSTALLMENT
.
- total_completed_amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
squareup: InvoiceQuery
Describes query criteria for searching invoices.
Fields
- filter InvoiceFilter - Describes query filters to apply.
- sort InvoiceSort? - Identifies the sort field and sort order.
squareup: InvoiceRecipient
Provides customer data that Square uses to deliver an invoice.
Fields
- address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- company_name string? - The name of the recipient's company.
- customer_id string? - The ID of the customer. This is the customer profile ID that you provide when creating a draft invoice.
- email_address string? - The recipient's email address.
- family_name string? - The recipient's family (that is, last) name.
- given_name string? - The recipient's given (that is, first) name.
- phone_number string? - The recipient's phone number.
squareup: InvoiceSort
Identifies the sort field and sort order.
Fields
- 'field string - The field to use for sorting.
- 'order string? - The order to use for sorting the results.
squareup: ItemVariationLocationOverrides
Price and inventory alerting overrides for a CatalogItemVariation
at a specific Location
.
Fields
- inventory_alert_threshold int? - If the inventory quantity for the variation is less than or equal to this value and
inventory_alert_type
isLOW_QUANTITY
, the variation displays an alert in the merchant dashboard. This value is always an integer.
- inventory_alert_type string? - Indicates whether the
CatalogItemVariation
displays an alert when its inventory quantity is less than or equal to itsinventory_alert_threshold
.
- location_id string? - The ID of the
Location
. This can include locations that are deactivated.
- price_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- pricing_type string? - The pricing type (fixed or variable) for the
CatalogItemVariation
at the givenLocation
.
- track_inventory boolean? - If
true
, inventory tracking is active for theCatalogItemVariation
at thisLocation
.
squareup: JobAssignment
An object describing a job that a team member is assigned to.
Fields
- annual_rate Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- hourly_rate Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- job_title string - The title of the job.
- pay_type string - The current pay type for the job assignment used to calculate the pay amount in a pay period.
- weekly_hours int? - The planned hours per week for the job. Set if the job
PayType
isSALARY
.
squareup: LinkCustomerToGiftCardRequest
A request to link a customer to a gift card
Fields
- customer_id string - The ID of the customer to be linked.
squareup: LinkCustomerToGiftCardResponse
A response that contains one GiftCard
that was linked. The response might contain a set of Error
objects if the request resulted in errors.
Fields
- errors Error[]? - Any errors that occurred during the request.
- gift_card GiftCard? - Represents a Square gift card.
squareup: ListBankAccountsRequest
Request object for fetching all BankAccount
objects linked to a account.
Fields
- cursor string? - The pagination cursor returned by a previous call to this endpoint.
Use it in the next
ListBankAccounts
request to retrieve the next set of results. See the Pagination guide for more information.
- 'limit int? - Upper limit on the number of bank accounts to return in the response. Currently, 1000 is the largest supported limit. You can specify a limit of up to 1000 bank accounts. This is also the default limit.
- location_id string? - Location ID. You can specify this optional filter to retrieve only the linked bank accounts belonging to a specific location.
squareup: ListBankAccountsResponse
Response object returned by ListBankAccounts.
Fields
- bank_accounts BankAccount[]? - List of BankAccounts associated with this account.
- cursor string? - When a response is truncated, it includes a cursor that you can use in a subsequent request to fetch next set of bank accounts. If empty, this is the final response. For more information, see Pagination.
- errors Error[]? - Information on errors encountered during the request.
squareup: ListBreakTypesRequest
A request for a filtered set of BreakType
objects.
Fields
- cursor string? - A pointer to the next page of
BreakType
results to fetch.
- 'limit int? - The maximum number of
BreakType
results to return per page. The number can range between 1 and 200. The default is 200.
- location_id string? - Filter the returned
BreakType
results to only those that are associated with the specified location.
squareup: ListBreakTypesResponse
The response to a request for a set of BreakType
objects. The response contains
the requested BreakType
objects and might contain a set of Error
objects if
the request resulted in errors.
Fields
- break_types BreakType[]? - A page of
BreakType
results.
- cursor string? - The value supplied in the subsequent request to fetch the next page
of
BreakType
results.
- errors Error[]? - Any errors that occurred during the request.
squareup: ListCardsRequest
Retrieves details for a specific Card. Accessible via HTTP requests at GET https://connect.squareup.com/v2/cards
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See Pagination for more information.
- customer_id string? - Limit results to cards associated with the customer supplied. By default, all cards owned by the merchant are returned.
- include_disabled boolean? - Includes disabled cards. By default, all enabled cards owned by the merchant are returned.
- reference_id string? - Limit results to cards associated with the reference_id supplied.
- sort_order string? - Sorts the returned list by when the card was created with the specified order. This field defaults to ASC.
squareup: ListCardsResponse
Defines the fields that are included in the response body of a request to the ListCards endpoint.
Note: if there are errors processing the request, the card field will not be present.
Fields
- cards Card[]? - The requested list of
Card
s.
- cursor string? - The pagination cursor to be used in a subsequent request. If empty, this is the final response. See Pagination for more information.
- errors Error[]? - Information on errors encountered during the request.
squareup: ListCashDrawerShiftEventsRequest
Fields
- cursor string? - Opaque cursor for fetching the next page of results.
- 'limit int? - Number of resources to be returned in a page of results (200 by default, 1000 max).
- location_id string - The ID of the location to list cash drawer shifts for.
squareup: ListCashDrawerShiftEventsResponse
Fields
- cursor string? - Opaque cursor for fetching the next page. Cursor is not present in the last page of results.
- errors Error[]? - Any errors that occurred during the request.
- events CashDrawerShiftEvent[]? - All of the events (payments, refunds, etc.) for a cash drawer during the shift.
squareup: ListCashDrawerShiftsRequest
Fields
- begin_time string? - The inclusive start time of the query on opened_at, in ISO 8601 format.
- cursor string? - Opaque cursor for fetching the next page of results.
- end_time string? - The exclusive end date of the query on opened_at, in ISO 8601 format.
- 'limit int? - Number of cash drawer shift events in a page of results (200 by default, 1000 max).
- location_id string - The ID of the location to query for a list of cash drawer shifts.
- sort_order string? - The order in which cash drawer shifts are listed in the response, based on their opened_at field. Default value: ASC
squareup: ListCashDrawerShiftsResponse
Fields
- cursor string? - Opaque cursor for fetching the next page of results. Cursor is not present in the last page of results.
- errors Error[]? - Any errors that occurred during the request.
- items CashDrawerShiftSummary[]? - A collection of CashDrawerShiftSummary objects for shifts that match the query.
squareup: ListCatalogRequest
Fields
- catalog_version int? - The specific version of the catalog objects to be included in the response.
This allows you to retrieve historical
versions of objects. The specified version value is matched against
the CatalogObjects'
version
attribute.
- cursor string? - The pagination cursor returned in the previous response. Leave unset for an initial request. The page size is currently set to be 100. See Pagination for more information.
- types string? - An optional case-insensitive, comma-separated list of object types to retrieve.
The valid values are defined in the CatalogObjectType enum, including
ITEM
,ITEM_VARIATION
,CATEGORY
,DISCOUNT
,TAX
,MODIFIER
,MODIFIER_LIST
, orIMAGE
. If this is unspecified, the operation returns objects of all the types at the version of the Square API used to make the request.
squareup: ListCatalogResponse
Fields
- cursor string? - The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Pagination for more information.
- errors Error[]? - Any errors that occurred during the request.
- objects CatalogObject[]? - The CatalogObjects returned.
squareup: ListCustomerGroupsRequest
Defines the query parameters that can be included in a request to the ListCustomerGroups endpoint.
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see Pagination.
- 'limit int? - The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. The limit is ignored if it is less than 1 or greater than 50. The default value is 50. For more information, see Pagination.
squareup: ListCustomerGroupsResponse
Defines the fields that are included in the response body of a request to the ListCustomerGroups endpoint.
Either errors
or groups
is present in a given response (never both).
Fields
- cursor string? - A pagination cursor to retrieve the next set of results for your original query to the endpoint. This value is present only if the request succeeded and additional results are available. For more information, see Pagination.
- errors Error[]? - Any errors that occurred during the request.
- groups CustomerGroup[]? - A list of customer groups belonging to the current seller.
squareup: ListCustomerSegmentsRequest
Defines the valid parameters for requests to the ListCustomerSegments
endpoint.
Fields
- cursor string? - A pagination cursor returned by previous calls to
ListCustomerSegments
. This cursor is used to retrieve the next set of query results. For more information, see Pagination.
- 'limit int? - The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. The limit is ignored if it is less than 1 or greater than 50. The default value is 50. For more information, see Pagination.
squareup: ListCustomerSegmentsResponse
Defines the fields that are included in the response body for requests to the ListCustomerSegments
endpoint.
Either errors
or segments
is present in a given response (never both).
Fields
- cursor string? - A pagination cursor to be used in subsequent calls to
ListCustomerSegments
to retrieve the next set of query results. The cursor is only present if the request succeeded and additional results are available. For more information, see Pagination.
- errors Error[]? - Any errors that occurred during the request.
- segments CustomerSegment[]? - The list of customer segments belonging to the associated Square account.
squareup: ListCustomersRequest
Defines the query parameters that can be included in a request to the
ListCustomers
endpoint.
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see Pagination.
- 'limit int? - The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. The limit is ignored if it is less than 1 or greater than 100. The default value is 100. For more information, see Pagination.
- sort_field string? - Indicates how customers should be sorted.
The default value is
DEFAULT
.
- sort_order string? - Indicates whether customers should be sorted in ascending (
ASC
) or descending (DESC
) order. The default value isASC
.
squareup: ListCustomersResponse
Defines the fields that are included in the response body of
a request to the ListCustomers
endpoint.
Either errors
or customers
is present in a given response (never both).
Fields
- cursor string? - A pagination cursor to retrieve the next set of results for the original query. A cursor is only present if the request succeeded and additional results are available. For more information, see Pagination.
- customers Customer[]? - An array of
Customer
objects that match the provided query.
- errors Error[]? - Any errors that occurred during the request.
squareup: ListDeviceCodesRequest
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See Paginating results for more information.
- location_id string? - If specified, only returns DeviceCodes of the specified location. Returns DeviceCodes of all locations if empty.
- product_type string? - If specified, only returns DeviceCodes targeting the specified product type. Returns DeviceCodes of all product types if empty.
- status string[]? - If specified, returns DeviceCodes with the specified statuses.
Returns DeviceCodes of status
PAIRED
andUNPAIRED
if empty.
squareup: ListDeviceCodesResponse
Fields
- cursor string? - A pagination cursor to retrieve the next set of results for your original query to the endpoint. This value is present only if the request succeeded and additional results are available. See Paginating results for more information.
- device_codes DeviceCode[]? - The queried DeviceCode.
- errors Error[]? - Any errors that occurred during the request.
squareup: ListDisputeEvidenceRequest
Defines the parameters for a ListDisputeEvidence
request.
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see Pagination.
squareup: ListDisputeEvidenceResponse
Defines the fields in a ListDisputeEvidence
response.
Fields
- cursor string? - The pagination cursor to be used in a subsequent request. If unset, this is the final response. For more information, see Pagination.
- errors Error[]? - Information about errors encountered during the request.
- evidence DisputeEvidence[]? - The list of evidence previously uploaded to the specified dispute.
squareup: ListDisputesRequest
Defines the request parameters for the ListDisputes
endpoint.
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see Pagination.
- location_id string? - The ID of the location for which to return a list of disputes. If not specified, the endpoint returns
all open disputes (the dispute status is not
INQUIRY_CLOSED
,WON
, orLOST
) associated with all locations.
- states string[]? - The dispute states to filter the result.
If not specified, the endpoint returns all open disputes (the dispute status is not
INQUIRY_CLOSED
,WON
, orLOST
).
squareup: ListDisputesResponse
Defines fields in a ListDisputes
response.
Fields
- cursor string? - The pagination cursor to be used in a subsequent request. If unset, this is the final response. For more information, see Pagination.
- disputes Dispute[]? - The list of disputes.
- errors Error[]? - Information about errors encountered during the request.
squareup: ListEmployeesRequest
Fields
- cursor string? - The token required to retrieve the specified page of results.
- 'limit int? - The number of employees to be returned on each page.
- location_id string? -
- status string? - Specifies the EmployeeStatus to filter the employee by.
squareup: ListEmployeesResponse
Fields
- cursor string? - The token to be used to retrieve the next page of results.
- employees Employee[]? -
- errors Error[]? - Any errors that occurred during the request.
squareup: ListEmployeeWagesRequest
A request for a set of EmployeeWage
objects.
Fields
- cursor string? - A pointer to the next page of
EmployeeWage
results to fetch.
- employee_id string? - Filter the returned wages to only those that are associated with the specified employee.
- 'limit int? - The maximum number of
EmployeeWage
results to return per page. The number can range between 1 and 200. The default is 200.
squareup: ListEmployeeWagesResponse
The response to a request for a set of EmployeeWage
objects. The response contains
a set of EmployeeWage
objects.
Fields
- cursor string? - The value supplied in the subsequent request to fetch the next page
of
EmployeeWage
results.
- employee_wages EmployeeWage[]? - A page of
EmployeeWage
results.
- errors Error[]? - Any errors that occurred during the request.
squareup: ListGiftCardActivitiesRequest
Returns a list of gift card activities. You can optionally specify a filter to retrieve a subset of activites.
Fields
- begin_time string? - The timestamp for the beginning of the reporting period, in RFC 3339 format. Inclusive. Default: The current time minus one year.
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If you do not provide the cursor, the call returns the first page of the results.
- end_time string? - The timestamp for the end of the reporting period, in RFC 3339 format. Inclusive. Default: The current time.
- gift_card_id string? - If you provide a gift card ID, the endpoint returns activities that belong to the specified gift card. Otherwise, the endpoint returns all gift card activities for the seller.
- 'limit int? - If you provide a limit value, the endpoint returns the specified number of results (or less) per page. A maximum value is 100. The default value is 50.
- location_id string? - If you provide a location ID, the endpoint returns gift card activities for that location. Otherwise, the endpoint returns gift card activities for all locations.
- sort_order string? - The order in which the endpoint returns the activities, based on
created_at
.ASC
- Oldest to newest.DESC
- Newest to oldest (default).
- 'type string? - If you provide a type, the endpoint returns gift card activities of this type. Otherwise, the endpoint returns all types of gift card activities.
squareup: ListGiftCardActivitiesResponse
A response that contains one or more GiftCardActivity
. The response might contain a set of Error
objects
if the request resulted in errors.
Fields
- cursor string? - When a response is truncated, it includes a cursor that you can use in a subsequent request to fetch the next set of activities. If empty, this is the final response.
- errors Error[]? - Any errors that occurred during the request.
- gift_card_activities GiftCardActivity[]? - Gift card activities retrieved.
squareup: ListGiftCardsRequest
A request to list gift cards. You can optionally specify a filter to retrieve a subset of gift cards.
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, it returns the first page of the results. For more information, see Pagination.
- customer_id string? - If a value is provided, returns only the gift cards linked to the specified customer
- 'limit int? - If a value is provided, it returns only that number of results per page. The maximum number of results allowed per page is 50. The default value is 30.
- state string? - If the state is provided, it returns the gift cards in the specified state (see GiftCardStatus). Otherwise, it returns the gift cards of all states.
- 'type string? - If a type is provided, gift cards of this type are returned (see GiftCardType). If no type is provided, it returns gift cards of all types.
squareup: ListGiftCardsResponse
A response that contains one or more GiftCard
. The response might contain a set of Error
objects if the request resulted in errors.
Fields
- cursor string? - When a response is truncated, it includes a cursor that you can use in a subsequent request to fetch the next set of gift cards. If empty, this is the final response.
- errors Error[]? - Any errors that occurred during the request.
- gift_cards GiftCard[]? - Gift cards retrieved.
squareup: ListInvoicesRequest
Describes a ListInvoice
request.
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see Pagination.
- 'limit int? - The maximum number of invoices to return (200 is the maximum
limit
). If not provided, the server uses a default limit of 100 invoices.
- location_id string - The ID of the location for which to list invoices.
squareup: ListInvoicesResponse
Describes a ListInvoice
response.
Fields
- cursor string? - When a response is truncated, it includes a cursor that you can use in a subsequent request to retrieve the next set of invoices. If empty, this is the final response. For more information, see Pagination.
- errors Error[]? - Information about errors encountered during the request.
- invoices Invoice[]? - The invoices retrieved.
squareup: ListLocationsRequest
Defines the fields that are included in requests to the ListLocations endpoint.
squareup: ListLocationsResponse
Defines the fields that are included in the response body of a request to the ListLocations endpoint.
One of errors
or locations
is present in a given response (never both).
Fields
- errors Error[]? - Any errors that occurred during the request.
- locations Location[]? - The business locations.
squareup: ListLoyaltyProgramsRequest
A request to list LoyaltyProgram
.
squareup: ListLoyaltyProgramsResponse
A response that contains all loyalty programs.
Fields
- errors Error[]? - Any errors that occurred during the request.
- programs LoyaltyProgram[]? - A list of
LoyaltyProgram
for the merchant.
squareup: ListMerchantsRequest
Request object for the ListMerchant endpoint.
Fields
- cursor int? - The cursor generated by the previous response.
squareup: ListMerchantsResponse
The response object returned by the ListMerchant endpoint.
Fields
- cursor int? - If the response is truncated, the cursor to use in next request to fetch next set of objects.
- errors Error[]? - Information on errors encountered during the request.
- merchant Merchant[]? - The requested
Merchant
entities.
squareup: ListPaymentRefundsRequest
Describes a request to list refunds using ListPaymentRefunds.
The maximum results per page is 100.
Fields
- begin_time string? - The timestamp for the beginning of the requested reporting period, in RFC 3339 format. Default: The current time minus one year.
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see Pagination.
- end_time string? - The timestamp for the end of the requested reporting period, in RFC 3339 format. Default: The current time.
- 'limit int? - The maximum number of results to be returned in a single page. It is possible to receive fewer results than the specified limit on a given page. If the supplied value is greater than 100, no more than 100 results are returned. Default: 100
- location_id string? - Limit results to the location supplied. By default, results are returned for all locations associated with the seller.
- sort_order string? - The order in which results are listed:
ASC
- Oldest to newest.DESC
- Newest to oldest (default).
- source_type string? - If provided, only refunds with the given source type are returned.
CARD
- List refunds only for payments whereCARD
was specified as the payment source.
- status string? - If provided, only refunds with the given status are returned. For a list of refund status values, see PaymentRefund. Default: If omitted, refunds are returned regardless of their status.
squareup: ListPaymentRefundsResponse
Defines the response returned by ListPaymentRefunds.
Either errors
or refunds
is present in a given response (never both).
Fields
- cursor string? - The pagination cursor to be used in a subsequent request. If empty, this is the final response. For more information, see Pagination.
- errors Error[]? - Information about errors encountered during the request.
- refunds PaymentRefund[]? - The list of requested refunds.
squareup: ListPaymentsRequest
Describes a request to list payments using ListPayments.
The maximum results per page is 100.
Fields
- begin_time string? - The timestamp for the beginning of the reporting period, in RFC 3339 format. Inclusive. Default: The current time minus one year.
- card_brand string? - The brand of the payment card (for example, VISA).
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. For more information, see Pagination.
- end_time string? - The timestamp for the end of the reporting period, in RFC 3339 format. Default: The current time.
- last_4 string? - The last four digits of a payment card.
- 'limit int? - The maximum number of results to be returned in a single page.
It is possible to receive fewer results than the specified limit on a given page.
The default value of 100 is also the maximum allowed value. If the provided value is
greater than 100, it is ignored and the default value is used instead.
Default:
100
- location_id string? - Limit results to the location supplied. By default, results are returned for the default (main) location associated with the seller.
- sort_order string? - The order in which results are listed:
ASC
- Oldest to newest.DESC
- Newest to oldest (default).
- total int? - The exact amount in the
total_money
for a payment.
squareup: ListPaymentsResponse
Defines the response returned by ListPayments.
Fields
- cursor string? - The pagination cursor to be used in a subsequent request. If empty, this is the final response. For more information, see Pagination.
- errors Error[]? - Information about errors encountered during the request.
- payments Payment[]? - The requested list of payments.
squareup: ListRefundsRequest
Defines the query parameters that can be included in a request to the ListRefunds endpoint.
Deprecated - recommend using SearchOrders
Fields
- begin_time string? - The beginning of the requested reporting period, in RFC 3339 format. See Date ranges for details on date inclusivity/exclusivity. Default value: The current time minus one year.
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See Paginating results for more information.
- end_time string? - The end of the requested reporting period, in RFC 3339 format. See Date ranges for details on date inclusivity/exclusivity. Default value: The current time.
- sort_order string? - The order in which results are listed in the response (
ASC
for oldest first,DESC
for newest first). Default value:DESC
squareup: ListRefundsResponse
Defines the fields that are included in the response body of a request to the ListRefunds endpoint.
One of errors
or refunds
is present in a given response (never both).
Fields
- cursor string? - A pagination cursor for retrieving the next set of results,
if any remain. Provide this value as the
cursor
parameter in a subsequent request to this endpoint. See Paginating results for more information.
- errors Error[]? - Any errors that occurred during the request.
- refunds Refund[]? - An array of refunds that match your query.
squareup: ListSitesRequest
Represents a ListSites
request.
squareup: ListSitesResponse
Represents a ListSites
response. The response can include either sites
or errors
.
Fields
- errors Error[]? - Any errors that occurred during the request.
- sites Site[]? - The sites that belong to the seller.
squareup: ListSubscriptionEventsRequest
Defines parameters in a ListSubscriptionEvents endpoint request.
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. For more information, see Pagination.
- 'limit int? - The upper limit on the number of subscription events to return
in the response.
Default:
200
squareup: ListSubscriptionEventsResponse
Defines the fields that are included in the response from the ListSubscriptionEvents endpoint.
Fields
- cursor string? - When a response is truncated, it includes a cursor that you can use in a subsequent request to fetch the next set of events. If empty, this is the final response. For more information, see Pagination.
- errors Error[]? - Information about errors encountered during the request.
- subscription_events SubscriptionEvent[]? - The
SubscriptionEvents
retrieved.
squareup: ListTeamMemberBookingProfilesRequest
Fields
- bookable_only boolean? - Indicates whether to include only bookable team members in the returned result (
true
) or not (false
).
- cursor string? - The cursor for paginating through the results.
- 'limit int? - The maximum number of results to return.
- location_id string? - Indicates whether to include only team members enabled at the given location in the returned result.
squareup: ListTeamMemberBookingProfilesResponse
Fields
- cursor string? - The cursor for paginating through the results.
- errors Error[]? - Any errors that occurred during the request.
- team_member_booking_profiles TeamMemberBookingProfile[]? - The list of team member booking profiles.
squareup: ListTeamMemberWagesRequest
A request for a set of TeamMemberWage
objects.
Fields
- cursor string? - A pointer to the next page of
EmployeeWage
results to fetch.
- 'limit int? - The maximum number of
TeamMemberWage
results to return per page. The number can range between 1 and 200. The default is 200.
- team_member_id string? - Filter the returned wages to only those that are associated with the specified team member.
squareup: ListTeamMemberWagesResponse
The response to a request for a set of TeamMemberWage
objects. The response contains
a set of TeamMemberWage
objects.
Fields
- cursor string? - The value supplied in the subsequent request to fetch the next page
of
TeamMemberWage
results.
- errors Error[]? - Any errors that occurred during the request.
- team_member_wages TeamMemberWage[]? - A page of
TeamMemberWage
results.
squareup: ListTransactionsRequest
Defines the query parameters that can be included in a request to the ListTransactions endpoint.
Deprecated - recommend using SearchOrders
Fields
- begin_time string? - The beginning of the requested reporting period, in RFC 3339 format. See Date ranges for details on date inclusivity/exclusivity. Default value: The current time minus one year.
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. See Paginating results for more information.
- end_time string? - The end of the requested reporting period, in RFC 3339 format. See Date ranges for details on date inclusivity/exclusivity. Default value: The current time.
- sort_order string? - The order in which results are listed in the response (
ASC
for oldest first,DESC
for newest first). Default value:DESC
squareup: ListTransactionsResponse
Defines the fields that are included in the response body of a request to the ListTransactions endpoint.
One of errors
or transactions
is present in a given response (never both).
Fields
- cursor string? - A pagination cursor for retrieving the next set of results,
if any remain. Provide this value as the
cursor
parameter in a subsequent request to this endpoint. See Paginating results for more information.
- errors Error[]? - Any errors that occurred during the request.
- transactions Transaction[]? - An array of transactions that match your query.
squareup: ListWorkweekConfigsRequest
A request for a set of WorkweekConfig
objects.
Fields
- cursor string? - A pointer to the next page of
WorkweekConfig
results to fetch.
- 'limit int? - The maximum number of
WorkweekConfigs
results to return per page.
squareup: ListWorkweekConfigsResponse
The response to a request for a set of WorkweekConfig
objects. The response contains
the requested WorkweekConfig
objects and might contain a set of Error
objects if
the request resulted in errors.
Fields
- cursor string? - The value supplied in the subsequent request to fetch the next page of
EmployeeWage
results.
- errors Error[]? - Any errors that occurred during the request.
- workweek_configs WorkweekConfig[]? - A page of
EmployeeWage
results.
squareup: Location
Fields
- address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- business_email string? - The email of the location.
This email is visible to the customers of the location.
For example, the email appears on customer receipts.
For example,
help@squareup.com
.
- business_hours BusinessHours? - Represents the hours of operation for a business location.
- business_name string? - The business name of the location This is the name visible to the customers of the location. For example, this name appears on customer receipts.
- capabilities string[]? - The Square features that are enabled for the location. See LocationCapability for possible values.
- coordinates Coordinates? - Latitude and longitude coordinates.
- created_at string? - The time when the location was created, in RFC 3339 format. For more information, see Working with Dates.
- description string? - The description of the location.
- facebook_url string? - The Facebook profile URL of the location. The URL should begin with 'facebook.com/'. For example,
https://www.facebook.com/square
.
- full_format_logo_url string? - The URL of a full-format logo image for the location. The Seller must choose this logo in the Seller dashboard (Receipts section) for the logo to appear on transactions (such as receipts, invoices) that Square generates on behalf of the Seller. This image can have an aspect ratio of 2:1 or greater and is recommended to be at least 1280x648 pixels.
- id string? - The Square-issued ID of the location.
- instagram_username string? - The Instagram username of the location without the '@' symbol. For example,
square
.
- language_code string? - The language associated with the location, in BCP 47 format. For more information, see Location language code.
- logo_url string? - The URL of the logo image for the location. The Seller must choose this logo in the Seller dashboard (Receipts section) for the logo to appear on transactions (such as receipts, invoices) that Square generates on behalf of the Seller. This image should have an aspect ratio close to 1:1 and is recommended to be at least 200x200 pixels.
- mcc string? - The merchant category code (MCC) of the location, as standardized by ISO 18245. The MCC describes the kind of goods or services sold at the location.
- merchant_id string? - The ID of the merchant that owns the location.
- name string? - The name of the location. This information appears in the dashboard as the nickname. A location name must be unique within a seller account.
- phone_number string? - The phone number of the location in human readable format. For example,
+353 80 0 098 8099
.
- pos_background_url string? - The URL of the Point of Sale background image for the location.
- status string? - The status of the location, either active or inactive.
- tax_ids TaxIds? - The tax IDs that a Location is operating under.
- timezone string? - The IANA Timezone identifier for the timezone of the location.
- twitter_username string? - The Twitter username of the location without the '@' symbol. For example,
Square
.
- 'type string? - The type of the location, either physical or mobile.
- website_url string? - The website URL of the location. For example,
https://squareup.com
.
squareup: LoyaltyAccount
Describes a loyalty account. For more information, see Manage Loyalty Accounts Using the Loyalty API.
Fields
- balance int? - The available point balance in the loyalty account. If points are scheduled to expire, they are listed in the
expiring_point_deadlines
field. Your application should be able to handle loyalty accounts that have a negative point balance (balance
is less than 0). This might occur if a seller makes a manual adjustment or as a result of a refund or exchange.
- created_at string? - The timestamp when the loyalty account was created, in RFC 3339 format.
- enrolled_at string? - The timestamp when enrollment occurred, in RFC 3339 format.
- expiring_point_deadlines LoyaltyAccountExpiringPointDeadline[]? - The schedule for when points expire in the loyalty account balance. This field is present only if the account has points that are scheduled to expire.
The total number of points in this field equals the number of points in the
balance
field.
- id string? - The Square-assigned ID of the loyalty account.
- lifetime_points int? - The total points accrued during the lifetime of the account.
- mapping LoyaltyAccountMapping? - Represents the mapping that associates a loyalty account with a buyer. Currently, a loyalty account can only be mapped to a buyer by phone number. For more information, see Loyalty Overview.
- program_id string - The Square-assigned ID of the loyalty program to which the account belongs.
- updated_at string? - The timestamp when the loyalty account was last updated, in RFC 3339 format.
squareup: LoyaltyAccountExpiringPointDeadline
Represents a set of points for a loyalty account that are scheduled to expire on a specific date.
Fields
- expires_at string - The timestamp of when the points are scheduled to expire, in RFC 3339 format.
- points int - The number of points scheduled to expire at the
expires_at
timestamp.
squareup: LoyaltyAccountMapping
Represents the mapping that associates a loyalty account with a buyer.
Currently, a loyalty account can only be mapped to a buyer by phone number. For more information, see Loyalty Overview.
Fields
- created_at string? - The timestamp when the mapping was created, in RFC 3339 format.
- id string? - The Square-assigned ID of the mapping.
- phone_number string? - The phone number of the buyer, in E.164 format. For example, "+14155551111".
squareup: LoyaltyEvent
Provides information about a loyalty event. For more information, see Loyalty events.
Fields
- accumulate_points LoyaltyEventAccumulatePoints? - Provides metadata when the event
type
isACCUMULATE_POINTS
.
- adjust_points LoyaltyEventAdjustPoints? - Provides metadata when the event
type
isADJUST_POINTS
.
- create_reward LoyaltyEventCreateReward? - Provides metadata when the event
type
isCREATE_REWARD
.
- created_at string - The timestamp when the event was created, in RFC 3339 format.
- delete_reward LoyaltyEventDeleteReward? - Provides metadata when the event
type
isDELETE_REWARD
.
- expire_points LoyaltyEventExpirePoints? - Provides metadata when the event
type
isEXPIRE_POINTS
.
- id string - The Square-assigned ID of the loyalty event.
- loyalty_account_id string - The ID of the loyalty account in which the event occurred.
- other_event LoyaltyEventOther? - Provides metadata when the event
type
isOTHER
.
- redeem_reward LoyaltyEventRedeemReward? - Provides metadata when the event
type
isREDEEM_REWARD
.
- 'source string - Defines whether the event was generated by the Square Point of Sale.
- 'type string - The type of the loyalty event.
squareup: LoyaltyEventAccumulatePoints
Provides metadata when the event type
is ACCUMULATE_POINTS
.
Fields
- loyalty_program_id string? - The ID of the loyalty program.
- points int? - The number of points accumulated by the event.
squareup: LoyaltyEventAdjustPoints
Provides metadata when the event type
is ADJUST_POINTS
.
Fields
- loyalty_program_id string? - The Square-assigned ID of the loyalty program.
- points int - The number of points added or removed.
- reason string? - The reason for the adjustment of points.
squareup: LoyaltyEventCreateReward
Provides metadata when the event type
is CREATE_REWARD
.
Fields
- loyalty_program_id string - The ID of the loyalty program.
- points int - The loyalty points used to create the reward.
- reward_id string? - The Square-assigned ID of the created loyalty reward.
This field is returned only if the event source is
LOYALTY_API
.
squareup: LoyaltyEventDateTimeFilter
Filter events by date time range.
Fields
- created_at TimeRange - Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
squareup: LoyaltyEventDeleteReward
Provides metadata when the event type
is DELETE_REWARD
.
Fields
- loyalty_program_id string - The ID of the loyalty program.
- points int - The number of points returned to the loyalty account.
- reward_id string? - The ID of the deleted loyalty reward.
This field is returned only if the event source is
LOYALTY_API
.
squareup: LoyaltyEventExpirePoints
Provides metadata when the event type
is EXPIRE_POINTS
.
Fields
- loyalty_program_id string - The Square-assigned ID of the loyalty program.
- points int - The number of points expired.
squareup: LoyaltyEventFilter
The filtering criteria. If the request specifies multiple filters, the endpoint uses a logical AND to evaluate them.
Fields
- date_time_filter LoyaltyEventDateTimeFilter? - Filter events by date time range.
- location_filter LoyaltyEventLocationFilter? - Filter events by location.
- loyalty_account_filter LoyaltyEventLoyaltyAccountFilter? - Filter events by loyalty account.
- order_filter LoyaltyEventOrderFilter? - Filter events by the order associated with the event.
- type_filter LoyaltyEventTypeFilter? - Filter events by event type.
squareup: LoyaltyEventLocationFilter
Filter events by location.
Fields
- location_ids LoyaltyeventlocationfilterLocationidsItemsString[] - The location IDs for loyalty events to query. If multiple values are specified, the endpoint uses a logical OR to combine them.
squareup: LoyaltyEventLoyaltyAccountFilter
Filter events by loyalty account.
Fields
- loyalty_account_id string - The ID of the loyalty account associated with loyalty events.
squareup: LoyaltyEventOrderFilter
Filter events by the order associated with the event.
Fields
squareup: LoyaltyEventOther
Provides metadata when the event type
is OTHER
.
Fields
- loyalty_program_id string - The Square-assigned ID of the loyalty program.
- points int - The number of points added or removed.
squareup: LoyaltyEventQuery
Represents a query used to search for loyalty events.
Fields
- filter LoyaltyEventFilter? - The filtering criteria. If the request specifies multiple filters, the endpoint uses a logical AND to evaluate them.
squareup: LoyaltyEventRedeemReward
Provides metadata when the event type
is REDEEM_REWARD
.
Fields
- loyalty_program_id string - The ID of the loyalty program.
- reward_id string? - The ID of the redeemed loyalty reward.
This field is returned only if the event source is
LOYALTY_API
.
squareup: LoyaltyEventTypeFilter
Filter events by event type.
Fields
- types string[] - The loyalty event types used to filter the result. If multiple values are specified, the endpoint uses a logical OR to combine them.
squareup: LoyaltyProgram
Represents a Square loyalty program. Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see Loyalty Program Overview.
Fields
- accrual_rules LoyaltyProgramAccrualRule[] - Defines how buyers can earn loyalty points.
- created_at string - The timestamp when the program was created, in RFC 3339 format.
- expiration_policy LoyaltyProgramExpirationPolicy? - Describes when the loyalty program expires.
- id string - The Square-assigned ID of the loyalty program. Updates to the loyalty program do not modify the identifier.
- location_ids LoyaltyprogramLocationidsItemsString[] - The locations at which the program is active.
- reward_tiers LoyaltyProgramRewardTier[] - The list of rewards for buyers, sorted by ascending points.
- status string - Whether the program is currently active.
- terminology LoyaltyProgramTerminology - Represents the naming used for loyalty points.
- updated_at string - The timestamp when the reward was last updated, in RFC 3339 format.
squareup: LoyaltyProgramAccrualRule
Defines an accrual rule, which is how buyers can earn points.
Fields
- accrual_type string - The type of the accrual rule that defines how buyers can earn points.
- catalog_object_id string? - When the accrual rule is item-based or category-based, this field specifies the ID
of the catalog object that buyers can purchase to earn points.
If
accrual_type
isITEM_VARIATION
, the object is an item variation. Ifaccrual_type
isCATEGORY
, the object is a category.
- excluded_category_ids string[]? - When the accrual rule is spend-based (
accrual_type
isSPEND
), this field lists the IDs of anyCATEGORY
catalog objects that are excluded from points accrual. You can use the BatchRetrieveCatalogObjects endpoint to retrieve information about the excluded categories.
- excluded_item_variation_ids string[]? - When the accrual rule is spend-based (
accrual_type
isSPEND
), this field lists the IDs of anyITEM_VARIATION
catalog objects that are excluded from points accrual. You can use the BatchRetrieveCatalogObjects endpoint to retrieve information about the excluded item variations.
- points int? - The number of points that
buyers earn based on the
accrual_type
.
- spend_amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- visit_minimum_amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
squareup: LoyaltyProgramExpirationPolicy
Describes when the loyalty program expires.
Fields
- expiration_duration string - The number of months before points expire, in
P[n]M
RFC 3339 duration format. For example, a value ofP12M
represents a duration of 12 months. Points are valid through the last day of the month in which they are scheduled to expire. For example, with aP12M
duration, points earned on July 6, 2020 expire on August 1, 2021.
squareup: LoyaltyProgramRewardDefinition
Provides details about the reward tier discount. DEPRECATED at version 2020-12-16. Discount details are now defined using a catalog pricing rule and other catalog objects. For more information, see Get discount details for the reward.
Fields
- catalog_object_ids string[]? - The list of catalog objects to which this reward can be applied. They are either all item-variation ids or category ids, depending on the
type
field. DEPRECATED at version 2020-12-16. You can find this information in theproduct_set_data.product_ids_any
field of thePRODUCT_SET
catalog object referenced by the pricing rule.
- discount_type string - The type of discount the reward tier offers. DEPRECATED at version 2020-12-16. You can find this information
in the
discount_data.discount_type
field of theDISCOUNT
catalog object referenced by the pricing rule.
- fixed_discount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- max_discount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- percentage_discount string? - The fixed percentage of the discount. Present if
discount_type
isFIXED_PERCENTAGE
. For example, a 7.25% off discount will be represented as "7.25". DEPRECATED at version 2020-12-16. You can find this information in thediscount_data.percentage
field of theDISCOUNT
catalog object referenced by the pricing rule.
- scope string - Indicates the scope of the reward tier. DEPRECATED at version 2020-12-16. You can find this information in the
discount_target_scope
field of thePRICING_RULE
catalog object and theproduct_set_data
field of thePRODUCT_SET
catalog object referenced by the pricing rule. ForORDER
scopes, the target scope isWHOLE_PURCHASE
andall_products
is true. ForITEM_VARIATION
andCATEGORY
scopes, the target scope isLINE_ITEM
andproduct_ids_any
is a list of catalog object IDs of the given type.
squareup: LoyaltyProgramRewardTier
Represents a reward tier in a loyalty program. A reward tier defines how buyers can redeem points for a reward, such as the number of points required and the value and scope of the discount. A loyalty program can offer multiple reward tiers.
Fields
- created_at string - The timestamp when the reward tier was created, in RFC 3339 format.
- definition LoyaltyProgramRewardDefinition - Provides details about the reward tier discount. DEPRECATED at version 2020-12-16. Discount details are now defined using a catalog pricing rule and other catalog objects. For more information, see Get discount details for the reward.
- id string - The Square-assigned ID of the reward tier.
- name string - The name of the reward tier.
- points int - The points exchanged for the reward tier.
- pricing_rule_reference CatalogObjectReference? - A reference to a Catalog object at a specific version. In general this is used as an entry point into a graph of catalog objects, where the objects exist at a specific version.
squareup: LoyaltyProgramTerminology
Represents the naming used for loyalty points.
Fields
- one string - A singular unit for a point (for example, 1 point is called 1 star).
- other string - A plural unit for point (for example, 10 points is called 10 stars).
squareup: LoyaltyReward
Represents a contract to redeem loyalty points for a reward tier discount. Loyalty rewards can be in an ISSUED, REDEEMED, or DELETED state. For more information, see Redeem loyalty rewards.
Fields
- created_at string? - The timestamp when the reward was created, in RFC 3339 format.
- id string? - The Square-assigned ID of the loyalty reward.
- loyalty_account_id string - The Square-assigned ID of the loyalty account to which the reward belongs.
- points int? - The number of loyalty points used for the reward.
- redeemed_at string? - The timestamp when the reward was redeemed, in RFC 3339 format.
- reward_tier_id string - The Square-assigned ID of the reward tier used to create the reward.
- status string? - The status of a loyalty reward.
- updated_at string? - The timestamp when the reward was last updated, in RFC 3339 format.
squareup: MeasurementUnit
Represents a unit of measurement to use with a quantity, such as ounces
or inches. Exactly one of the following fields are required: custom_unit
,
area_unit
, length_unit
, volume_unit
, and weight_unit
.
Fields
- area_unit string? - Represents a standard area unit.
- custom_unit MeasurementUnitCustom? - The information needed to define a custom unit, provided by the seller.
- generic_unit string? - Reserved for API integrations that lack the ability to specify a real measurement unit
- length_unit string? - Represents a standard length unit.
- time_unit string? - Represents a standard unit of time.
- 'type string? - Represents the type of the measurement unit.
- volume_unit string? - Represents a standard volume unit.
- weight_unit string? - Represents a standard unit of weight or mass.
squareup: MeasurementUnitCustom
The information needed to define a custom unit, provided by the seller.
Fields
- abbreviation string - The abbreviation of the custom unit, such as "bsh" (bushel). This appears in the cart for the Point of Sale app, and in reports.
- name string - The name of the custom unit, for example "bushel".
squareup: Merchant
Represents a Square seller.
Fields
- business_name string? - The business name of the merchant.
- country string - The country code associated with the merchant account, in ISO 3166 format.
- currency string? - The currency associated with the merchant account, in ISO 4217 format.
- id string? - The Square-issued ID of the merchant.
- language_code string? - The language code associated with the merchant account, in BCP 47 format.
- main_location_id string? - The ID of the main
Location
for this merchant.
- status string? - The merchant status, active or inactive.
squareup: Money
Represents an amount of money. Money
fields can be signed or unsigned.
Fields that do not explicitly define whether they are signed or unsigned are
considered unsigned and can only hold positive amounts. For signed fields, the
sign of the value indicates the purpose of the money transfer. See
Working with Monetary Amounts
for more information.
Fields
- amount int? - The amount of money, in the smallest denomination of the currency
indicated by
currency
. For example, whencurrency
isUSD
,amount
is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case.
squareup: OAuth2RefreshTokenGrantConfig
OAuth2 Refresh Token Grant Configs
Fields
- Fields Included from * OAuth2RefreshTokenGrantConfig
- refreshUrl string(default "https://connect.squareup.com/oauth2/token") - Refresh URL
squareup: ObtainTokenRequest
Fields
- client_id string - The Square-issued ID of your application, available from the developer dashboard.
- client_secret string - The Square-issued application secret for your application, available from the developer dashboard.
- code string? - The authorization code to exchange.
This is required if
grant_type
is set toauthorization_code
, to indicate that the application wants to exchange an authorization code for an OAuth access token.
- grant_type string - Specifies the method to request an OAuth access token.
Valid values are:
authorization_code
,refresh_token
, andmigration_token
- migration_token string? - Legacy OAuth access token obtained using a Connect API version prior
to 2019-03-13. This parameter is required if
grant_type
is set tomigration_token
to indicate that the application wants to get a replacement OAuth access token. The response also returns a refresh token. For more information, see Migrate to Using Refresh Tokens.
- redirect_uri string? - The redirect URL assigned in the developer dashboard.
- refresh_token string? - A valid refresh token for generating a new OAuth access token.
A valid refresh token is required if
grant_type
is set torefresh_token
, to indicate the application wants a replacement for an expired OAuth access token.
- scopes string[]? - A JSON list of strings representing the permissions the application is requesting.
For example: "
["MERCHANT_PROFILE_READ","PAYMENTS_READ","BANK_ACCOUNTS_READ"]
" The access token returned in the response is granted the permissions that comprise the intersection between the requested list of permissions, and those that belong to the provided refresh token.
- short_lived boolean? - A boolean indicating a request for a short-lived access token. The short-lived access token returned in the response will expire in 24 hours.
squareup: ObtainTokenResponse
Fields
- access_token string? - A valid OAuth access token. OAuth access tokens are 64 bytes long. Provide the access token in a header with every request to Connect API endpoints. See OAuth API: Walkthrough for more information.
- id_token string? - Then OpenID token belonging to this this person. Only present if the OPENID scope is included in the authorize request.
- merchant_id string? - The ID of the authorizing merchant's business.
- plan_id string? - LEGACY FIELD. The ID of the subscription plan the merchant signed up for. Only present if the merchant signed up for a subscription during authorization.
- refresh_token string? - A refresh token. OAuth refresh tokens are 64 bytes long. For more information, see OAuth access token management.
- short_lived boolean? - A boolean indicating the access token is a short-lived access token. The short-lived access token returned in the response will expire in 24 hours.
- subscription_id string? - LEGACY FIELD. The ID of a subscription plan the merchant signed up for. Only present if the merchant signed up for a subscription during authorization.
- token_type string? - This value is always bearer.
squareup: OnboardAppointmentsRequest
squareup: Order
Contains all information related to a single order to process with Square,
including line items that specify the products to purchase. Order
objects also
include information about any associated tenders, refunds, and returns.
All Connect V2 Transactions have all been converted to Orders including all associated itemization data.
Fields
- created_at string? - The timestamp for when the order was created, in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").
- customer_id string? - The ID of the customer associated with the order.
IMPORTANT: You should specify a
customer_id
if you want the corresponding payment transactions to be explicitly linked to the customer in the Seller Dashboard. If this field is omitted, thecustomer_id
assigned to any underlyingPayment
objects is ignored and might result in the creation of new instant profiles.
- discounts OrderLineItemDiscount[]? - The list of all discounts associated with the order.
Discounts can be scoped to either
ORDER
orLINE_ITEM
. For discounts scoped toLINE_ITEM
, anOrderLineItemAppliedDiscount
must be added to each line item that the discount applies to. For discounts withORDER
scope, the server generates anOrderLineItemAppliedDiscount
for every line item. IMPORTANT: IfLINE_ITEM
scope is set on any discounts in this field, using the deprecatedline_items.discounts
field results in an error. Useline_items.applied_discounts
instead.
- fulfillments OrderFulfillment[]? - Details about order fulfillment. Orders can only be created with at most one fulfillment. However, orders returned by the API might contain multiple fulfillments.
- id string? - The order's unique ID.
- line_items OrderLineItem[]? - The line items included in the order.
- location_id string - The ID of the seller location that this order is associated with.
- metadata record {}? - Application-defined data attached to this order. Metadata fields are intended
to store descriptive references or associations with an entity in another system or store brief
information about the object. Square does not process this field; it only stores and returns it
in relevant API calls. Do not use metadata to store any sensitive information (such as personally
identifiable information or card details).
Keys written by applications must be 60 characters or less and must be in the character set
[a-zA-Z0-9_-]
. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a ':' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see Metadata.
- net_amounts OrderMoneyAmounts? - A collection of various money amounts.
- pricing_options OrderPricingOptions? - Pricing options for an order. The options affect how the order's price is calculated. They can be used, for example, to apply automatic price adjustments that are based on preconfigured pricing rules.
- reference_id string? - A client-specified ID to associate an entity in another system with this order.
- refunds Refund[]? - The refunds that are part of this order.
- return_amounts OrderMoneyAmounts? - A collection of various money amounts.
- 'returns OrderReturn[]? - A collection of items from sale orders being returned in this one. Normally part of an
itemized return or exchange. There is exactly one
Return
object per saleOrder
being referenced.
- rewards OrderReward[]? - A set-like list of Rewards that have been added to the Order.
- rounding_adjustment OrderRoundingAdjustment? - A rounding adjustment of the money being returned. Commonly used to apply cash rounding when the minimum unit of the account is smaller than the lowest physical denomination of the currency.
- service_charges OrderServiceCharge[]? - A list of service charges applied to the order.
- 'source OrderSource? - Represents the origination details of an order.
- state string? - The current state of the order:
OPEN
,COMPLETED
, orCANCELED
.
- taxes OrderLineItemTax[]? - The list of all taxes associated with the order.
Taxes can be scoped to either
ORDER
orLINE_ITEM
. For taxes withLINE_ITEM
scope, anOrderLineItemAppliedTax
must be added to each line item that the tax applies to. For taxes withORDER
scope, the server generates anOrderLineItemAppliedTax
for every line item. On reads, each tax in the list includes the total amount of that tax applied to the order. IMPORTANT: IfLINE_ITEM
scope is set on any taxes in this field, using the deprecatedline_items.taxes
field results in an error. Useline_items.applied_taxes
instead.
- tenders Tender[]? - The tenders that were used to pay for the order.
- total_discount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- total_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- total_service_charge_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- total_tax_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- total_tip_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- updated_at string? - The timestamp for when the order was last updated, in RFC 3339 format (for example, "2016-09-04T23:59:33.123Z").
- 'version int? - The version number, which is incremented each time an update is committed to the order. Orders not created through the API do not include a version number and therefore cannot be updated. Read more about working with versions.
squareup: OrderCreated
Fields
- created_at string? - The timestamp for when the order was created, in RFC 3339 format.
- location_id string? - The ID of the seller location that this order is associated with.
- order_id string? - The order's unique ID.
- state string? - The state of the order.
- 'version int? - The version number, which is incremented each time an update is committed to the order. Orders that were not created through the API do not include a version number and therefore cannot be updated. Read more about working with versions.
squareup: OrderCreatedObject
Fields
- order_created OrderCreated? -
squareup: OrderEntry
A lightweight description of an order that is returned when
returned_entries
is true
on a SearchOrdersRequest.
Fields
- location_id string? - The location ID the order belongs to.
- order_id string? - The ID of the order.
- 'version int? - The version number, which is incremented each time an update is committed to the order. Orders that were not created through the API do not include a version number and therefore cannot be updated. Read more about working with versions.
squareup: OrderFulfillment
Contains details about how to fulfill this order.
Fields
- metadata record {}? - Application-defined data attached to this fulfillment. Metadata fields are intended
to store descriptive references or associations with an entity in another system or store brief
information about the object. Square does not process this field; it only stores and returns it
in relevant API calls. Do not use metadata to store any sensitive information (such as personally
identifiable information or card details).
Keys written by applications must be 60 characters or less and must be in the character set
[a-zA-Z0-9_-]
. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a ':' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see Metadata.
- pickup_details OrderFulfillmentPickupDetails? - Contains details necessary to fulfill a pickup order.
- shipment_details OrderFulfillmentShipmentDetails? - Contains the details necessary to fulfill a shipment order.
- state string? - The state of the fulfillment.
- 'type string? - The type of the fulfillment.
- uid string? - A unique ID that identifies the fulfillment only within this order.
squareup: OrderFulfillmentPickupDetails
Contains details necessary to fulfill a pickup order.
Fields
- auto_complete_duration string? - The duration of time after which an open and accepted pickup fulfillment
is automatically moved to the
COMPLETED
state. The duration must be in RFC 3339 format (for example, "P1W3D"). If not set, this pickup fulfillment remains accepted until it is canceled or completed.
- cancel_reason string? - A description of why the pickup was canceled. The maximum length: 100 characters.
- curbside_pickup_details OrderFulfillmentPickupDetailsCurbsidePickupDetails? - Specific details for curbside pickup.
- expires_at string? - The timestamp
indicating when this fulfillment expires if it is not accepted. The timestamp must be in RFC 3339 format
(for example, "2016-09-04T23:59:33.123Z"). The expiration time can only be set up to 7 days in the future.
If
expires_at
is not set, this pickup fulfillment is automatically accepted when placed.
- is_curbside_pickup boolean? - If set to
true
, indicates that this pickup order is for curbside pickup, not in-store pickup.
- note string? - A note meant to provide additional instructions about the pickup fulfillment displayed in the Square Point of Sale application and set by the API.
- pickup_at string? - The timestamp
that represents the start of the pickup window. Must be in RFC 3339 timestamp format, e.g.,
"2016-09-04T23:59:33.123Z".
For fulfillments with the schedule type
ASAP
, this is automatically set to the current time plus the expected duration to prepare the fulfillment.
- pickup_window_duration string? - The window of time in which the order should be picked up after the
pickup_at
timestamp. Must be in RFC 3339 duration format, e.g., "P1W3D". Can be used as an informational guideline for merchants.
- prep_time_duration string? - The duration of time it takes to prepare this fulfillment. The duration must be in RFC 3339 format (for example, "P1W3D").
- recipient OrderFulfillmentRecipient? - Contains information about the recipient of a fulfillment.
- schedule_type string? - The schedule type of the pickup fulfillment. Defaults to
SCHEDULED
.
squareup: OrderFulfillmentPickupDetailsCurbsidePickupDetails
Specific details for curbside pickup.
Fields
- curbside_details string? - Specific details for curbside pickup, such as parking number and vehicle model.
squareup: OrderFulfillmentRecipient
Contains information about the recipient of a fulfillment.
Fields
- address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- customer_id string? - The customer ID of the customer associated with the fulfillment.
If
customer_id
is provided, the fulfillment recipient'sdisplay_name
,email_address
, andphone_number
are automatically populated from the targeted customer profile. If these fields are set in the request, the request values overrides the information from the customer profile. If the targeted customer profile does not contain the necessary information and these fields are left unset, the request results in an error.
- display_name string? - The display name of the fulfillment recipient.
If provided, the display name overrides the value pulled from the customer profile indicated by
customer_id
.
- email_address string? - The email address of the fulfillment recipient.
If provided, the email address overrides the value pulled from the customer profile indicated by
customer_id
.
- phone_number string? - The phone number of the fulfillment recipient.
If provided, the phone number overrides the value pulled from the customer profile indicated by
customer_id
.
squareup: OrderFulfillmentShipmentDetails
Contains the details necessary to fulfill a shipment order.
Fields
- cancel_reason string? - A description of why the shipment was canceled.
- carrier string? - The shipping carrier being used to ship this fulfillment (such as UPS, FedEx, or USPS).
- failure_reason string? - A description of why the shipment failed to be completed.
- recipient OrderFulfillmentRecipient? - Contains information about the recipient of a fulfillment.
- shipping_note string? - A note with additional information for the shipping carrier.
- shipping_type string? - A description of the type of shipping product purchased from the carrier (such as First Class, Priority, or Express).
- tracking_number string? - The reference number provided by the carrier to track the shipment's progress.
- tracking_url string? - A link to the tracking webpage on the carrier's website.
squareup: OrderFulfillmentUpdated
Fields
- created_at string? - The timestamp for when the order was created, in RFC 3339 format.
- fulfillment_update OrderFulfillmentUpdatedUpdate[]? - The fulfillments that were updated with this version change.
- location_id string? - The ID of the seller location that this order is associated with.
- order_id string? - The order's unique ID.
- state string? - The state of the order.
- updated_at string? - The timestamp for when the order was last updated, in RFC 3339 format.
- 'version int? - The version number, which is incremented each time an update is committed to the order. Orders that were not created through the API do not include a version number and therefore cannot be updated. Read more about working with versions.
squareup: OrderFulfillmentUpdatedObject
Fields
- order_fulfillment_updated OrderFulfillmentUpdated? -
squareup: OrderFulfillmentUpdatedUpdate
Information about fulfillment updates.
Fields
- fulfillment_uid string? - A unique ID that identifies the fulfillment only within this order.
- new_state string? - The state of the fulfillment after the change. The state might be equal to
old_state
if a non-state field was changed on the fulfillment (such as the tracking number).
- old_state string? - The state of the fulfillment before the change.
The state is not populated if the fulfillment is created with this new
Order
version.
squareup: OrderLineItem
Represents a line item in an order. Each line item describes a different product to purchase, with its own quantity and price details.
Fields
- applied_discounts OrderLineItemAppliedDiscount[]? - The list of references to discounts applied to this line item. Each
OrderLineItemAppliedDiscount
has adiscount_uid
that references theuid
of a top-levelOrderLineItemDiscounts
applied to the line item. On reads, the amount applied is populated. AnOrderLineItemAppliedDiscount
is automatically created on every line item for allORDER
scoped discounts that are added to the order.OrderLineItemAppliedDiscount
records forLINE_ITEM
scoped discounts must be added in requests for the discount to apply to any line items. To change the amount of a discount, modify the referenced top-level discount.
- applied_taxes OrderLineItemAppliedTax[]? - The list of references to taxes applied to this line item. Each
OrderLineItemAppliedTax
has atax_uid
that references theuid
of a top-levelOrderLineItemTax
applied to the line item. On reads, the amount applied is populated. AnOrderLineItemAppliedTax
is automatically created on every line item for allORDER
scoped taxes added to the order.OrderLineItemAppliedTax
records forLINE_ITEM
scoped taxes must be added in requests for the tax to apply to any line items. To change the amount of a tax, modify the referenced top-level tax.
- base_price_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- catalog_object_id string? - The CatalogItemVariation ID applied to this line item.
- catalog_version int? - The version of the catalog object that this line item references.
- gross_sales_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- item_type string? - The type of line item: an itemized sale, a non-itemized sale (custom amount), or the activation or reloading of a gift card.
- metadata record {}? - Application-defined data attached to this line item. Metadata fields are intended
to store descriptive references or associations with an entity in another system or store brief
information about the object. Square does not process this field; it only stores and returns it
in relevant API calls. Do not use metadata to store any sensitive information (such as personally
identifiable information or card details).
Keys written by applications must be 60 characters or less and must be in the character set
[a-zA-Z0-9_-]
. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a ':' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see Metadata.
- modifiers OrderLineItemModifier[]? - The CatalogModifiers applied to this line item.
- name string? - The name of the line item.
- note string? - The note of the line item.
- pricing_blocklists OrderLineItemPricingBlocklists? - Describes pricing adjustments that are blocked from manual and automatic application to a line item. For more information, see Apply Taxes and Discounts.
- quantity string - The quantity purchased, formatted as a decimal number.
For example,
"3"
. Line items with a quantity of"0"
are automatically removed when paying for or otherwise completing the order. Line items with aquantity_unit
can have non-integer quantities. For example,"1.70000"
.
- quantity_unit OrderQuantityUnit? - Contains the measurement unit for a quantity and a precision that specifies the number of digits after the decimal point for decimal quantities.
- total_discount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- total_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- total_tax_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- uid string? - A unique ID that identifies the line item only within this order.
- variation_name string? - The name of the variation applied to this line item.
- variation_total_price_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
squareup: OrderLineItemAppliedDiscount
Represents an applied portion of a discount to a line item in an order.
Order scoped discounts have automatically applied discounts present for each line item. Line-item scoped discounts must have applied discounts added manually for any applicable line items. The corresponding applied money is automatically computed based on participating line items.
Fields
- applied_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- discount_uid string - The
uid
of the discount that the applied discount represents. It must reference a discount present in theorder.discounts
field. This field is immutable. To change which discounts apply to a line item, you must delete the discount and re-add it as a newOrderLineItemAppliedDiscount
.
- uid string? - A unique ID that identifies the applied discount only within this order.
squareup: OrderLineItemAppliedTax
Represents an applied portion of a tax to a line item in an order.
Order-scoped taxes automatically include the applied taxes in each line item. Line item taxes must be referenced from any applicable line items. The corresponding applied money is automatically computed, based on the set of participating line items.
Fields
- applied_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- tax_uid string - The
uid
of the tax for which this applied tax represents. It must reference a tax present in theorder.taxes
field. This field is immutable. To change which taxes apply to a line item, delete and add a newOrderLineItemAppliedTax
.
- uid string? - A unique ID that identifies the applied tax only within this order.
squareup: OrderLineItemDiscount
Represents a discount that applies to one or more line items in an order.
Fixed-amount, order-scoped discounts are distributed across all non-zero line item totals. The amount distributed to each line item is relative to the amount contributed by the item to the order subtotal.
Fields
- amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- applied_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- catalog_object_id string? - The catalog object ID referencing CatalogDiscount.
- catalog_version int? - The version of the catalog object that this discount references.
- metadata record {}? - Application-defined data attached to this discount. Metadata fields are intended
to store descriptive references or associations with an entity in another system or store brief
information about the object. Square does not process this field; it only stores and returns it
in relevant API calls. Do not use metadata to store any sensitive information (such as personally
identifiable information or card details).
Keys written by applications must be 60 characters or less and must be in the character set
[a-zA-Z0-9_-]
. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a ':' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see Metadata.
- name string? - The discount's name.
- percentage string? - The percentage of the discount, as a string representation of a decimal number.
A value of
7.25
corresponds to a percentage of 7.25%.percentage
is not set for amount-based discounts.
- pricing_rule_id string? - The object ID of a pricing rule to be applied
automatically to this discount. The specification and application of the discounts, to
which a
pricing_rule_id
is assigned, are completely controlled by the corresponding pricing rule.
- reward_ids string[]? - The reward IDs corresponding to this discount. The application and
specification of discounts that have
reward_ids
are completely controlled by the backing criteria corresponding to the reward tiers of the rewards that are added to the order through the Loyalty API. To manually unapply discounts that are the result of added rewards, the rewards must be removed from the order through the Loyalty API.
- scope string? - Indicates the level at which the discount applies. For
ORDER
scoped discounts, Square generates references inapplied_discounts
on all order line items that do not have them. ForLINE_ITEM
scoped discounts, the discount only applies to line items with a discount reference in theirapplied_discounts
field. This field is immutable. To change the scope of a discount, you must delete the discount and re-add it as a new discount.
- 'type string? - The type of the discount.
Discounts that do not reference a catalog object ID must have a type of
FIXED_PERCENTAGE
orFIXED_AMOUNT
.
- uid string? - A unique ID that identifies the discount only within this order.
squareup: OrderLineItemModifier
Fields
- base_price_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- catalog_object_id string? - The catalog object ID referencing CatalogModifier.
- catalog_version int? - The version of the catalog object that this modifier references.
- name string? - The name of the item modifier.
- total_price_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- uid string? - A unique ID that identifies the modifier only within this order.
squareup: OrderLineItemPricingBlocklists
Describes pricing adjustments that are blocked from manual and automatic application to a line item. For more information, see Apply Taxes and Discounts.
Fields
- blocked_discounts OrderLineItemPricingBlocklistsBlockedDiscount[]? - A list of discounts blocked from applying to the line item.
Discounts can be blocked by the
discount_uid
(for ad hoc discounts) or thediscount_catalog_object_id
(for catalog discounts).
- blocked_taxes OrderLineItemPricingBlocklistsBlockedTax[]? - A list of taxes blocked from applying to the line item.
Taxes can be blocked by the
tax_uid
(for ad hoc taxes) or thetax_catalog_object_id
(for catalog taxes).
squareup: OrderLineItemPricingBlocklistsBlockedDiscount
A discount to block from applying to a line item. The discount must be
identified by either discount_uid
or discount_catalog_object_id
, but not both.
Fields
- discount_catalog_object_id string? - The
catalog_object_id
of the discount that should be blocked. Use this field to block catalog discounts. For ad hoc discounts, use thediscount_uid
field.
- discount_uid string? - The
uid
of the discount that should be blocked. Use this field to block ad hoc discounts. For catalog discounts, use thediscount_catalog_object_id
field.
- uid string? - A unique ID of the
BlockedDiscount
within the order.
squareup: OrderLineItemPricingBlocklistsBlockedTax
A tax to block from applying to a line item. The tax must be
identified by either tax_uid
or tax_catalog_object_id
, but not both.
Fields
- tax_catalog_object_id string? - The
catalog_object_id
of the tax that should be blocked. Use this field to block catalog taxes. For ad hoc taxes, use thetax_uid
field.
- tax_uid string? - The
uid
of the tax that should be blocked. Use this field to block ad hoc taxes. For catalog, taxes use thetax_catalog_object_id
field.
- uid string? - A unique ID of the
BlockedTax
within the order.
squareup: OrderLineItemTax
Represents a tax that applies to one or more line item in the order.
Fixed-amount, order-scoped taxes are distributed across all non-zero line item totals. The amount distributed to each line item is relative to the amount the item contributes to the order subtotal.
Fields
- applied_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- auto_applied boolean? - Determines whether the tax was automatically applied to the order based on the catalog configuration. For an example, see Automatically Apply Taxes to an Order.
- catalog_object_id string? - The catalog object ID referencing CatalogTax.
- catalog_version int? - The version of the catalog object that this tax references.
- metadata record {}? - Application-defined data attached to this tax. Metadata fields are intended
to store descriptive references or associations with an entity in another system or store brief
information about the object. Square does not process this field; it only stores and returns it
in relevant API calls. Do not use metadata to store any sensitive information (such as personally
identifiable information or card details).
Keys written by applications must be 60 characters or less and must be in the character set
[a-zA-Z0-9_-]
. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a ':' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see Metadata.
- name string? - The tax's name.
- percentage string? - The percentage of the tax, as a string representation of a decimal
number. For example, a value of
"7.25"
corresponds to a percentage of 7.25%.
- scope string? - Indicates the level at which the tax applies. For
ORDER
scoped taxes, Square generates references inapplied_taxes
on all order line items that do not have them. ForLINE_ITEM
scoped taxes, the tax only applies to line items with references in theirapplied_taxes
field. This field is immutable. To change the scope, you must delete the tax and re-add it as a new tax.
- 'type string? - Indicates the calculation method used to apply the tax.
- uid string? - A unique ID that identifies the tax only within this order.
squareup: OrderMoneyAmounts
A collection of various money amounts.
Fields
- discount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- service_charge_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- tax_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- tip_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- total_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
squareup: OrderPricingOptions
Pricing options for an order. The options affect how the order's price is calculated. They can be used, for example, to apply automatic price adjustments that are based on preconfigured pricing rules.
Fields
- auto_apply_discounts boolean? - The option to determine whether pricing rule-based discounts are automatically applied to an order.
- auto_apply_taxes boolean? - The option to determine whether rule-based taxes are automatically applied to an order when the criteria of the corresponding rules are met.
squareup: OrderQuantityUnit
Contains the measurement unit for a quantity and a precision that specifies the number of digits after the decimal point for decimal quantities.
Fields
- catalog_version int? - The version of the catalog object that this measurement unit references. This field is set when this is a catalog-backed measurement unit.
- measurement_unit MeasurementUnit? - Represents a unit of measurement to use with a quantity, such as ounces
or inches. Exactly one of the following fields are required:
custom_unit
,area_unit
,length_unit
,volume_unit
, andweight_unit
.
- precision int? - For non-integer quantities, represents the number of digits after the decimal point that are
recorded for this quantity.
For example, a precision of 1 allows quantities such as
"1.0"
and"1.1"
, but not"1.01"
. Min: 0. Max: 5.
squareup: OrderReturn
The set of line items, service charges, taxes, discounts, tips, and other items being returned in an order.
Fields
- return_amounts OrderMoneyAmounts? - A collection of various money amounts.
- return_discounts OrderReturnDiscount[]? - A collection of references to discounts being returned for an order, including the total applied discount amount to be returned. The discounts must reference a top-level discount ID from the source order.
- return_line_items OrderReturnLineItem[]? - A collection of line items that are being returned.
- return_service_charges OrderReturnServiceCharge[]? - A collection of service charges that are being returned.
- return_taxes OrderReturnTax[]? - A collection of references to taxes being returned for an order, including the total applied tax amount to be returned. The taxes must reference a top-level tax ID from the source order.
- rounding_adjustment OrderRoundingAdjustment? - A rounding adjustment of the money being returned. Commonly used to apply cash rounding when the minimum unit of the account is smaller than the lowest physical denomination of the currency.
- source_order_id string? - An order that contains the original sale of these return line items. This is unset for unlinked returns.
- uid string? - A unique ID that identifies the return only within this order.
squareup: OrderReturnDiscount
Represents a discount being returned that applies to one or more return line items in an order.
Fixed-amount, order-scoped discounts are distributed across all non-zero return line item totals. The amount distributed to each return line item is relative to that item’s contribution to the order subtotal.
Fields
- amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- applied_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- catalog_object_id string? - The catalog object ID referencing CatalogDiscount.
- catalog_version int? - The version of the catalog object that this discount references.
- name string? - The discount's name.
- percentage string? - The percentage of the tax, as a string representation of a decimal number.
A value of
"7.25"
corresponds to a percentage of 7.25%.percentage
is not set for amount-based discounts.
- scope string? - Indicates the level at which the
OrderReturnDiscount
applies. ForORDER
scoped discounts, the server generates references inapplied_discounts
on allOrderReturnLineItem
s. ForLINE_ITEM
scoped discounts, the discount is only applied toOrderReturnLineItem
s with references in theirapplied_discounts
field.
- source_discount_uid string? - The discount
uid
from the order that contains the original application of this discount.
- 'type string? - The type of the discount. If it is created by the API, it is
FIXED_PERCENTAGE
orFIXED_AMOUNT
. Discounts that do not reference a catalog object ID must have a type ofFIXED_PERCENTAGE
orFIXED_AMOUNT
.
- uid string? - A unique ID that identifies the returned discount only within this order.
squareup: OrderReturnLineItem
The line item being returned in an order.
Fields
- applied_discounts OrderLineItemAppliedDiscount[]? - The list of references to
OrderReturnDiscount
entities applied to the return line item. EachOrderLineItemAppliedDiscount
has adiscount_uid
that references theuid
of a top-levelOrderReturnDiscount
applied to the return line item. On reads, the applied amount is populated.
- applied_taxes OrderLineItemAppliedTax[]? - The list of references to
OrderReturnTax
entities applied to the return line item. EachOrderLineItemAppliedTax
has atax_uid
that references theuid
of a top-levelOrderReturnTax
applied to the return line item. On reads, the applied amount is populated.
- base_price_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- catalog_object_id string? - The CatalogItemVariation ID applied to this return line item.
- catalog_version int? - The version of the catalog object that this line item references.
- gross_return_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- item_type string? - The type of line item: an itemized return, a non-itemized return (custom amount), or the return of an unactivated gift card sale.
- name string? - The name of the line item.
- note string? - The note of the return line item.
- quantity string - The quantity returned, formatted as a decimal number.
For example,
"3"
. Line items with aquantity_unit
can have non-integer quantities. For example,"1.70000"
.
- quantity_unit OrderQuantityUnit? - Contains the measurement unit for a quantity and a precision that specifies the number of digits after the decimal point for decimal quantities.
- return_modifiers OrderReturnLineItemModifier[]? - The CatalogModifiers applied to this line item.
- source_line_item_uid string? - The
uid
of the line item in the original sale order.
- total_discount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- total_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- total_tax_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- uid string? - A unique ID for this return line-item entry.
- variation_name string? - The name of the variation applied to this return line item.
- variation_total_price_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
squareup: OrderReturnLineItemModifier
A line item modifier being returned.
Fields
- base_price_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- catalog_object_id string? - The catalog object ID referencing CatalogModifier.
- catalog_version int? - The version of the catalog object that this line item modifier references.
- name string? - The name of the item modifier.
- source_modifier_uid string? - The modifier
uid
from the order's line item that contains the original sale of this line item modifier.
- total_price_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- uid string? - A unique ID that identifies the return modifier only within this order.
squareup: OrderReturnServiceCharge
Represents the service charge applied to the original order.
Fields
- amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- applied_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- applied_taxes OrderLineItemAppliedTax[]? - The list of references to
OrderReturnTax
entities applied to theOrderReturnServiceCharge
. EachOrderLineItemAppliedTax
has atax_uid
that references theuid
of a top-levelOrderReturnTax
that is being applied to theOrderReturnServiceCharge
. On reads, the applied amount is populated.
- calculation_phase string? - The calculation phase after which to apply the service charge.
- catalog_object_id string? - The catalog object ID of the associated OrderServiceCharge.
- catalog_version int? - The version of the catalog object that this service charge references.
- name string? - The name of the service charge.
- percentage string? - The percentage of the service charge, as a string representation of
a decimal number. For example, a value of
"7.25"
corresponds to a percentage of 7.25%. Eitherpercentage
oramount_money
should be set, but not both.
- source_service_charge_uid string? - The service charge
uid
from the order containing the original service charge.source_service_charge_uid
isnull
for unlinked returns.
- taxable boolean? - Indicates whether the surcharge can be taxed. Service charges
calculated in the
TOTAL_PHASE
cannot be marked as taxable.
- total_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- total_tax_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- uid string? - A unique ID that identifies the return service charge only within this order.
squareup: OrderReturnTax
Represents a tax being returned that applies to one or more return line items in an order.
Fixed-amount, order-scoped taxes are distributed across all non-zero return line item totals. The amount distributed to each return line item is relative to that item’s contribution to the order subtotal.
Fields
- applied_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- catalog_object_id string? - The catalog object ID referencing CatalogTax.
- catalog_version int? - The version of the catalog object that this tax references.
- name string? - The tax's name.
- percentage string? - The percentage of the tax, as a string representation of a decimal number.
For example, a value of
"7.25"
corresponds to a percentage of 7.25%.
- scope string? - Indicates the level at which the
OrderReturnTax
applies. ForORDER
scoped taxes, Square generates references inapplied_taxes
on allOrderReturnLineItem
s. ForLINE_ITEM
scoped taxes, the tax is only applied toOrderReturnLineItem
s with references in theirapplied_discounts
field.
- source_tax_uid string? - The tax
uid
from the order that contains the original tax charge.
- 'type string? - Indicates the calculation method used to apply the tax.
- uid string? - A unique ID that identifies the returned tax only within this order.
squareup: OrderReward
Represents a reward that can be applied to an order if the necessary reward tier criteria are met. Rewards are created through the Loyalty API.
Fields
- id string - The identifier of the reward.
- reward_tier_id string - The identifier of the reward tier corresponding to this reward.
squareup: OrderRoundingAdjustment
A rounding adjustment of the money being returned. Commonly used to apply cash rounding when the minimum unit of the account is smaller than the lowest physical denomination of the currency.
Fields
- amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- name string? - The name of the rounding adjustment from the original sale order.
- uid string? - A unique ID that identifies the rounding adjustment only within this order.
squareup: OrderServiceCharge
Represents a service charge applied to an order.
Fields
- amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- applied_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- applied_taxes OrderLineItemAppliedTax[]? - The list of references to the taxes applied to this service charge. Each
OrderLineItemAppliedTax
has atax_uid
that references theuid
of a top-levelOrderLineItemTax
that is being applied to this service charge. On reads, the amount applied is populated. AnOrderLineItemAppliedTax
is automatically created on every taxable service charge for allORDER
scoped taxes that are added to the order.OrderLineItemAppliedTax
records forLINE_ITEM
scoped taxes must be added in requests for the tax to apply to any taxable service charge. Taxable service charges have thetaxable
field set totrue
and calculated in theSUBTOTAL_PHASE
. To change the amount of a tax, modify the referenced top-level tax.
- calculation_phase string? - The calculation phase at which to apply the service charge.
- catalog_object_id string? - The catalog object ID referencing the service charge CatalogObject.
- catalog_version int? - The version of the catalog object that this service charge references.
- metadata record {}? - Application-defined data attached to this service charge. Metadata fields are intended
to store descriptive references or associations with an entity in another system or store brief
information about the object. Square does not process this field; it only stores and returns it
in relevant API calls. Do not use metadata to store any sensitive information (such as personally
identifiable information or card details).
Keys written by applications must be 60 characters or less and must be in the character set
[a-zA-Z0-9_-]
. Entries can also include metadata generated by Square. These keys are prefixed with a namespace, separated from the key with a ':' character. Values have a maximum length of 255 characters. An application can have up to 10 entries per metadata field. Entries written by applications are private and can only be read or modified by the same application. For more information, see Metadata.
- name string? - The name of the service charge.
- percentage string? - The service charge percentage as a string representation of a
decimal number. For example,
"7.25"
indicates a service charge of 7.25%. Exactly 1 ofpercentage
oramount_money
should be set.
- taxable boolean? - Indicates whether the service charge can be taxed. If set to
true
, order-level taxes automatically apply to the service charge. Note that service charges calculated in theTOTAL_PHASE
cannot be marked as taxable.
- total_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- total_tax_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- 'type string? - The type of the service charge.
- uid string? - A unique ID that identifies the service charge only within this order.
squareup: OrderSource
Represents the origination details of an order.
Fields
- name string? - The name used to identify the place (physical or digital) that an order originates. If unset, the name defaults to the name of the application that created the order.
squareup: OrderUpdated
Fields
- created_at string? - The timestamp for when the order was created, in RFC 3339 format.
- location_id string? - The ID of the seller location that this order is associated with.
- order_id string? - The order's unique ID.
- state string? - The state of the order.
- updated_at string? - The timestamp for when the order was last updated, in RFC 3339 format.
- 'version int? - The version number, which is incremented each time an update is committed to the order. Orders that were not created through the API do not include a version number and therefore cannot be updated. Read more about working with versions.
squareup: OrderUpdatedObject
Fields
- order_updated OrderUpdated? -
squareup: Payment
Represents a payment processed by the Square API.
Fields
- amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- app_fee_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- approved_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- bank_account_details BankAccountPaymentDetails? - Additional details about BANK_ACCOUNT type payments.
- billing_address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- buyer_email_address string? - The buyer's email address.
- capabilities string[]? - Actions that can be performed on this payment:
EDIT_AMOUNT_UP
- The payment amount can be edited up.EDIT_AMOUNT_DOWN
- The payment amount can be edited down.EDIT_TIP_AMOUNT_UP
- The tip amount can be edited up.EDIT_TIP_AMOUNT_DOWN
- The tip amount can be edited down.
- card_details CardPaymentDetails? - Reflects the current status of a card payment. Contains only non-confidential information.
- cash_details CashPaymentDetails? - Stores details about a cash payment. Contains only non-confidential information. For more information, see Take Cash Payments.
- created_at string? - The timestamp of when the payment was created, in RFC 3339 format.
- delay_action string? - The action to be applied to the payment when the
delay_duration
has elapsed. This field is read-only. Current values includeCANCEL
.
- delay_duration string? - The duration of time after the payment's creation when Square automatically applies the
delay_action
to the payment. This automaticdelay_action
applies only to payments that do not reach a terminal state (COMPLETED, CANCELED, or FAILED) before thedelay_duration
time period. This field is specified as a time duration, in RFC 3339 format. Notes: This feature is only supported for card payments. Default:- Card-present payments: "PT36H" (36 hours) from the creation time.
- Card-not-present payments: "P7D" (7 days) from the creation time.
- delayed_until string? - The read-only timestamp of when the
delay_action
is automatically applied, in RFC 3339 format. Note that this field is calculated by summing the payment'sdelay_duration
andcreated_at
fields. Thecreated_at
field is generated by Square and might not exactly match the time on your local machine.
- employee_id string? - An optional ID of the employee associated with taking the payment.
- external_details ExternalPaymentDetails? - Stores details about an external payment. Contains only non-confidential information. For more information, see Take External Payments.
- id string? - A unique ID for the payment.
- location_id string? - The ID of the location associated with the payment.
- note string? - An optional note to include when creating a payment.
- order_id string? - The ID of the order associated with the payment.
- processing_fee ProcessingFee[]? - The processing fees and fee adjustments assessed by Square for this payment.
- receipt_number string? - The payment's receipt number. The field is missing if a payment is canceled.
- receipt_url string? - The URL for the payment's receipt. The field is only populated for COMPLETED payments.
- reference_id string? - An optional ID that associates the payment with an entity in another system.
- refund_ids string[]? - A list of
refund_id
s identifying refunds for the payment.
- refunded_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- risk_evaluation RiskEvaluation? - Represents fraud risk information for the associated payment.
When you take a payment through Square's Payments API (using the
CreatePayment
endpoint), Square evaluates it and assigns a risk level to the payment. Sellers can use this information to determine the course of action (for example, provide the goods/services or refund the payment).
- shipping_address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- source_type string? - The source type for this payment.
Current values include
CARD
,BANK_ACCOUNT
,WALLET
,CASH
, orEXTERNAL
.
- statement_description_identifier string? - Additional payment information that gets added to the customer's card statement
as part of the statement description.
Note that the
statement_description_identifier
might get truncated on the statement description to fit the required information including the Square identifier (SQ *) and the name of the seller taking the payment.
- status string? - Indicates whether the payment is APPROVED, PENDING, COMPLETED, CANCELED, or FAILED.
- tip_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- total_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- updated_at string? - The timestamp of when the payment was last updated, in RFC 3339 format.
- version_token string? - Used for optimistic concurrency. This opaque token identifies a specific version of the
Payment
object.
- wallet_details DigitalWalletDetails? - Additional details about
WALLET
type payments. Contains only non-confidential information.
squareup: PaymentOptions
Fields
- autocomplete boolean? - Indicates whether the
Payment
objects created from thisTerminalCheckout
are automaticallyCOMPLETED
or left in anAPPROVED
state for later modification.
squareup: PaymentRefund
Represents a refund of a payment made using Square. Contains information about the original payment and the amount of money refunded.
Fields
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- app_fee_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- created_at string? - The timestamp of when the refund was created, in RFC 3339 format.
- id string - The unique ID for this refund, generated by Square.
- location_id string? - The location ID associated with the payment this refund is attached to.
- order_id string? - The ID of the order associated with the refund.
- payment_id string? - The ID of the payment associated with this refund.
- processing_fee ProcessingFee[]? - Processing fees and fee adjustments assessed by Square for this refund.
- reason string? - The reason for the refund.
- status string? - The refund's status:
PENDING
- Awaiting approval.COMPLETED
- Successfully completed.REJECTED
- The refund was rejected.FAILED
- An error occurred.
- updated_at string? - The timestamp of when the refund was last updated, in RFC 3339 format.
squareup: PayOrderRequest
Defines the fields that are included in requests to the PayOrder endpoint.
Fields
- idempotency_key string - A value you specify that uniquely identifies this request among requests you have sent. If you are unsure whether a particular payment request was completed successfully, you can reattempt it with the same idempotency key without worrying about duplicate payments. For more information, see Idempotency.
- order_version int? - The version of the order being paid. If not supplied, the latest version will be paid.
squareup: PayOrderResponse
Defines the fields that are included in the response body of a request to the PayOrder endpoint.
Fields
- errors Error[]? - Any errors that occurred during the request.
- 'order Order? - Contains all information related to a single order to process with Square,
including line items that specify the products to purchase.
Order
objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.
squareup: ProcessingFee
Represents the Square processing fee.
Fields
- amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- effective_at string? - The timestamp of when the fee takes effect, in RFC 3339 format.
- 'type string? - The type of fee assessed or adjusted. The fee type can be
INITIAL
orADJUSTMENT
.
squareup: ProxyConfig
Proxy server configurations to be used with the HTTP client endpoint.
Fields
- host string(default "") - Host name of the proxy server
- port int(default 0) - Proxy server port
- userName string(default "") - Proxy server username
- password string(default "") - Proxy server password
squareup: PublishInvoiceRequest
Describes a PublishInvoice
request.
Fields
- idempotency_key string? - A unique string that identifies the
PublishInvoice
request. If you do not provideidempotency_key
(or provide an empty string as the value), the endpoint treats each request as independent. For more information, see Idempotency.
squareup: PublishInvoiceResponse
Describes a PublishInvoice
response.
Fields
- errors Error[]? - Information about errors encountered during the request.
- invoice Invoice? - Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see Manage Invoices Using the Invoices API.
squareup: QuantityRatio
A whole number or unreduced fractional ratio.
Fields
- quantity int? - The whole or fractional quantity as the numerator.
- quantity_denominator int? - The whole or fractional quantity as the denominator.
In the case of fractional quantity this field is the denominator and quantity is the numerator.
When unspecified, the value is
1
. For example, whenquantity=3
andquantity_donominator
is unspecified, the quantity ratio is3
or3/1
.
squareup: Range
The range of a number value between the specified lower and upper bounds.
Fields
- max string? - The upper bound of the number range.
- min string? - The lower bound of the number range.
squareup: RedeemLoyaltyRewardRequest
A request to redeem a loyalty reward.
Fields
- idempotency_key string - A unique string that identifies this
RedeemLoyaltyReward
request. Keys can be any valid string, but must be unique for every request.
squareup: RedeemLoyaltyRewardResponse
A response that includes the LoyaltyEvent
published for redeeming the reward.
Fields
- errors Error[]? - Any errors that occurred during the request.
- event LoyaltyEvent? - Provides information about a loyalty event. For more information, see Loyalty events.
squareup: Refund
Represents a refund processed for a Square transaction.
Fields
- additional_recipients AdditionalRecipient[]? - Additional recipients (other than the merchant) receiving a portion of this refund. For example, fees assessed on a refund of a purchase by a third party integration.
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- created_at string? - The timestamp for when the refund was created, in RFC 3339 format.
- id string - The refund's unique ID.
- location_id string - The ID of the refund's associated location.
- processing_fee_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- reason string - The reason for the refund being issued.
- status string - The current status of the refund (
PENDING
,APPROVED
,REJECTED
, orFAILED
).
- tender_id string - The ID of the refunded tender.
- transaction_id string - The ID of the transaction that the refunded tender is part of.
squareup: RefundPaymentRequest
Describes a request to refund a payment using RefundPayment.
Fields
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- app_fee_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- idempotency_key string - A unique string that identifies this
RefundPayment
request. The key can be any valid string but must be unique for everyRefundPayment
request. For more information, see Idempotency.
- payment_id string - The unique ID of the payment being refunded.
- reason string? - A description of the reason for the refund.
squareup: RefundPaymentResponse
Defines the response returned by RefundPayment.
If there are errors processing the request, the refund
field might not be
present, or it might be present with a status of FAILED
.
Fields
- errors Error[]? - Information about errors encountered during the request.
- refund PaymentRefund? - Represents a refund of a payment made using Square. Contains information about the original payment and the amount of money refunded.
squareup: RegisterDomainRequest
Defines the parameters that can be included in the body of a request to the RegisterDomain endpoint.
Fields
- domain_name string - A domain name as described in RFC-1034 that will be registered with ApplePay.
squareup: RegisterDomainResponse
Defines the fields that are included in the response body of a request to the RegisterDomain endpoint.
Either errors
or status
are present in a given response (never both).
Fields
- errors Error[]? - Any errors that occurred during the request.
- status string? - The status of the domain registration. See RegisterDomainResponseStatus for possible values.
squareup: RemoveGroupFromCustomerRequest
Defines the fields that are included in the request body of a request to the RemoveGroupFromCustomer endpoint.
squareup: RemoveGroupFromCustomerResponse
Defines the fields that are included in the response body of a request to the RemoveGroupFromCustomer endpoint.
Fields
- errors Error[]? - Any errors that occurred during the request.
squareup: RenewTokenRequest
Fields
- access_token string? - The token you want to renew.
squareup: RenewTokenResponse
Fields
- access_token string? - The renewed access token.
This value might be different from the
access_token
you provided in your request. You provide this token in a header with every request to Connect API endpoints. See Request and response headers for the format of this header.
- merchant_id string? - The ID of the authorizing merchant's business.
- plan_id string? - LEGACY FIELD. The ID of the subscription plan the merchant signed up for. Only present if the merchant signed up for a subscription during authorization.
- subscription_id string? - LEGACY FIELD. The ID of the merchant subscription associated with the authorization. Only present if the merchant signed up for a subscription during authorization..
- token_type string? - This value is always bearer.
squareup: ResumeSubscriptionRequest
Defines parameters in a ResumeSubscription endpoint request.
squareup: ResumeSubscriptionResponse
Defines parameters in a ResumeSubscription endpoint response.
Fields
- errors Error[]? - Information about errors encountered during the request.
- subscription Subscription? - Represents a customer subscription to a subscription plan.
For an overview of the
Subscription
type, see Subscription object.
squareup: RetrieveBookingRequest
squareup: RetrieveBookingResponse
Fields
- booking 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.
- errors Error[]? - Any errors that occurred during the request.
squareup: RetrieveBusinessBookingProfileRequest
squareup: RetrieveBusinessBookingProfileResponse
Fields
- business_booking_profile BusinessBookingProfile? -
- errors Error[]? - Any errors that occurred during the request.
squareup: RetrieveCardRequest
Retrieves details for a specific Card. Accessible via HTTP requests at GET https://connect.squareup.com/v2/cards/{card_id}
squareup: RetrieveCardResponse
Defines the fields that are included in the response body of a request to the RetrieveCard endpoint.
Note: if there are errors processing the request, the card field will not be present.
Fields
- card Card? - Represents the payment details of a card to be used for payments. These details are determined by the payment token generated by Web Payments SDK.
- errors Error[]? - Information on errors encountered during the request.
squareup: RetrieveCashDrawerShiftRequest
Fields
- location_id string - The ID of the location to retrieve cash drawer shifts from.
squareup: RetrieveCashDrawerShiftResponse
Fields
- cash_drawer_shift CashDrawerShift? - This model gives the details of a cash drawer shift. The cash_payment_money, cash_refund_money, cash_paid_in_money, and cash_paid_out_money fields are all computed by summing their respective event types.
- errors Error[]? - Any errors that occurred during the request.
squareup: RetrieveCatalogObjectRequest
Fields
- catalog_version int? - Requests objects as of a specific version of the catalog. This allows you to retrieve historical versions of objects. The value to retrieve a specific version of an object can be found in the version field of CatalogObjects.
- include_related_objects boolean? - If
true
, the response will include additional objects that are related to the requested object, as follows: If theobject
field of the response contains aCatalogItem
, its associatedCatalogCategory
,CatalogTax
,CatalogImage
andCatalogModifierList
objects will be returned in therelated_objects
field of the response. If theobject
field of the response contains aCatalogItemVariation
, its parentCatalogItem
will be returned in therelated_objects
field of the response. Default value:false
squareup: RetrieveCatalogObjectResponse
Fields
- errors Error[]? - Any errors that occurred during the request.
- 'object CatalogObject? - The wrapper object for the Catalog entries of a given object type.
The type of a particular
CatalogObject
is determined by the value of thetype
attribute and only the corresponding data attribute can be set on theCatalogObject
instance. For example, the following list shows some instances ofCatalogObject
of a giventype
and their corresponding data attribute that can be set:- For a
CatalogObject
of theITEM
type, set theitem_data
attribute to yield theCatalogItem
object. - For a
CatalogObject
of theITEM_VARIATION
type, set theitem_variation_data
attribute to yield theCatalogItemVariation
object. - For a
CatalogObject
of theMODIFIER
type, set themodifier_data
attribute to yield theCatalogModifier
object. - For a
CatalogObject
of theMODIFIER_LIST
type, set themodifier_list_data
attribute to yield theCatalogModifierList
object. - For a
CatalogObject
of theCATEGORY
type, set thecategory_data
attribute to yield theCatalogCategory
object. - For a
CatalogObject
of theDISCOUNT
type, set thediscount_data
attribute to yield theCatalogDiscount
object. - For a
CatalogObject
of theTAX
type, set thetax_data
attribute to yield theCatalogTax
object. - For a
CatalogObject
of theIMAGE
type, set theimage_data
attribute to yield theCatalogImageData
object. - For a
CatalogObject
of theQUICK_AMOUNTS_SETTINGS
type, set thequick_amounts_settings_data
attribute to yield theCatalogQuickAmountsSettings
object. - For a
CatalogObject
of thePRICING_RULE
type, set thepricing_rule_data
attribute to yield theCatalogPricingRule
object. - For a
CatalogObject
of theTIME_PERIOD
type, set thetime_period_data
attribute to yield theCatalogTimePeriod
object. - For a
CatalogObject
of thePRODUCT_SET
type, set theproduct_set_data
attribute to yield theCatalogProductSet
object. - For a
CatalogObject
of theSUBSCRIPTION_PLAN
type, set thesubscription_plan_data
attribute to yield theCatalogSubscriptionPlan
object.
- For a
- related_objects CatalogObject[]? - A list of
CatalogObject
s referenced by the object in theobject
field.
squareup: RetrieveCustomerGroupRequest
Defines the fields that can be included in a request to the RetrieveCustomerGroup endpoint.
squareup: RetrieveCustomerGroupResponse
Defines the fields that are included in the response body of a request to the RetrieveCustomerGroup endpoint.
Either errors
or group
is present in a given response (never both).
Fields
- errors Error[]? - Any errors that occurred during the request.
- group CustomerGroup? - Represents a group of customer profiles. Customer groups can be created, be modified, and have their membership defined using the Customers API or within the Customer Directory in the Square Seller Dashboard or Point of Sale.
squareup: RetrieveCustomerRequest
Defines the fields that are included in requests to the RetrieveCustomer
endpoint.
squareup: RetrieveCustomerResponse
Defines the fields that are included in the response body of
a request to the RetrieveCustomer
endpoint.
Either errors
or customer
is present in a given response (never both).
Fields
- customer Customer? - Represents a Square customer profile in the Customer Directory of a Square seller.
- errors Error[]? - Any errors that occurred during the request.
squareup: RetrieveCustomerSegmentRequest
Defines the valid parameters for requests to the RetrieveCustomerSegmentRequest
endpoint.
squareup: RetrieveCustomerSegmentResponse
Defines the fields that are included in the response body for requests to the RetrieveCustomerSegment
endpoint.
Either errors
or segment
is present in a given response (never both).
Fields
- errors Error[]? - Any errors that occurred during the request.
- segment CustomerSegment? - Represents a group of customer profiles that match one or more predefined filter criteria. Segments (also known as Smart Groups) are defined and created within the Customer Directory in the Square Seller Dashboard or Point of Sale.
squareup: RetrieveDisputeEvidenceRequest
Defines the parameters for a RetrieveDisputeEvidence
request.
squareup: RetrieveDisputeEvidenceResponse
Defines the fields in a RetrieveDisputeEvidence
response.
Fields
- errors Error[]? - Any errors that occurred during the request.
- evidence DisputeEvidence? -
squareup: RetrieveDisputeRequest
Defines the request parameters for the RetrieveDispute
endpoint.
squareup: RetrieveDisputeResponse
Defines fields in a RetrieveDispute
response.
Fields
- dispute Dispute? - Represents a dispute a cardholder initiated with their bank.
- errors Error[]? - Information about errors encountered during the request.
squareup: RetrieveEmployeeRequest
squareup: RetrieveEmployeeResponse
Fields
- employee Employee? - An employee object that is used by the external API.
- errors Error[]? - Any errors that occurred during the request.
squareup: RetrieveGiftCardFromGANRequest
A request to retrieve gift cards by their GANs.
Fields
- gan string - The gift card account number (GAN) of the gift card to retrieve. The maximum length of a GAN is 255 digits to account for third-party GANs that have been imported. Square-issued gift cards have 16-digit GANs.
squareup: RetrieveGiftCardFromGANResponse
A response that contains a GiftCard
. This response might contain a set of Error
objects
if the request resulted in errors.
Fields
- errors Error[]? - Any errors that occurred during the request.
- gift_card GiftCard? - Represents a Square gift card.
squareup: RetrieveGiftCardFromNonceRequest
A request to retrieve gift cards by using nonces.
Fields
- nonce string - The nonce of the gift card to retrieve.
squareup: RetrieveGiftCardFromNonceResponse
A response that contains a GiftCard
. The response might contain a set of Error
objects
if the request resulted in errors.
Fields
- errors Error[]? - Any errors that occurred during the request.
- gift_card GiftCard? - Represents a Square gift card.
squareup: RetrieveGiftCardRequest
A request to retrieve digital gift cards.
squareup: RetrieveGiftCardResponse
A response that contains a GiftCard
. The response might contain a set of Error
objects
if the request resulted in errors.
Fields
- errors Error[]? - Any errors that occurred during the request.
- gift_card GiftCard? - Represents a Square gift card.
squareup: RetrieveInventoryAdjustmentRequest
squareup: RetrieveInventoryAdjustmentResponse
Fields
- adjustment InventoryAdjustment? - Represents a change in state or quantity of product inventory at a particular time and location.
- errors Error[]? - Any errors that occurred during the request.
squareup: RetrieveInventoryChangesRequest
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See the Pagination guide for more information.
squareup: RetrieveInventoryChangesResponse
Fields
- changes InventoryChange[]? - The set of inventory changes for the requested object and locations.
- cursor string? - The pagination cursor to be used in a subsequent request. If unset, this is the final response. See the Pagination guide for more information.
- errors Error[]? - Any errors that occurred during the request.
squareup: RetrieveInventoryCountRequest
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. See the Pagination guide for more information.
squareup: RetrieveInventoryCountResponse
Fields
- counts InventoryCount[]? - The current calculated inventory counts for the requested object and locations.
- cursor string? - The pagination cursor to be used in a subsequent request. If unset, this is the final response. See the Pagination guide for more information.
- errors Error[]? - Any errors that occurred during the request.
squareup: RetrieveInventoryPhysicalCountRequest
squareup: RetrieveInventoryPhysicalCountResponse
Fields
- count 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. For example, a physical count might come from an employee counting the item variations on hand or from syncing with an external system.
- errors Error[]? - Any errors that occurred during the request.
squareup: RetrieveInventoryTransferRequest
squareup: RetrieveInventoryTransferResponse
Fields
- errors Error[]? - Any errors that occurred during the request.
- transfer InventoryTransfer? - Represents the transfer of a quantity of product inventory at a particular time from one location to another.
squareup: RetrieveLocationRequest
Defines the fields that are included in the request body for the RetrieveLocation endpoint.
squareup: RetrieveLocationResponse
Defines the fields that the RetrieveLocation endpoint returns in a response.
Fields
- errors Error[]? - Information on errors encountered during the request.
- location Location? -
squareup: RetrieveLoyaltyAccountRequest
A request to retrieve a loyalty account.
squareup: RetrieveLoyaltyAccountResponse
A response that includes the loyalty account.
Fields
- errors Error[]? - Any errors that occurred during the request.
- loyalty_account LoyaltyAccount? - Describes a loyalty account. For more information, see Manage Loyalty Accounts Using the Loyalty API.
squareup: RetrieveLoyaltyProgramRequest
A request to retrieve the loyalty program that belongs to a seller. A seller can have only one loyalty program.
squareup: RetrieveLoyaltyProgramResponse
A response that contains the loyalty program.
Fields
- errors Error[]? - Any errors that occurred during the request.
- program LoyaltyProgram? - Represents a Square loyalty program. Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see Loyalty Program Overview.
squareup: RetrieveLoyaltyRewardRequest
A request to retrieve a loyalty reward.
squareup: RetrieveLoyaltyRewardResponse
A response that includes the loyalty reward.
Fields
- errors Error[]? - Any errors that occurred during the request.
- reward LoyaltyReward? - Represents a contract to redeem loyalty points for a reward tier discount. Loyalty rewards can be in an ISSUED, REDEEMED, or DELETED state. For more information, see Redeem loyalty rewards.
squareup: RetrieveMerchantRequest
Request object for the RetrieveMerchant endpoint.
squareup: RetrieveMerchantResponse
The response object returned by the RetrieveMerchant endpoint.
Fields
- errors Error[]? - Information on errors encountered during the request.
- merchant Merchant? - Represents a Square seller.
squareup: RetrieveObsMigrationProfileRequest
squareup: RetrieveOrderRequest
squareup: RetrieveOrderResponse
Fields
- errors Error[]? - Any errors that occurred during the request.
- 'order Order? - Contains all information related to a single order to process with Square,
including line items that specify the products to purchase.
Order
objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.
squareup: RetrieveSnippetRequest
Represents a RetrieveSnippet
request.
squareup: RetrieveSnippetResponse
Represents a RetrieveSnippet
response. The response can include either snippet
or errors
.
Fields
- errors Error[]? - Any errors that occurred during the request.
- snippet Snippet? - Represents the snippet that is added to a Square Online site. The snippet code is injected into the
head
element of all pages on the site, except for checkout pages.
squareup: RetrieveSubscriptionRequest
Defines parameters in a RetrieveSubscription endpoint request.
squareup: RetrieveSubscriptionResponse
Defines the fields that are included in the response from the RetrieveSubscription endpoint.
Fields
- errors Error[]? - Information about errors encountered during the request.
- subscription Subscription? - Represents a customer subscription to a subscription plan.
For an overview of the
Subscription
type, see Subscription object.
squareup: RetrieveTeamMemberBookingProfileRequest
squareup: RetrieveTeamMemberBookingProfileResponse
Fields
- errors Error[]? - Any errors that occurred during the request.
- team_member_booking_profile TeamMemberBookingProfile? - 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.
squareup: RetrieveTeamMemberRequest
Represents a retrieve request for a TeamMember
object.
squareup: RetrieveTeamMemberResponse
Represents a response from a retrieve request containing a TeamMember
object or error messages.
Fields
- errors Error[]? - The errors that occurred during the request.
- team_member TeamMember? - A record representing an individual team member for a business.
squareup: RetrieveTransactionRequest
squareup: RetrieveTransactionResponse
Defines the fields that are included in the response body of a request to the RetrieveTransaction endpoint.
One of errors
or transaction
is present in a given response (never both).
Fields
- errors Error[]? - Any errors that occurred during the request.
- 'transaction Transaction? - Represents a transaction processed with Square, either with the
Connect API or with Square Point of Sale.
The
tenders
field of this object lists all methods of payment used to pay in the transaction.
squareup: RetrieveWageSettingRequest
Represents a retrieve request for the wage setting of a team member.
squareup: RetrieveWageSettingResponse
Represents a response from a retrieve request containing the specified WageSetting
object or error messages.
Fields
- errors Error[]? - The errors that occurred during the request.
- wage_setting WageSetting? - An object representing a team member's wage information.
squareup: RevokeTokenRequest
Fields
- access_token string? - The access token of the merchant whose token you want to revoke. Do not provide a value for merchant_id if you provide this parameter.
- client_id string? - The Square issued ID for your application, available from the developer dashboard.
- merchant_id string? - The ID of the merchant whose token you want to revoke. Do not provide a value for access_token if you provide this parameter.
- revoke_only_access_token boolean? - If
true
, terminate the given single access token, but do not terminate the entire authorization. Default:false
squareup: RevokeTokenResponse
Fields
- success boolean? - If the request is successful, this is true.
squareup: RiskEvaluation
Represents fraud risk information for the associated payment.
When you take a payment through Square's Payments API (using the CreatePayment
endpoint), Square evaluates it and assigns a risk level to the payment. Sellers
can use this information to determine the course of action (for example,
provide the goods/services or refund the payment).
Fields
- created_at string? - The timestamp when payment risk was evaluated, in RFC 3339 format.
- risk_level string? - The risk level associated with the payment
squareup: SearchAvailabilityFilter
A query filter to search for availabilities by.
Fields
- booking_id string? - The query expression to search for availabilities for an existing booking by matching the specified
booking_id
value. This is commonly used to reschedule an appointment. If this expression is specified, thelocation_id
andsegment_filters
expressions are not allowed.
- location_id string? - The query expression to search for availabilities matching the specified seller location IDs.
This query expression is not applicable when
booking_id
is present.
- segment_filters SegmentFilter[]? - The list of segment filters to apply. A query with
n
segment filters returns availabilities withn
segments per availability. It is not applicable whenbooking_id
is present.
- start_at_range TimeRange - Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
squareup: SearchAvailabilityQuery
Query conditions to search for availabilities of bookings.
Fields
- filter SearchAvailabilityFilter - A query filter to search for availabilities by.
squareup: SearchAvailabilityRequest
Fields
- query SearchAvailabilityQuery - Query conditions to search for availabilities of bookings.
squareup: SearchAvailabilityResponse
Fields
- availabilities Availability[]? - List of slots available for booking.
- errors Error[]? - Any errors that occurred during the request.
squareup: SearchCatalogItemsRequest
Defines the request body for the SearchCatalogItems endpoint.
Fields
- category_ids string[]? - The category id query expression to return items containing the specified category IDs.
- cursor string? - The pagination token, returned in the previous response, used to fetch the next batch of pending results.
- custom_attribute_filters CustomAttributeFilter[]? - The customer-attribute filter to return items or item variations matching the specified custom attribute expressions. A maximum number of 10 custom attribute expressions are supported in a single call to the SearchCatalogItems endpoint.
- enabled_location_ids string[]? - The enabled-location query expression to return items and item variations having specified enabled locations.
- 'limit int? - The maximum number of results to return per page. The default value is 100.
- product_types string[]? - The product types query expression to return items or item variations having the specified product types.
- sort_order string? - The order to sort the results by item names. The default sort order is ascending (
ASC
).
- stock_levels string[]? - The stock-level query expression to return item variations with the specified stock levels.
- text_filter string? - The text filter expression to return items or item variations containing specified text in
the
name
,description
, orabbreviation
attribute value of an item, or in thename
,sku
, orupc
attribute value of an item variation.
squareup: SearchCatalogItemsResponse
Defines the response body returned from the SearchCatalogItems endpoint.
Fields
- cursor string? - Pagination token used in the next request to return more of the search result.
- errors Error[]? - Any errors that occurred during the request.
- items CatalogObject[]? - Returned items matching the specified query expressions.
- matched_variation_ids string[]? - Ids of returned item variations matching the specified query expression.
squareup: SearchCatalogObjectsRequest
Fields
- cursor string? - The pagination cursor returned in the previous response. Leave unset for an initial request. See Pagination for more information.
- include_deleted_objects boolean? - If
true
, deleted objects will be included in the results. Deleted objects will have theiris_deleted
field set totrue
.
- include_related_objects boolean? - If
true
, the response will include additional objects that are related to the requested object, as follows: If a CatalogItem is returned in the object field of the response, its associated CatalogCategory, CatalogTax objects, CatalogImage objects and CatalogModifierList objects will be included in therelated_objects
field of the response. If a CatalogItemVariation is returned in the object field of the response, its parent CatalogItem will be included in therelated_objects
field of the response.
- 'limit int? - A limit on the number of results to be returned in a single page. The limit is advisory - the implementation may return more or fewer results. If the supplied limit is negative, zero, or is higher than the maximum limit of 1,000, it will be ignored.
- object_types string[]? - The desired set of object types to appear in the search results.
- query CatalogQuery? - A query composed of one or more different types of filters to narrow the scope of targeted objects when calling the
SearchCatalogObjects
endpoint. Although a query can have multiple filters, only certain query types can be combined per call to SearchCatalogObjects. Any combination of the following types may be used together:- exact_query
- prefix_query
- range_query
- sorted_attribute_query
- text_query All other query types cannot be combined with any others.
- Searchable attribute and objects queryable by searchable attributes **
name
:CatalogItem
,CatalogItemVariation
,CatalogCategory
,CatalogTax
,CatalogDiscount
,CatalogModifier
, 'CatalogModifierList,
CatalogItemOption,
CatalogItemOptionValueMISSING[] MISSING[
]-description
:CatalogItem
,CatalogItemOptionValue
abbreviation
:CatalogItem
upc
:CatalogItemVariation
sku
:CatalogItemVariation
caption
:CatalogImage
display_name
:CatalogItemOption
"name"
,"description"
, or"abbreviation"
attribute in an applicable query filter.
squareup: SearchCatalogObjectsResponse
Fields
- cursor string? - The pagination cursor to be used in a subsequent request. If unset, this is the final response. See Pagination for more information.
- errors Error[]? - Any errors that occurred during the request.
- latest_time string? - When the associated product catalog was last updated. Will
match the value for
end_time
orcursor
if either field is included in theSearchCatalog
request.
- objects CatalogObject[]? - The CatalogObjects returned.
- related_objects CatalogObject[]? - A list of CatalogObjects referenced by the objects in the
objects
field.
squareup: SearchCustomersRequest
Defines the fields that are included in the request body of a request to the
SearchCustomers
endpoint.
Fields
- cursor string? - Include the pagination cursor in subsequent calls to this endpoint to retrieve the next set of results associated with the original query. For more information, see Pagination.
- 'limit int? - The maximum number of results to return in a single page. This limit is advisory. The response might contain more or fewer results. The limit is ignored if it is less than the minimum or greater than the maximum value. The default value is 100. For more information, see Pagination.
- query CustomerQuery? - Represents a query (including filtering criteria, sorting criteria, or both) used to search for customer profiles.
squareup: SearchCustomersResponse
Defines the fields that are included in the response body of
a request to the SearchCustomers
endpoint.
Either errors
or customers
is present in a given response (never both).
Fields
- cursor string? - A pagination cursor that can be used during subsequent calls
to
SearchCustomers
to retrieve the next set of results associated with the original query. Pagination cursors are only present when a request succeeds and additional results are available. For more information, see Pagination.
- customers Customer[]? - An array of
Customer
objects that match a query.
- errors Error[]? - Any errors that occurred during the request.
squareup: SearchInvoicesRequest
Describes a SearchInvoices
request.
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see Pagination.
- 'limit int? - The maximum number of invoices to return (200 is the maximum
limit
). If not provided, the server uses a default limit of 100 invoices.
- query InvoiceQuery - Describes query criteria for searching invoices.
squareup: SearchInvoicesResponse
Describes a SearchInvoices
response.
Fields
- cursor string? - When a response is truncated, it includes a cursor that you can use in a subsequent request to fetch the next set of invoices. If empty, this is the final response. For more information, see Pagination.
- errors Error[]? - Information about errors encountered during the request.
- invoices Invoice[]? - The list of invoices returned by the search.
squareup: SearchLoyaltyAccountsRequest
A request to search for loyalty accounts.
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. For more information, see Pagination.
- 'limit int? - The maximum number of results to include in the response.
- query SearchLoyaltyAccountsRequestLoyaltyAccountQuery? - The search criteria for the loyalty accounts.
squareup: SearchLoyaltyAccountsRequestLoyaltyAccountQuery
The search criteria for the loyalty accounts.
Fields
- customer_ids string[]? - The set of customer IDs to use in the loyalty account search.
This cannot be combined with
mappings
. Max: 30 customer IDs
- mappings LoyaltyAccountMapping[]? - The set of mappings to use in the loyalty account search.
This cannot be combined with
customer_ids
. Max: 30 mappings
squareup: SearchLoyaltyAccountsResponse
A response that includes loyalty accounts that satisfy the search criteria.
Fields
- cursor string? - The pagination cursor to use in a subsequent request. If empty, this is the final response. For more information, see Pagination.
- errors Error[]? - Any errors that occurred during the request.
- loyalty_accounts LoyaltyAccount[]? - The loyalty accounts that met the search criteria,
in order of creation date.
squareup: SearchLoyaltyEventsRequest
A request to search for loyalty events.
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for your original query. For more information, see Pagination.
- 'limit int? - The maximum number of results to include in the response. The last page might contain fewer events. The default is 30 events.
- query LoyaltyEventQuery? - Represents a query used to search for loyalty events.
squareup: SearchLoyaltyEventsResponse
A response that contains loyalty events that satisfy the search
criteria, in order by the created_at
date.
Fields
- cursor string? - The pagination cursor to be used in a subsequent request. If empty, this is the final response. For more information, see Pagination.
- errors Error[]? - Any errors that occurred during the request.
- events LoyaltyEvent[]? - The loyalty events that satisfy the search criteria.
squareup: SearchLoyaltyRewardsRequest
A request to search for loyalty rewards.
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. For more information, see Pagination.
- 'limit int? - The maximum number of results to return in the response.
- query SearchLoyaltyRewardsRequestLoyaltyRewardQuery? - The set of search requirements.
squareup: SearchLoyaltyRewardsRequestLoyaltyRewardQuery
The set of search requirements.
Fields
- loyalty_account_id string - The ID of the loyalty account to which the loyalty reward belongs.
- status string? - The status of the loyalty reward.
squareup: SearchLoyaltyRewardsResponse
A response that includes the loyalty rewards satisfying the search criteria.
Fields
- cursor string? - The pagination cursor to be used in a subsequent request. If empty, this is the final response.
- errors Error[]? - Any errors that occurred during the request.
- rewards LoyaltyReward[]? - The loyalty rewards that satisfy the search criteria.
These are returned in descending order by
updated_at
.
squareup: SearchOrdersCustomerFilter
A filter based on the order customer_id
and any tender customer_id
associated with the order. It does not filter based on the
FulfillmentRecipient customer_id
.
Fields
- customer_ids string[]? - A list of customer IDs to filter by. Max: 10 customer IDs.
squareup: SearchOrdersDateTimeFilter
Filter for Order
objects based on whether their CREATED_AT
,
CLOSED_AT
, or UPDATED_AT
timestamps fall within a specified time range.
You can specify the time range and which timestamp to filter for. You can filter
for only one time range at a time.
For each time range, the start time and end time are inclusive. If the end time is absent, it defaults to the time of the first request for the cursor.
Important: If you use the DateTimeFilter
in a SearchOrders
query,
you must set the sort_field
in OrdersSort
to the same field you filter for. For example, if you set the CLOSED_AT
field
in DateTimeFilter
, you must set the sort_field
in SearchOrdersSort
to
CLOSED_AT
. Otherwise, SearchOrders
throws an error.
Learn more about filtering orders by time range.
Fields
- closed_at TimeRange? - Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
- created_at TimeRange? - Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
- updated_at TimeRange? - Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
squareup: SearchOrdersFilter
Filtering criteria to use for a SearchOrders
request. Multiple filters
are ANDed together.
Fields
- customer_filter SearchOrdersCustomerFilter? - A filter based on the order
customer_id
and any tendercustomer_id
associated with the order. It does not filter based on the FulfillmentRecipientcustomer_id
.
- date_time_filter SearchOrdersDateTimeFilter? - Filter for
Order
objects based on whether theirCREATED_AT
,CLOSED_AT
, orUPDATED_AT
timestamps fall within a specified time range. You can specify the time range and which timestamp to filter for. You can filter for only one time range at a time. For each time range, the start time and end time are inclusive. If the end time is absent, it defaults to the time of the first request for the cursor. Important: If you use theDateTimeFilter
in aSearchOrders
query, you must set thesort_field
in OrdersSort to the same field you filter for. For example, if you set theCLOSED_AT
field inDateTimeFilter
, you must set thesort_field
inSearchOrdersSort
toCLOSED_AT
. Otherwise,SearchOrders
throws an error. Learn more about filtering orders by time range.
- fulfillment_filter SearchOrdersFulfillmentFilter? - Filter based on order fulfillment information.
- source_filter SearchOrdersSourceFilter? - A filter based on order
source
information.
- state_filter SearchOrdersStateFilter? - Filter by the current order
state
.
squareup: SearchOrdersFulfillmentFilter
Filter based on order fulfillment information.
Fields
- fulfillment_states string[]? - A list of fulfillment states to filter for. The list returns orders if any of its fulfillments match any of the fulfillment states listed in this field.
- fulfillment_types string[]? - A list of fulfillment types to filter for. The list returns orders if any of its fulfillments match any of the fulfillment types listed in this field.
squareup: SearchOrdersQuery
Contains query criteria for the search.
Fields
- filter SearchOrdersFilter? - Filtering criteria to use for a
SearchOrders
request. Multiple filters are ANDed together.
- sort SearchOrdersSort? - Sorting criteria for a
SearchOrders
request. Results can only be sorted by a timestamp field.
squareup: SearchOrdersRequest
The request does not have any required fields. When given no query criteria,
SearchOrders
returns all results for all of the seller's locations. When retrieving additional
pages using a cursor
, the query
must be equal to the query
used to retrieve the first page of
results.
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for your original query. For more information, see Pagination.
- 'limit int? - The maximum number of results to be returned in a single page. It is
possible to receive fewer results than the specified limit on a given page.
Default:
500
- location_ids string[]? - The location IDs for the orders to query. All locations must belong to the same merchant. Min: 1 location ID. Max: 10 location IDs.
- query SearchOrdersQuery? - Contains query criteria for the search.
- return_entries boolean? - A Boolean that controls the format of the search results. If
true
,SearchOrders
returns OrderEntry objects. Iffalse
,SearchOrders
returns complete order objects. Default:false
.
squareup: SearchOrdersResponse
Either the order_entries
or orders
field is set, depending on whether
return_entries
is set on the SearchOrdersRequest.
Fields
- cursor string? - The pagination cursor to be used in a subsequent request. If unset, this is the final response. For more information, see Pagination.
- order_entries OrderEntry[]? - A list of OrderEntries that fit the query
conditions. The list is populated only if
return_entries
is set totrue
in the request.
squareup: SearchOrdersSort
Sorting criteria for a SearchOrders
request. Results can only be sorted
by a timestamp field.
Fields
- sort_field string - The field to sort by.
Important: When using a DateTimeFilter,
sort_field
must match the timestamp field that theDateTimeFilter
uses to filter. For example, if you set yoursort_field
toCLOSED_AT
and you use aDateTimeFilter
, yourDateTimeFilter
must filter for orders by theirCLOSED_AT
date. If this field does not match the timestamp field inDateTimeFilter
,SearchOrders
returns an error. Default:CREATED_AT
.
- sort_order string? - The chronological order in which results are returned. Defaults to
DESC
.
squareup: SearchOrdersSourceFilter
A filter based on order source
information.
Fields
squareup: SearchOrdersStateFilter
Filter by the current order state
.
Fields
- states string[] - States to filter for.
squareup: SearchShiftsRequest
A request for a filtered and sorted set of Shift
objects.
Fields
- cursor string? - An opaque cursor for fetching the next page.
- 'limit int? - The number of resources in a page (200 by default).
- query ShiftQuery? - The parameters of a
Shift
search query, which includes filter and sort options.
squareup: SearchShiftsResponse
The response to a request for Shift
objects. The response contains
the requested Shift
objects and might contain a set of Error
objects if
the request resulted in errors.
Fields
- cursor string? - An opaque cursor for fetching the next page.
- errors Error[]? - Any errors that occurred during the request.
- shifts Shift[]? - Shifts.
squareup: SearchSubscriptionsFilter
Represents a set of SearchSubscriptionsQuery filters used to limit the set of Subscriptions returned by SearchSubscriptions.
Fields
- customer_ids string[]? - A filter to select subscriptions based on the customer.
- location_ids string[]? - A filter to select subscriptions based the location.
squareup: SearchSubscriptionsQuery
Represents a query (including filtering criteria) used to search for subscriptions.
Fields
- filter SearchSubscriptionsFilter? - Represents a set of SearchSubscriptionsQuery filters used to limit the set of Subscriptions returned by SearchSubscriptions.
squareup: SearchSubscriptionsRequest
Defines parameters in a SearchSubscriptions endpoint request.
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this to retrieve the next set of results for the original query. For more information, see Pagination.
- 'limit int? - The upper limit on the number of subscriptions to return
in the response.
Default:
200
- query SearchSubscriptionsQuery? - Represents a query (including filtering criteria) used to search for subscriptions.
squareup: SearchSubscriptionsResponse
Defines the fields that are included in the response from the SearchSubscriptions endpoint.
Fields
- cursor string? - When a response is truncated, it includes a cursor that you can use in a subsequent request to fetch the next set of subscriptions. If empty, this is the final response. For more information, see Pagination.
- errors Error[]? - Information about errors encountered during the request.
- subscriptions Subscription[]? - The search result.
squareup: SearchTeamMembersFilter
Represents a filter used in a search for TeamMember
objects. AND
logic is applied
between the individual fields, and OR
logic is applied within list-based fields.
For example, setting this filter value:
filter = (locations_ids = ["A", "B"], status = ACTIVE)
returns only active team members assigned to either location "A" or "B".
Fields
- location_ids string[]? - When present, filters by team members assigned to the specified locations. When empty, includes team members assigned to any location.
- status string? - When present, filters by team members who match the given status. When empty, includes team members of all statuses.
squareup: SearchTeamMembersQuery
Represents the parameters in a search for TeamMember
objects.
Fields
- filter SearchTeamMembersFilter? - Represents a filter used in a search for
TeamMember
objects.AND
logic is applied between the individual fields, andOR
logic is applied within list-based fields. For example, setting this filter value:
returns only active team members assigned to either location "A" or "B".filter = (locations_ids = ["A", "B"], status = ACTIVE)
squareup: SearchTeamMembersRequest
Represents a search request for a filtered list of TeamMember
objects.
Fields
- cursor string? - The opaque cursor for fetching the next page. For more information, see pagination.
- 'limit int? - The maximum number of
TeamMember
objects in a page (100 by default).
- query SearchTeamMembersQuery? - Represents the parameters in a search for
TeamMember
objects.
squareup: SearchTeamMembersResponse
Represents a response from a search request containing a filtered list of TeamMember
objects.
Fields
- cursor string? - The opaque cursor for fetching the next page. For more information, see pagination.
- errors Error[]? - The errors that occurred during the request.
- team_members TeamMember[]? - The filtered list of
TeamMember
objects.
squareup: SearchTerminalCheckoutsRequest
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. See Pagination for more information.
- 'limit int? - Limits the number of results returned for a single request.
- query TerminalCheckoutQuery? -
squareup: SearchTerminalCheckoutsResponse
Fields
- checkouts TerminalCheckout[]? - The requested search result of
TerminalCheckout
objects.
- cursor string? - The pagination cursor to be used in a subsequent request. If empty, this is the final response. See Pagination for more information.
- errors Error[]? - Information about errors encountered during the request.
squareup: SearchTerminalRefundsRequest
Fields
- cursor string? - A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query.
- 'limit int? - Limits the number of results returned for a single request.
- query TerminalRefundQuery? -
squareup: SearchTerminalRefundsResponse
Fields
- cursor string? - The pagination cursor to be used in a subsequent request. If empty, this is the final response. See Pagination for more information.
- errors Error[]? - Information about errors encountered during the request.
- refunds TerminalRefund[]? - The requested search result of
TerminalRefund
objects.
squareup: SegmentFilter
A query filter to search for appointment segments by.
Fields
- service_variation_id string - The ID of the CatalogItemVariation representing the service booked in this segment.
- team_member_id_filter FilterValue? - A filter to select resources based on an exact field value. For any given value, the value can only be in one property. Depending on the field, either all properties can be set or only a subset will be available. Refer to the documentation of the field.
squareup: Shift
A record of the hourly rate, start, and end times for a single work shift for an employee. This might include a record of the start and end times for breaks taken during the shift.
Fields
- breaks Break[]? - A list of all the paid or unpaid breaks that were taken during this shift.
- created_at string? - A read-only timestamp in RFC 3339 format; presented in UTC.
- employee_id string? - The ID of the employee this shift belongs to. DEPRECATED at version 2020-08-26. Use
team_member_id
instead.
- end_at string? - RFC 3339; shifted to the timezone + offset. Precision up to the minute is respected; seconds are truncated.
- id string? - The UUID for this object.
- location_id string? - The ID of the location this shift occurred at. The location should be based on where the employee clocked in.
- start_at string - RFC 3339; shifted to the location timezone + offset. Precision up to the minute is respected; seconds are truncated.
- status string? - Describes the working state of the current
Shift
.
- team_member_id string? - The ID of the team member this shift belongs to. Replaced
employee_id
at version "2020-08-26".
- timezone string? - The read-only convenience value that is calculated from the location based
on the
location_id
. Format: the IANA timezone database identifier for the location timezone.
- updated_at string? - A read-only timestamp in RFC 3339 format; presented in UTC.
- 'version int? - Used for resolving concurrency issues. The request fails if the version provided does not match the server version at the time of the request. If not provided, Square executes a blind write; potentially overwriting data from another write.
- wage ShiftWage? - The hourly wage rate used to compensate an employee for this shift.
squareup: ShiftFilter
Defines a filter used in a search for Shift
records. AND
logic is
used by Square's servers to apply each filter property specified.
Fields
- employee_ids string[]? - Fetch shifts for the specified employees. DEPRECATED at version 2020-08-26. Use
team_member_ids
instead.
- end TimeRange? - Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
- location_ids ShiftfilterLocationidsItemsString[] - Fetch shifts for the specified location.
- 'start TimeRange? - Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
- status string? - Fetch a
Shift
instance byShift.status
.
- team_member_ids ShiftfilterTeammemberidsItemsString[] - Fetch shifts for the specified team members. Replaced
employee_ids
at version "2020-08-26".
- workday ShiftWorkday? - A
Shift
search query filter parameter that sets a range of days that aShift
must start or end in before passing the filter condition.
squareup: ShiftQuery
The parameters of a Shift
search query, which includes filter and sort options.
Fields
- filter ShiftFilter? - Defines a filter used in a search for
Shift
records.AND
logic is used by Square's servers to apply each filter property specified.
- sort ShiftSort? - Sets the sort order of search results.
squareup: ShiftSort
Sets the sort order of search results.
Fields
- 'field string? - The field to sort on.
- 'order string? - The order in which results are returned. Defaults to DESC.
squareup: ShiftWage
The hourly wage rate used to compensate an employee for this shift.
Fields
- hourly_rate Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- title string? - The name of the job performed during this shift. Square labor-reporting UIs might group shifts together by title.
squareup: 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.
Fields
- date_range DateRange? - A range defined by two dates. Used for filtering a query for Connect v2 objects that have date properties.
- default_timezone string? - Location-specific timezones convert workdays to datetime filters. Every location included in the query must have a timezone or this field must be provided as a fallback. Format: the IANA timezone database identifier for the relevant timezone.
- match_shifts_by string? - The strategy on which the dates are applied.
squareup: Site
Represents a Square Online site, which is an online store for a Square seller.
Fields
- created_at string? - The timestamp of when the site was created, in RFC 3339 format.
- domain string? - The domain of the site (without the protocol). For example,
mysite1.square.site
.
- id string? - The Square-assigned ID of the site.
- is_published boolean? - Indicates whether the site is published.
- site_title string? - The title of the site.
- updated_at string? - The timestamp of when the site was last updated, in RFC 3339 format.
squareup: Snippet
Represents the snippet that is added to a Square Online site. The snippet code is injected into the head
element of all pages on the site, except for checkout pages.
Fields
- content string - The snippet code, which can contain valid HTML, JavaScript, or both.
- created_at string? - The timestamp of when the snippet was initially added to the site, in RFC 3339 format.
- id string? - The Square-assigned ID for the snippet.
- site_id string? - The ID of the site that contains the snippet.
- updated_at string? - The timestamp of when the snippet was last updated on the site, in RFC 3339 format.
squareup: SnippetResponse
Fields
- errors Error[]? - Any errors that occurred during the request.
- snippet Snippet? - Represents the snippet that is added to a Square Online site. The snippet code is injected into the
head
element of all pages on the site, except for checkout pages.
squareup: SourceApplication
Provides information about the application used to generate a change.
Fields
- name string? - Read-only display name assigned to the application
(e.g.
"Custom Application"
,"Square POS 4.74 for Android"
).
squareup: StandardUnitDescription
Contains the name and abbreviation for standard measurement unit.
Fields
- abbreviation string? - UI display abbreviation for the measurement unit. For example, 'lb'.
- name string? - UI display name of the measurement unit. For example, 'Pound'.
- unit MeasurementUnit? - Represents a unit of measurement to use with a quantity, such as ounces
or inches. Exactly one of the following fields are required:
custom_unit
,area_unit
,length_unit
,volume_unit
, andweight_unit
.
squareup: StandardUnitDescriptionGroup
Group of standard measurement units.
Fields
- language_code string? - IETF language tag.
- standard_unit_descriptions StandardUnitDescription[]? - List of standard (non-custom) measurement units in this description group.
squareup: SubmitEvidenceRequest
Defines the parameters for a SubmitEvidence
request.
squareup: SubmitEvidenceResponse
Defines the fields in a SubmitEvidence
response.
Fields
- dispute Dispute? - Represents a dispute a cardholder initiated with their bank.
- errors Error[]? - Information about errors encountered during the request.
squareup: Subscription
Represents a customer subscription to a subscription plan.
For an overview of the Subscription
type, see
Subscription object.
Fields
- canceled_date string? - The subscription cancellation date, in YYYY-MM-DD format (for
example, 2013-01-15). On this date, the subscription status changes
to
CANCELED
and the subscription billing stops. If you don't set this field, the subscription plan dictates if and when subscription ends. You cannot update this field, you can only clear it.
- charged_through_date string? - The date up to which the customer is invoiced for the subscription, in YYYY-MM-DD format (for example, 2013-01-15). After the invoice is sent for a given billing period, this date will be the last day of the billing period. For example, suppose for the month of May a customer gets an invoice (or charged the card) on May 1. For the monthly billing scenario, this date is then set to May 31.
- created_at string? - The timestamp when the subscription was created, in RFC 3339 format.
- id string? - The Square-assigned ID of the subscription.
- location_id string? - The ID of the location associated with the subscription.
- plan_id string? - The ID of the associated subscription plan.
- price_override_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- start_date string? - The start date of the subscription, in YYYY-MM-DD format (for example, 2013-01-15).
- status string? - The current status of the subscription.
- tax_percentage string? - The tax amount applied when billing the subscription. The
percentage is expressed in decimal form, using a
'.'
as the decimal separator and without a'%'
sign. For example, a value of7.5
corresponds to 7.5%.
- timezone string? - Timezone that will be used in date calculations for the subscription.
Defaults to the timezone of the location based on
location_id
. Format: the IANA Timezone Database identifier for the location timezone (for example,America/Los_Angeles
).
- 'version int? - The version of the object. When updating an object, the version supplied must match the version in the database, otherwise the write will be rejected as conflicting.
squareup: SubscriptionEvent
Describes changes to subscription and billing states.
Fields
- effective_date string - The date, in YYYY-MM-DD format (for example, 2013-01-15), when the subscription event went into effect.
- id string - The ID of the subscription event.
- info Info? -
- plan_id string - The ID of the subscription plan associated with the subscription.
- subscription_event_type string - Type of the subscription event.
squareup: SubscriptionEventInfo
Provides information about the subscription event.
Fields
- code InfoCode? -
- detail string? - A human-readable explanation for the event.
squareup: SubscriptionPhase
Describes a phase in a subscription plan. For more information, see Set Up and Manage a Subscription Plan.
Fields
- cadence string - The billing cadence of the phase. For example, weekly or monthly. This field cannot be changed after a
SubscriptionPhase
is created.
- ordinal int? - The position this phase appears in the sequence of phases defined for the plan, indexed from 0. This field cannot be changed after a
SubscriptionPhase
is created.
- periods int? - The number of
cadence
s the phase lasts. If not set, the phase never ends. Only the last phase can be indefinite. This field cannot be changed after aSubscriptionPhase
is created.
- recurring_price_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- uid string? - The Square-assigned ID of the subscription phase. This field cannot be changed after a
SubscriptionPhase
is created.
squareup: TaxIds
The tax IDs that a Location is operating under.
Fields
- eu_vat string? - The EU VAT number for this location. For example, "IE3426675K". If the EU VAT number is present, it is well-formed and has been validated with VIES, the VAT Information Exchange System.
- fr_naf string? - The French government uses the NAF (Nomenclature des Activités Françaises) to display and track economic statistical data. This is also called the APE (Activite Principale de l’Entreprise) code. For example, 6910Z.
- fr_siret string? - The SIRET (Système d'Identification du Répertoire des Entreprises et de leurs Etablissements) number is a 14 digits code issued by the French INSEE. For example, "39922799000021".
squareup: TeamMember
A record representing an individual team member for a business.
Fields
- assigned_locations TeamMemberAssignedLocations? - An object that represents a team member's assignment to locations.
- created_at string? - The timestamp, in RFC 3339 format, describing when the team member was created. For example, "2018-10-04T04:00:00-07:00" or "2019-02-05T12:00:00Z".
- email_address string? - The email address associated with the team member.
- family_name string? - The family name (that is, the last name) associated with the team member.
- given_name string? - The given name (that is, the first name) associated with the team member.
- id string? - The unique ID for the team member.
- is_owner boolean? - Whether the team member is the owner of the Square account.
- phone_number string? - The team member's phone number, in E.164 format. For example:
- reference_id string? - A second ID used to associate the team member with an entity in another system.
- status string? - Describes the status of the team member.
- updated_at string? - The timestamp, in RFC 3339 format, describing when the team member was last updated. For example, "2018-10-04T04:00:00-07:00" or "2019-02-05T12:00:00Z".
squareup: TeamMemberAssignedLocations
An object that represents a team member's assignment to locations.
Fields
- assignment_type string? - The current assignment type of the team member.
- location_ids string[]? - The locations that the team member is assigned to.
squareup: TeamMemberBookingProfile
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.
Fields
- description string? - The description of the team member.
- display_name string? - The display name of the team member.
- is_bookable boolean? - Indicates whether the team member can be booked through the Bookings API or the seller's online booking channel or site (
true) or not (
false). MISSING[
]
- profile_image_url string? - The URL of the team member's image for the bookings profile.
- team_member_id string? - The ID of the TeamMember object for the team member associated with the booking profile.
squareup: TeamMemberWage
The hourly wage rate that a team member earns on a Shift
for doing the job
specified by the title
property of this object.
Fields
- hourly_rate Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- id string? - The UUID for this object.
- team_member_id string? - The
TeamMember
that this wage is assigned to.
- title string? - The job title that this wage relates to.
squareup: Tender
Represents a tender (i.e., a method of payment) used in a Square transaction.
Fields
- additional_recipients AdditionalRecipient[]? - Additional recipients (other than the merchant) receiving a portion of this tender. For example, fees assessed on the purchase by a third party integration.
- amount_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- card_details TenderCardDetails? - Represents additional details of a tender with
type
CARD
orSQUARE_GIFT_CARD
- cash_details TenderCashDetails? - Represents the details of a tender with
type
CASH
.
- created_at string? - The timestamp for when the tender was created, in RFC 3339 format.
- customer_id string? - If the tender is associated with a customer or represents a customer's card on file, this is the ID of the associated customer.
- id string? - The tender's unique ID.
- location_id string? - The ID of the transaction's associated location.
- note string? - An optional note associated with the tender at the time of payment.
- processing_fee_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- tip_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- transaction_id string? - The ID of the tender's associated transaction.
- 'type string - The type of tender, such as
CARD
orCASH
.
squareup: TenderCardDetails
Represents additional details of a tender with type
CARD
or SQUARE_GIFT_CARD
Fields
- card Card? - Represents the payment details of a card to be used for payments. These details are determined by the payment token generated by Web Payments SDK.
- entry_method string? - The method used to enter the card's details for the transaction.
- status string? - The credit card payment's current state (such as
AUTHORIZED
orCAPTURED
). See TenderCardDetailsStatus for possible values.
squareup: TenderCashDetails
Represents the details of a tender with type
CASH
.
Fields
- buyer_tendered_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- change_back_money Money? - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
squareup: TerminalCheckout
Fields
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- app_id string? - The ID of the application that created the checkout.
- cancel_reason string? - Present if the status is
CANCELED
.
- created_at string? - The time when the
TerminalCheckout
was created, as an RFC 3339 timestamp.
- deadline_duration string? - An RFC 3339 duration, after which the checkout is automatically canceled.
A
TerminalCheckout
that isPENDING
is automaticallyCANCELED
and has a cancellation reason ofTIMED_OUT
. Default: 5 minutes from creation Maximum: 5 minutes
- device_options DeviceCheckoutOptions -
- id string? - A unique ID for this
TerminalCheckout
.
- location_id string? - The location of the device where the
TerminalCheckout
was directed.
- note string? - An optional note to associate with the checkout, as well as with any payments used to complete the checkout.
- payment_ids string[]? - A list of IDs for payments created by this
TerminalCheckout
.
- payment_type string? - The type of payment the terminal should attempt to capture from. Defaults to
CARD_PRESENT
.
- reference_id string? - An optional user-defined reference ID that can be used to associate
this
TerminalCheckout
to another entity in an external system. For example, an order ID generated by a third-party shopping cart. The ID is also associated with any payments used to complete the checkout.
- status string? - The status of the
TerminalCheckout
. Options:PENDING
,IN_PROGRESS
,CANCEL_REQUESTED
,CANCELED
,COMPLETED
- updated_at string? - The time when the
TerminalCheckout
was last updated, as an RFC 3339 timestamp.
squareup: TerminalCheckoutQuery
Fields
- filter TerminalCheckoutQueryFilter? -
- sort TerminalCheckoutQuerySort? -
squareup: TerminalCheckoutQueryFilter
Fields
- created_at TimeRange? - Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
- device_id string? - The
TerminalCheckout
objects associated with a specific device. If no device is specified, then allTerminalCheckout
objects for the merchant are displayed.
- status string? - Filtered results with the desired status of the
TerminalCheckout
. Options: PENDING, IN_PROGRESS, CANCELED, COMPLETED
squareup: TerminalCheckoutQuerySort
Fields
- sort_order string? - The order in which results are listed.
ASC
- Oldest to newest.DESC
- Newest to oldest (default).
squareup: TerminalRefund
Fields
- amount_money Money - Represents an amount of money.
Money
fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
- app_id string? - The ID of the application that created the refund.
- cancel_reason string? - Present if the status is
CANCELED
.
- created_at string? - The time when the
TerminalRefund
was created, as an RFC 3339 timestamp.
- deadline_duration string? - The RFC 3339 duration, after which the refund is automatically canceled.
A
TerminalRefund
that isPENDING
is automaticallyCANCELED
and has a cancellation reason ofTIMED_OUT
. Default: 5 minutes from creation. Maximum: 5 minutes
- device_id string? - The unique ID of the device intended for this
TerminalRefund
. The Id can be retrieved from /v2/devices api.
- id string? - A unique ID for this
TerminalRefund
.
- location_id string? - The location of the device where the
TerminalRefund
was directed.
- order_id string? - The reference to the Square order ID for the payment identified by the
payment_id
.
- payment_id string - The unique ID of the payment being refunded.
- reason string? - A description of the reason for the refund. Note: maximum 192 characters
- refund_id string? - The reference to the payment refund created by completing this
TerminalRefund
.
- status string? - The status of the
TerminalRefund
. Options:PENDING
,IN_PROGRESS
,CANCELED
, orCOMPLETED
.
- updated_at string? - The time when the
TerminalRefund
was last updated, as an RFC 3339 timestamp.
squareup: TerminalRefundQuery
Fields
- filter TerminalRefundQueryFilter? -
- sort TerminalRefundQuerySort? -
squareup: TerminalRefundQueryFilter
Fields
- created_at TimeRange? - Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
- device_id string? -
TerminalRefund
objects associated with a specific device. If no device is specified, then allTerminalRefund
objects for the signed-in account are displayed.
- status string? - Filtered results with the desired status of the
TerminalRefund
. Options:PENDING
,IN_PROGRESS
,CANCEL_REQUESTED
,CANCELED
, orCOMPLETED
.
squareup: TerminalRefundQuerySort
Fields
- sort_order string? - The order in which results are listed.
ASC
- Oldest to newest.DESC
- Newest to oldest (default).
squareup: TimeRange
Represents a generic time range. The start and end values are represented in RFC 3339 format. Time ranges are customized to be inclusive or exclusive based on the needs of a particular endpoint. Refer to the relevant endpoint-specific documentation to determine how time ranges are handled.
Fields
- end_at string? - A datetime value in RFC 3339 format indicating when the time range ends.
- start_at string? - A datetime value in RFC 3339 format indicating when the time range starts.
squareup: TipSettings
Fields
- allow_tipping boolean? - Indicates whether tipping is enabled for this checkout. Defaults to false.
- custom_tip_field boolean? - Indicates whether custom tip amounts are allowed during the checkout flow. Defaults to false.
- separate_tip_screen boolean? - Indicates whether tip options should be presented on the screen before presenting the signature screen during card payment. Defaults to false.
- smart_tipping boolean? - Enables the "Smart Tip Amounts" behavior.
Exact tipping options depend on the region in which the Square seller is active.
For payments under 10.00, in the Australia, Canada, Ireland, United Kingdom, and United States, tipping options are presented as no tip, .50, 1.00 or 2.00.
For payment amounts of 10.00 or greater, tipping options are presented as the following percentages: 0%, 5%, 10%, 15%.
If set to true, the
tip_percentages
settings is ignored. Defaults to false. To learn more about smart tipping, see Accept Tips with the Square App.
- tip_percentages int[]? - A list of tip percentages that should be presented during the checkout flow, specified as up to 3 non-negative integers from 0 to 100 (inclusive). Defaults to 15, 20, and 25.
squareup: Transaction
Represents a transaction processed with Square, either with the Connect API or with Square Point of Sale.
The tenders
field of this object lists all methods of payment used to pay in
the transaction.
Fields
- client_id string? - If the transaction was created in the Square Point of Sale app, this value
is the ID generated for the transaction by Square Point of Sale.
This ID has no relationship to the transaction's canonical
id
, which is generated by Square's backend servers. This value is generated for bookkeeping purposes, in case the transaction cannot immediately be completed (for example, if the transaction is processed in offline mode). It is not currently possible with the Connect API to perform a transaction lookup by this value.
- created_at string? - The timestamp for when the transaction was created, in RFC 3339 format.
- id string? - The transaction's unique ID, issued by Square payments servers.
- location_id string? - The ID of the transaction's associated location.
- order_id string? - The order_id is an identifier for the order associated with this transaction, if any.
- product string? - The Square product that processed the transaction.
- refunds Refund[]? - Refunds that have been applied to any tender in the transaction.
- shipping_address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- tenders Tender[]? - The tenders used to pay in the transaction.
squareup: UnlinkCustomerFromGiftCardRequest
A request to unlink a customer to a gift card
Fields
- customer_id string -
squareup: UnlinkCustomerFromGiftCardResponse
A response that contains one GiftCard
that was unlinked. The response might contain a set of Error
objects if the request resulted in errors.
Fields
- errors Error[]? - Any errors that occurred during the request.
- gift_card GiftCard? - Represents a Square gift card.
squareup: UpdateBookingRequest
Fields
- booking 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.
- idempotency_key string? - A unique key to make this request an idempotent operation.
squareup: UpdateBookingResponse
Fields
- booking 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.
- errors Error[]? - Any errors that occurred during the request.
squareup: UpdateBreakTypeRequest
A request to update a BreakType
.
Fields
- break_type BreakType - A defined break template that sets an expectation for possible
Break
instances on aShift
.
squareup: UpdateBreakTypeResponse
A response to a request to update a BreakType
. The response contains
the requested BreakType
objects and might contain a set of Error
objects if
the request resulted in errors.
Fields
- break_type BreakType? - A defined break template that sets an expectation for possible
Break
instances on aShift
.
- errors Error[]? - Any errors that occurred during the request.
squareup: UpdateCustomerGroupRequest
Defines the body parameters that can be included in a request to the UpdateCustomerGroup endpoint.
Fields
- group CustomerGroup - Represents a group of customer profiles. Customer groups can be created, be modified, and have their membership defined using the Customers API or within the Customer Directory in the Square Seller Dashboard or Point of Sale.
squareup: UpdateCustomerGroupResponse
Defines the fields that are included in the response body of a request to the UpdateCustomerGroup endpoint.
Either errors
or group
is present in a given response (never both).
Fields
- errors Error[]? - Any errors that occurred during the request.
- group CustomerGroup? - Represents a group of customer profiles. Customer groups can be created, be modified, and have their membership defined using the Customers API or within the Customer Directory in the Square Seller Dashboard or Point of Sale.
squareup: UpdateCustomerRequest
Defines the body parameters that can be included in a request to the
UpdateCustomer
endpoint.
Fields
- address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- birthday string? - The birthday associated with the customer profile, in RFC 3339 format. The year is optional. The timezone and time are not allowed.
For example,
0000-09-21T00:00:00-00:00
represents a birthday on September 21 and1998-09-21T00:00:00-00:00
represents a birthday on September 21, 1998. You can also specify this value inYYYY-MM-DD
format.
- company_name string? - A business name associated with the customer profile.
- email_address string? - The email address associated with the customer profile.
- family_name string? - The family name (that is, the last name) associated with the customer profile.
- given_name string? - The given name (that is, the first name) associated with the customer profile.
- nickname string? - A nickname for the customer profile.
- note string? - A custom note associated with the customer profile.
- phone_number string? - The 11-digit phone number associated with the customer profile.
- reference_id string? - An optional second ID used to associate the customer profile with an entity in another system.
- 'version int? - The current version of the customer profile. As a best practice, you should include this field to enable optimistic concurrency control. For more information, see Update a customer profile.
squareup: UpdateCustomerResponse
Defines the fields that are included in the response body of
a request to the UpdateCustomer
endpoint.
Either errors
or customer
is present in a given response (never both).
Fields
- customer Customer? - Represents a Square customer profile in the Customer Directory of a Square seller.
- errors Error[]? - Any errors that occurred during the request.
squareup: UpdateInvoiceRequest
Describes a UpdateInvoice
request.
Fields
- fields_to_clear string[]? - The list of fields to clear. For examples, see Update an invoice.
- idempotency_key string? - A unique string that identifies the
UpdateInvoice
request. If you do not provideidempotency_key
(or provide an empty string as the value), the endpoint treats each request as independent. For more information, see Idempotency.
- invoice Invoice - Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see Manage Invoices Using the Invoices API.
squareup: UpdateInvoiceResponse
Describes a UpdateInvoice
response.
Fields
- errors Error[]? - Information about errors encountered during the request.
- invoice Invoice? - Stores information about an invoice. You use the Invoices API to create and manage invoices. For more information, see Manage Invoices Using the Invoices API.
squareup: UpdateItemModifierListsRequest
Fields
- item_ids string[] - The IDs of the catalog items associated with the CatalogModifierList objects being updated.
- modifier_lists_to_disable string[]? - The IDs of the CatalogModifierList objects to disable for the CatalogItem.
- modifier_lists_to_enable string[]? - The IDs of the CatalogModifierList objects to enable for the CatalogItem.
squareup: UpdateItemModifierListsResponse
Fields
- errors Error[]? - Any errors that occurred during the request.
squareup: UpdateItemTaxesRequest
Fields
- item_ids string[] - IDs for the CatalogItems associated with the CatalogTax objects being updated.
- taxes_to_disable string[]? - IDs of the CatalogTax objects to disable.
- taxes_to_enable string[]? - IDs of the CatalogTax objects to enable.
squareup: UpdateItemTaxesResponse
Fields
- errors Error[]? - Any errors that occurred during the request.
squareup: UpdateLocationRequest
Request object for the UpdateLocation endpoint.
Fields
- location Location? -
squareup: UpdateLocationResponse
Response object returned by the UpdateLocation endpoint.
Fields
- errors Error[]? - Information on errors encountered during the request.
- location Location? -
squareup: UpdateOrderRequest
Defines the fields that are included in requests to the UpdateOrder endpoint.
Fields
- fields_to_clear string[]? - The dot notation paths
fields to clear. For example,
line_items[uid].note
. For more information, see Deleting fields.
- idempotency_key string? - A value you specify that uniquely identifies this update request. If you are unsure whether a particular update was applied to an order successfully, you can reattempt it with the same idempotency key without worrying about creating duplicate updates to the order. The latest order version is returned. For more information, see Idempotency.
- 'order Order? - Contains all information related to a single order to process with Square,
including line items that specify the products to purchase.
Order
objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.
squareup: UpdateOrderResponse
Defines the fields that are included in the response body of a request to the UpdateOrder endpoint.
Fields
- errors Error[]? - Any errors that occurred during the request.
- 'order Order? - Contains all information related to a single order to process with Square,
including line items that specify the products to purchase.
Order
objects also include information about any associated tenders, refunds, and returns. All Connect V2 Transactions have all been converted to Orders including all associated itemization data.
squareup: UpdatePaymentRequest
Describes a request to update a payment using UpdatePayment.
Fields
- idempotency_key string - A unique string that identifies this
UpdatePayment
request. Keys can be any valid string but must be unique for everyUpdatePayment
request. The maximum is 45 characters. For more information, see Idempotency.
- payment Payment? - Represents a payment processed by the Square API.
squareup: UpdatePaymentResponse
Defines the response returned by UpdatePayment.
Fields
- errors Error[]? - Any errors that occurred during the request.
- payment Payment? - Represents a payment processed by the Square API.
squareup: UpdateShiftRequest
A request to update a Shift
object.
Fields
- shift Shift - A record of the hourly rate, start, and end times for a single work shift for an employee. This might include a record of the start and end times for breaks taken during the shift.
squareup: UpdateShiftResponse
The response to a request to update a Shift
. The response contains
the updated Shift
object and might contain a set of Error
objects if
the request resulted in errors.
Fields
- errors Error[]? - Any errors that occurred during the request.
- shift Shift? - A record of the hourly rate, start, and end times for a single work shift for an employee. This might include a record of the start and end times for breaks taken during the shift.
squareup: UpdateSubscriptionRequest
Defines parameters in a UpdateSubscription endpoint request.
Fields
- subscription Subscription? - Represents a customer subscription to a subscription plan.
For an overview of the
Subscription
type, see Subscription object.
squareup: UpdateSubscriptionResponse
Defines the fields that are included in the response from the UpdateSubscription endpoint.
Fields
- errors Error[]? - Information about errors encountered during the request.
- subscription Subscription? - Represents a customer subscription to a subscription plan.
For an overview of the
Subscription
type, see Subscription object.
squareup: UpdateTeamMemberRequest
Represents an update request for a TeamMember
object.
Fields
- team_member TeamMember? - A record representing an individual team member for a business.
squareup: UpdateTeamMemberResponse
Represents a response from an update request containing the updated TeamMember
object or error messages.
Fields
- errors Error[]? - The errors that occurred during the request.
- team_member TeamMember? - A record representing an individual team member for a business.
squareup: UpdateWageSettingRequest
Represents an update request for the WageSetting
object describing a TeamMember
.
Fields
- wage_setting WageSetting - An object representing a team member's wage information.
squareup: UpdateWageSettingResponse
Represents a response from an update request containing the updated WageSetting
object
or error messages.
Fields
- errors Error[]? - The errors that occurred during the request.
- wage_setting WageSetting? - An object representing a team member's wage information.
squareup: UpdateWorkweekConfigRequest
A request to update a WorkweekConfig
object.
Fields
- workweek_config WorkweekConfig - Sets the day of the week and hour of the day that a business starts a workweek. This is used to calculate overtime pay.
squareup: UpdateWorkweekConfigResponse
The response to a request to update a WorkweekConfig
object. The response contains
the updated WorkweekConfig
object and might contain a set of Error
objects if
the request resulted in errors.
Fields
- errors Error[]? - Any errors that occurred during the request.
- workweek_config WorkweekConfig? - Sets the day of the week and hour of the day that a business starts a workweek. This is used to calculate overtime pay.
squareup: UpsertCatalogObjectRequest
Fields
- idempotency_key string - A value you specify that uniquely identifies this request among all your requests. A common way to create a valid idempotency key is to use a Universally unique identifier (UUID). If you're unsure whether a particular request was successful, you can reattempt it with the same idempotency key without worrying about creating duplicate objects. See Idempotency for more information.
- 'object CatalogObject - The wrapper object for the Catalog entries of a given object type.
The type of a particular
CatalogObject
is determined by the value of thetype
attribute and only the corresponding data attribute can be set on theCatalogObject
instance. For example, the following list shows some instances ofCatalogObject
of a giventype
and their corresponding data attribute that can be set:- For a
CatalogObject
of theITEM
type, set theitem_data
attribute to yield theCatalogItem
object. - For a
CatalogObject
of theITEM_VARIATION
type, set theitem_variation_data
attribute to yield theCatalogItemVariation
object. - For a
CatalogObject
of theMODIFIER
type, set themodifier_data
attribute to yield theCatalogModifier
object. - For a
CatalogObject
of theMODIFIER_LIST
type, set themodifier_list_data
attribute to yield theCatalogModifierList
object. - For a
CatalogObject
of theCATEGORY
type, set thecategory_data
attribute to yield theCatalogCategory
object. - For a
CatalogObject
of theDISCOUNT
type, set thediscount_data
attribute to yield theCatalogDiscount
object. - For a
CatalogObject
of theTAX
type, set thetax_data
attribute to yield theCatalogTax
object. - For a
CatalogObject
of theIMAGE
type, set theimage_data
attribute to yield theCatalogImageData
object. - For a
CatalogObject
of theQUICK_AMOUNTS_SETTINGS
type, set thequick_amounts_settings_data
attribute to yield theCatalogQuickAmountsSettings
object. - For a
CatalogObject
of thePRICING_RULE
type, set thepricing_rule_data
attribute to yield theCatalogPricingRule
object. - For a
CatalogObject
of theTIME_PERIOD
type, set thetime_period_data
attribute to yield theCatalogTimePeriod
object. - For a
CatalogObject
of thePRODUCT_SET
type, set theproduct_set_data
attribute to yield theCatalogProductSet
object. - For a
CatalogObject
of theSUBSCRIPTION_PLAN
type, set thesubscription_plan_data
attribute to yield theCatalogSubscriptionPlan
object.
- For a
squareup: UpsertCatalogObjectResponse
Fields
- catalog_object CatalogObject? - The wrapper object for the Catalog entries of a given object type.
The type of a particular
CatalogObject
is determined by the value of thetype
attribute and only the corresponding data attribute can be set on theCatalogObject
instance. For example, the following list shows some instances ofCatalogObject
of a giventype
and their corresponding data attribute that can be set:- For a
CatalogObject
of theITEM
type, set theitem_data
attribute to yield theCatalogItem
object. - For a
CatalogObject
of theITEM_VARIATION
type, set theitem_variation_data
attribute to yield theCatalogItemVariation
object. - For a
CatalogObject
of theMODIFIER
type, set themodifier_data
attribute to yield theCatalogModifier
object. - For a
CatalogObject
of theMODIFIER_LIST
type, set themodifier_list_data
attribute to yield theCatalogModifierList
object. - For a
CatalogObject
of theCATEGORY
type, set thecategory_data
attribute to yield theCatalogCategory
object. - For a
CatalogObject
of theDISCOUNT
type, set thediscount_data
attribute to yield theCatalogDiscount
object. - For a
CatalogObject
of theTAX
type, set thetax_data
attribute to yield theCatalogTax
object. - For a
CatalogObject
of theIMAGE
type, set theimage_data
attribute to yield theCatalogImageData
object. - For a
CatalogObject
of theQUICK_AMOUNTS_SETTINGS
type, set thequick_amounts_settings_data
attribute to yield theCatalogQuickAmountsSettings
object. - For a
CatalogObject
of thePRICING_RULE
type, set thepricing_rule_data
attribute to yield theCatalogPricingRule
object. - For a
CatalogObject
of theTIME_PERIOD
type, set thetime_period_data
attribute to yield theCatalogTimePeriod
object. - For a
CatalogObject
of thePRODUCT_SET
type, set theproduct_set_data
attribute to yield theCatalogProductSet
object. - For a
CatalogObject
of theSUBSCRIPTION_PLAN
type, set thesubscription_plan_data
attribute to yield theCatalogSubscriptionPlan
object.
- For a
- errors Error[]? - Any errors that occurred during the request.
- id_mappings CatalogIdMapping[]? - The mapping between client and server IDs for this upsert.
squareup: UpsertSnippetRequest
Represents an UpsertSnippet
request.
Fields
- snippet Snippet - Represents the snippet that is added to a Square Online site. The snippet code is injected into the
head
element of all pages on the site, except for checkout pages.
squareup: UpsertSnippetResponse
Represents an UpsertSnippet
response. The response can include either snippet
or errors
.
Fields
- errors Error[]? - Any errors that occurred during the request.
- snippet Snippet? - Represents the snippet that is added to a Square Online site. The snippet code is injected into the
head
element of all pages on the site, except for checkout pages.
squareup: V1CreateEmployeeRoleRequest
Fields
- employee_role V1EmployeeRole? - V1EmployeeRole
squareup: V1CreateRefundRequest
V1CreateRefundRequest
Fields
- payment_id string - The ID of the payment to refund. If you are creating a
PARTIAL
refund for a split tender payment, instead provide the id of the particular tender you want to refund.
- reason string - The reason for the refund.
- refunded_money V1Money? -
- request_idempotence_key string? - An optional key to ensure idempotence if you issue the same PARTIAL refund request more than once.
- 'type string - The type of refund (FULL or PARTIAL).
squareup: V1Employee
Represents one of a business's employees.
Fields
- authorized_location_ids string[]? - The IDs of the locations the employee is allowed to clock in at.
- created_at string? - The time when the employee entity was created, in ISO 8601 format.
- email string? - The employee's email address.
- external_id string? - An ID the merchant can set to associate the employee with an entity in another system.
- first_name string - The employee's first name.
- id string? - The employee's unique ID.
- last_name string - The employee's last name.
- role_ids string[]? - The ids of the employee's associated roles. Currently, you can specify only one or zero roles per employee.
- status string? - Whether the employee is ACTIVE or INACTIVE. Inactive employees cannot sign in to Square Register.Merchants update this field from the Square Dashboard.
- updated_at string? - The time when the employee entity was most recently updated, in ISO 8601 format.
squareup: V1EmployeeRole
V1EmployeeRole
Fields
- created_at string? - The time when the employee entity was created, in ISO 8601 format. Is set by Square when the Role is created.
- id string? - The role's unique ID, Can only be set by Square.
- is_owner boolean? - If true, employees with this role have all permissions, regardless of the values indicated in permissions.
- name string - The role's merchant-defined name.
- permissions string[] - The role's permissions.
- updated_at string? - The time when the employee entity was most recently updated, in ISO 8601 format. Is set by Square when the Role updated.
squareup: V1ListEmployeeRolesRequest
Fields
- batch_token string? - A pagination cursor to retrieve the next set of results for your original query to the endpoint.
- 'limit int? - The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.
- 'order string? - The order in which employees are listed in the response, based on their created_at field.Default value: ASC
squareup: V1ListEmployeeRolesResponse
Fields
- items V1EmployeeRole[]? -
squareup: V1ListEmployeesRequest
Fields
- batch_token string? - A pagination cursor to retrieve the next set of results for your original query to the endpoint.
- begin_created_at string? - If filtering results by their created_at field, the beginning of the requested reporting period, in ISO 8601 format.
- begin_updated_at string? - If filtering results by their updated_at field, the beginning of the requested reporting period, in ISO 8601 format
- end_created_at string? - If filtering results by their created_at field, the end of the requested reporting period, in ISO 8601 format.
- end_updated_at string? - If filtering results by there updated_at field, the end of the requested reporting period, in ISO 8601 format.
- external_id string? - If provided, the endpoint returns only employee entities with the specified external_id.
- 'limit int? - The maximum integer number of employee entities to return in a single response. Default 100, maximum 200.
- 'order string? - The order in which employees are listed in the response, based on their created_at field. Default value: ASC
- status string? - If provided, the endpoint returns only employee entities with the specified status (ACTIVE or INACTIVE).
squareup: V1ListEmployeesResponse
Fields
- items V1Employee[]? -
squareup: V1ListOrdersRequest
Fields
- batch_token string? - A pagination cursor to retrieve the next set of results for your original query to the endpoint.
- 'limit int? - The maximum number of payments to return in a single response. This value cannot exceed 200.
- 'order string? - The order in which payments are listed in the response.
squareup: V1ListOrdersResponse
Fields
- items V1Order[]? -
squareup: V1ListPaymentsRequest
Fields
- batch_token string? - A pagination cursor to retrieve the next set of results for your original query to the endpoint.
- begin_time string? - The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year.
- end_time string? - The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time.
- include_partial boolean? - Indicates whether or not to include partial payments in the response. Partial payments will have the tenders collected so far, but the itemizations will be empty until the payment is completed.
- 'limit int? - The maximum number of payments to return in a single response. This value cannot exceed 200.
- 'order string? - The order in which payments are listed in the response.
squareup: V1ListPaymentsResponse
Fields
- items V1Payment[]? -
squareup: V1ListRefundsRequest
Fields
- batch_token string? - A pagination cursor to retrieve the next set of results for your original query to the endpoint.
- begin_time string? - The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year.
- end_time string? - The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time.
- 'limit int? - The approximate number of refunds to return in a single response. Default: 100. Max: 200. Response may contain more results than the prescribed limit when refunds are made simultaneously to multiple tenders in a payment or when refunds are generated in an exchange to account for the value of returned goods.
- 'order string? - The order in which payments are listed in the response.
squareup: V1ListRefundsResponse
Fields
- items V1Refund[]? -
squareup: V1ListSettlementsRequest
Fields
- batch_token string? - A pagination cursor to retrieve the next set of results for your original query to the endpoint.
- begin_time string? - The beginning of the requested reporting period, in ISO 8601 format. If this value is before January 1, 2013 (2013-01-01T00:00:00Z), this endpoint returns an error. Default value: The current time minus one year.
- end_time string? - The end of the requested reporting period, in ISO 8601 format. If this value is more than one year greater than begin_time, this endpoint returns an error. Default value: The current time.
- 'limit int? - The maximum number of settlements to return in a single response. This value cannot exceed 200.
- 'order string? - The order in which settlements are listed in the response.
- status string? - Provide this parameter to retrieve only settlements with a particular status (SENT or FAILED).
squareup: V1ListSettlementsResponse
Fields
- items V1Settlement[]? -
squareup: V1Money
Fields
- amount int? - Amount in the lowest denominated value of this Currency. E.g. in USD these are cents, in JPY they are Yen (which do not have a 'cent' concept).
- currency_code string? -
squareup: V1Order
V1Order
Fields
- btc_price_satoshi decimal? - For Bitcoin transactions, the price of the buyer's order in satoshi (100 million satoshi equals 1 BTC).
- btc_receive_address string? - For Bitcoin transactions, the address that the buyer sent Bitcoin to.
- buyer_email string? - The email address of the order's buyer.
- buyer_note string? - A note provided by the buyer when the order was created, if any.
- canceled_note string? - A note provided by the merchant when the order's state was set to CANCELED, if any.
- completed_note string? - A note provided by the merchant when the order's state was set to COMPLETED, if any
- created_at string? - The time when the order was created, in ISO 8601 format.
- errors Error[]? - Any errors that occurred during the request.
- expires_at string? - The time when the order expires if no action is taken, in ISO 8601 format.
- id string? - The order's unique identifier.
- order_history V1OrderHistoryEntry[]? - The history of actions associated with the order.
- payment_id string? - The unique identifier of the payment associated with the order.
- promo_code string? - The promo code provided by the buyer, if any.
- recipient_name string? - The name of the order's buyer.
- recipient_phone_number string? - The phone number to use for the order's delivery.
- refunded_note string? - A note provided by the merchant when the order's state was set to REFUNDED, if any.
- shipping_address Address? - Represents a postal address in a country. The address format is based
on an open-source library from Google. For more information,
see AddressValidationMetadata.
This format has dedicated fields for four address components: postal code,
locality (city), administrative district (state, prefecture, or province), and
sublocality (town or village). These components have dedicated fields in the
Address
object because software sometimes behaves differently based on them. For example, sales tax software may charge different amounts of sales tax based on the postal code, and some software is only available in certain states due to compliance reasons. For the remaining address components, theAddress
type provides theaddress_line_1
andaddress_line_2
fields for free-form data entry. These fields are free-form because the remaining address components have too many variations around the world and typical software does not parse these components. These fields enable users to enter anything they want. Note that, in the current implementation, all otherAddress
type fields are blank. These includeaddress_line_3
,sublocality_2
,sublocality_3
,administrative_district_level_2
,administrative_district_level_3
,first_name
,last_name
, andorganization
. When it comes to localization, the seller's language preferences (see Language preferences) are ignored for addresses. Even though Square products (such as Square Point of Sale and the Seller Dashboard) mostly use a seller's language preference in communication, when it comes to addresses, they will use English for a US address, Japanese for an address in Japan, and so on.
- state string? - Whether the tax is an ADDITIVE tax or an INCLUSIVE tax.
- subtotal_money V1Money? -
- tender V1Tender? - A tender represents a discrete monetary exchange. Square represents this
exchange as a money object with a specific currency and amount, where the
amount is given in the smallest denomination of the given currency.
Square POS can accept more than one form of tender for a single payment (such
as by splitting a bill between a credit card and a gift card). The
tender
field of the Payment object lists all forms of tender used for the payment. Split tender payments behave slightly differently from single tender payments: The receipt_url for a split tender corresponds only to the first tender listed in the tender field. To get the receipt URLs for the remaining tenders, use the receipt_url fields of the corresponding Tender objects. A note on gift cards*: when a customer purchases a Square gift card from a merchant, the merchant receives the full amount of the gift card in the associated payment. When that gift card is used as a tender, the balance of the gift card is reduced and the merchant receives no funds. ATender
object with a type ofSQUARE_GIFT_CARD
indicates a gift card was used for some or all of the associated payment.
- total_discount_money V1Money? -
- total_price_money V1Money? -
- total_shipping_money V1Money? -
- total_tax_money V1Money? -
- updated_at string? - The time when the order was last modified, in ISO 8601 format.
squareup: V1OrderHistoryEntry
V1OrderHistoryEntry
Fields
- action string? - The type of action performed on the order.
- created_at string? - The time when the action was performed, in ISO 8601 format.
squareup: V1Payment
A payment represents a paid transaction between a Square merchant and a customer. Payment details are usually available from Connect API endpoints within a few minutes after the transaction completes.
Each Payment object includes several fields that end in _money
. These fields
describe the various amounts of money that contribute to the payment total:
-
Monetary values are positive if they represent an
increase in the amount of money the merchant receives (e.g.,
tax_money
,tip_money
). -
Monetary values are negative if they represent an
decrease in the amount of money the merchant receives (e.g.,
discount_money
,refunded_money
).
Fields
- additive_tax V1PaymentTax[]? - All of the additive taxes associated with the payment.
- additive_tax_money V1Money? -
- created_at string? - The time when the payment was created, in ISO 8601 format. Reflects the time of the first payment if the object represents an incomplete partial payment, and the time of the last or complete payment otherwise.
- creator_id string? - The unique identifier of the Square account that took the payment.
- device Device? -
- discount_money V1Money? -
- gross_sales_money V1Money? -
- id string? - The payment's unique identifier.
- inclusive_tax V1PaymentTax[]? - All of the inclusive taxes associated with the payment.
- inclusive_tax_money V1Money? -
- is_partial boolean? - Indicates whether or not the payment is only partially paid for. If true, this payment will have the tenders collected so far, but the itemizations will be empty until the payment is completed.
- itemizations V1PaymentItemization[]? - The items purchased in the payment.
- merchant_id string? - The unique identifier of the merchant that took the payment.
- net_sales_money V1Money? -
- net_total_money V1Money? -
- payment_url string? - The URL of the payment's detail page in the merchant dashboard. The merchant must be signed in to the merchant dashboard to view this page.
- processing_fee_money V1Money? -
- receipt_url string? - The URL of the receipt for the payment. Note that for split tender payments, this URL corresponds to the receipt for the first tender listed in the payment's tender field. Each Tender object has its own receipt_url field you can use to get the other receipts associated with a split tender payment.
- refunded_money V1Money? -
- refunds V1Refund[]? - All of the refunds applied to the payment. Note that the value of all refunds on a payment can exceed the value of all tenders if a merchant chooses to refund money to a tender after previously accepting returned goods as part of an exchange.
- surcharge_money V1Money? -
- surcharges V1PaymentSurcharge[]? - A list of all surcharges associated with the payment.
- swedish_rounding_money V1Money? -
- tax_money V1Money? -
- tender V1Tender[]? - All of the tenders associated with the payment.
- tip_money V1Money? -
- total_collected_money V1Money? -
squareup: V1PaymentDiscount
V1PaymentDiscount
Fields
- applied_money V1Money? -
- discount_id string? - The ID of the applied discount, if available. Discounts applied in older versions of Square Register might not have an ID.
- name string? - The discount's name.
squareup: V1PaymentItemDetail
V1PaymentItemDetail
Fields
- category_name string? - The name of the item's merchant-defined category, if any.
- item_id string? - The unique ID of the item purchased, if any.
- item_variation_id string? - The unique ID of the item variation purchased, if any.
- sku string? - The item's merchant-defined SKU, if any.
squareup: V1PaymentItemization
Payment include an itemizations
field that lists the items purchased,
along with associated fees, modifiers, and discounts. Each itemization has an
itemization_type
field that indicates which of the following the itemization
represents:
- An item variation from the merchant's item library
- A custom monetary amount
- An action performed on a Square gift card, such as activating or reloading it.
Note*: itemization information included in a Payment
object reflects
details collected at the time of the payment. Details such as the name or
price of items might have changed since the payment was processed.
Fields
- discount_money V1Money? -
- discounts V1PaymentDiscount[]? - All discounts applied to this itemization.
- gross_sales_money V1Money? -
- item_detail V1PaymentItemDetail? - V1PaymentItemDetail
- item_variation_name string? - The name of the item variation purchased, if any.
- itemization_type string? - The type of purchase that the itemization represents, such as an ITEM or CUSTOM_AMOUNT
- modifiers V1PaymentModifier[]? - All modifier options applied to this itemization.
- name string? - The item's name.
- net_sales_money V1Money? -
- notes string? - Notes entered by the merchant about the item at the time of payment, if any.
- quantity decimal? - The quantity of the item purchased. This can be a decimal value.
- single_quantity_money V1Money? -
- taxes V1PaymentTax[]? - All taxes applied to this itemization.
- total_money V1Money? -
squareup: V1PaymentModifier
V1PaymentModifier
Fields
- applied_money V1Money? -
- modifier_option_id string? - The ID of the applied modifier option, if available. Modifier options applied in older versions of Square Register might not have an ID.
- name string? - The modifier option's name.
squareup: V1PaymentSurcharge
V1PaymentSurcharge
Fields
- amount_money V1Money? -
- applied_money V1Money? -
- name string? - The name of the surcharge.
- rate string? - The amount of the surcharge as a percentage. The percentage is provided as a string representing the decimal equivalent of the percentage. For example, "0.7" corresponds to a 7% surcharge. Exactly one of rate or amount_money should be set.
- surcharge_id string? - A Square-issued unique identifier associated with the surcharge.
- taxable boolean? - Indicates whether the surcharge is taxable.
- taxes V1PaymentTax[]? - The list of taxes that should be applied to the surcharge.
- 'type string? - Indicates the source of the surcharge. For example, if it was applied as an automatic gratuity for a large group.
squareup: V1PaymentTax
V1PaymentTax
Fields
- applied_money V1Money? -
- errors Error[]? - Any errors that occurred during the request.
- fee_id string? - The ID of the tax, if available. Taxes applied in older versions of Square Register might not have an ID.
- inclusion_type string? - Whether the tax is an ADDITIVE tax or an INCLUSIVE tax.
- name string? - The merchant-defined name of the tax.
- rate string? - The rate of the tax, as a string representation of a decimal number. A value of 0.07 corresponds to a rate of 7%.
squareup: V1PhoneNumber
Represents a phone number.
Fields
- calling_code string - The phone number's international calling code. For US phone numbers, this value is +1.
- number string - The phone number.
squareup: V1Refund
V1Refund
Fields
- created_at string? - The time when the merchant initiated the refund for Square to process, in ISO 8601 format.
- is_exchange boolean? - Indicates whether or not the refund is associated with an exchange. If is_exchange is true, the refund reflects the value of goods returned in the exchange not the total money refunded.
- merchant_id string? -
- payment_id string? - A Square-issued ID associated with the refund. For single-tender refunds, payment_id is the ID of the original payment ID. For split-tender refunds, payment_id is the ID of the original tender. For exchange-based refunds (is_exchange == true), payment_id is the ID of the original payment ID even if the payment includes other tenders.
- processed_at string? - The time when Square processed the refund on behalf of the merchant, in ISO 8601 format.
- reason string? - The merchant-specified reason for the refund.
- refunded_additive_tax V1PaymentTax[]? - All of the additive taxes associated with the refund.
- refunded_additive_tax_money V1Money? -
- refunded_discount_money V1Money? -
- refunded_inclusive_tax V1PaymentTax[]? - All of the inclusive taxes associated with the refund.
- refunded_inclusive_tax_money V1Money? -
- refunded_money V1Money? -
- refunded_processing_fee_money V1Money? -
- refunded_surcharge_money V1Money? -
- refunded_surcharges V1PaymentSurcharge[]? - A list of all surcharges associated with the refund.
- refunded_tax_money V1Money? -
- refunded_tip_money V1Money? -
- 'type string? - The type of refund
squareup: V1RetrieveEmployeeRequest
squareup: V1RetrieveEmployeeRoleRequest
squareup: V1RetrieveOrderRequest
squareup: V1RetrievePaymentRequest
squareup: V1RetrieveSettlementRequest
squareup: V1Settlement
V1Settlement
Fields
- bank_account_id string? - The Square-issued unique identifier for the bank account associated with the settlement.
- entries V1SettlementEntry[]? - The entries included in this settlement.
- id string? - The settlement's unique identifier.
- initiated_at string? - The time when the settlement was submitted for deposit or withdrawal, in ISO 8601 format.
- status string? - The settlement's current status.
- total_money V1Money? -
squareup: V1SettlementEntry
V1SettlementEntry
Fields
- amount_money V1Money? -
- fee_money V1Money? -
- payment_id string? - The settlement's unique identifier.
- 'type string? - The settlement's current status.
squareup: V1Tender
A tender represents a discrete monetary exchange. Square represents this exchange as a money object with a specific currency and amount, where the amount is given in the smallest denomination of the given currency.
Square POS can accept more than one form of tender for a single payment (such
as by splitting a bill between a credit card and a gift card). The tender
field of the Payment object lists all forms of tender used for the payment.
Split tender payments behave slightly differently from single tender payments:
The receipt_url for a split tender corresponds only to the first tender listed in the tender field. To get the receipt URLs for the remaining tenders, use the receipt_url fields of the corresponding Tender objects.
A note on gift cards*: when a customer purchases a Square gift card from a merchant, the merchant receives the full amount of the gift card in the associated payment.
When that gift card is used as a tender, the balance of the gift card is
reduced and the merchant receives no funds. A Tender
object with a type of
SQUARE_GIFT_CARD
indicates a gift card was used for some or all of the
associated payment.
Fields
- card_brand string? - The brand of credit card provided.
- change_back_money V1Money? -
- employee_id string? - The ID of the employee that processed the tender.
- entry_method string? - The tender's unique ID.
- id string? - The tender's unique ID.
- is_exchange boolean? - Indicates whether or not the tender is associated with an exchange. If is_exchange is true, the tender represents the value of goods returned in an exchange not the actual money paid. The exchange value reduces the tender amounts needed to pay for items purchased in the exchange.
- name string? - A human-readable description of the tender.
- pan_suffix string? - The last four digits of the provided credit card's account number.
- payment_note string? - Notes entered by the merchant about the tender at the time of payment, if any. Typically only present for tender with the type: OTHER.
- receipt_url string? - The URL of the receipt for the tender.
- refunded_money V1Money? -
- settled_at string? - The time when the tender was settled, in ISO 8601 format.
- tendered_at string? - The time when the tender was created, in ISO 8601 format.
- tendered_money V1Money? -
- total_money V1Money? -
- 'type string? - The type of tender.
squareup: V1UpdateEmployeeRequest
Fields
- body V1Employee - Represents one of a business's employees.
squareup: V1UpdateEmployeeRoleRequest
Fields
- body V1EmployeeRole - V1EmployeeRole
squareup: V1UpdateOrderRequest
V1UpdateOrderRequest
Fields
- action string - The action to perform on the order (COMPLETE, CANCEL, or REFUND).
- canceled_note string? - A merchant-specified note about the canceling of the order. Only valid if action is CANCEL.
- completed_note string? - A merchant-specified note about the completion of the order. Only valid if action is COMPLETE.
- refunded_note string? - A merchant-specified note about the refunding of the order. Only valid if action is REFUND.
- shipped_tracking_number string? - The tracking number of the shipment associated with the order. Only valid if action is COMPLETE.
squareup: VoidTransactionRequest
squareup: VoidTransactionResponse
Defines the fields that are included in the response body of a request to the VoidTransaction endpoint.
Fields
- errors Error[]? - Any errors that occurred during the request.
squareup: WageSetting
An object representing a team member's wage information.
Fields
- created_at string? - The timestamp, in RFC 3339 format, describing when the wage setting object was created. For example, "2018-10-04T04:00:00-07:00" or "2019-02-05T12:00:00Z".
- is_overtime_exempt boolean? - Whether the team member is exempt from the overtime rules of the seller's country.
- job_assignments JobAssignment[]? - Required. The ordered list of jobs that the team member is assigned to. The first job assignment is considered the team member's primary job. The minimum length is 1 and the maximum length is 12.
- team_member_id string? - The unique ID of the
TeamMember
whom this wage setting describes.
- updated_at string? - The timestamp, in RFC 3339 format, describing when the wage setting object was last updated. For example, "2018-10-04T04:00:00-07:00" or "2019-02-05T12:00:00Z".
- 'version int? - Used for resolving concurrency issues. The request fails if the version provided does not match the server version at the time of the request. If not provided, Square executes a blind write, potentially overwriting data from another write. For more information, see optimistic concurrency.
squareup: WorkweekConfig
Sets the day of the week and hour of the day that a business starts a workweek. This is used to calculate overtime pay.
Fields
- created_at string? - A read-only timestamp in RFC 3339 format; presented in UTC.
- id string? - The UUID for this object.
- start_of_day_local_time string - The local time at which a business week ends. Represented as a
string in
HH:MM
format (HH:MM:SS
is also accepted, but seconds are truncated).
- start_of_week string - The day of the week on which a business week ends for compensation purposes.
- updated_at string? - A read-only timestamp in RFC 3339 format; presented in UTC.
- 'version int? - Used for resolving concurrency issues. The request fails if the version provided does not match the server version at the time of the request. If not provided, Square executes a blind write; potentially overwriting data from another write.
Anydata types
squareup: GANSource
GANSource
squareup: Info
Info
squareup: InfoCode
InfoCode
squareup: InvoiceDeliveryMethodinvoicedeliverymethod
InvoiceDeliveryMethodinvoicedeliverymethod
squareup: Reason
Reason
squareup: Status
Status
squareup: Type
Type
String types
squareup: ActionCancelReason
ActionCancelReason
squareup: BankAccountStatus
BankAccountStatus
Indicates the current verification status of a BankAccount
object.
squareup: BankAccountType
BankAccountType
Indicates the financial purpose of the bank account.
squareup: BatchretrieveordersrequestOrderidsItemsString
BatchretrieveordersrequestOrderidsItemsString
squareup: BookingStatus
BookingStatus
Supported booking statuses.
squareup: BusinessAppointmentSettingsAlignmentTime
BusinessAppointmentSettingsAlignmentTime
Time units of a service duration for bookings.
squareup: BusinessAppointmentSettingsBookingLocationType
BusinessAppointmentSettingsBookingLocationType
Types of location where service is provided.
squareup: BusinessAppointmentSettingsCancellationPolicy
BusinessAppointmentSettingsCancellationPolicy
The category of the seller’s cancellation policy.
squareup: BusinessAppointmentSettingsMaxAppointmentsPerDayLimitType
BusinessAppointmentSettingsMaxAppointmentsPerDayLimitType
Types of daily appointment limits.
squareup: BusinessBookingProfileBookingPolicy
BusinessBookingProfileBookingPolicy
Policies for accepting bookings.
squareup: BusinessBookingProfileCustomerTimezoneChoice
BusinessBookingProfileCustomerTimezoneChoice
Choices of customer-facing time zone used for bookings.
squareup: CardBrand
CardBrand
Indicates a card's brand, such as VISA
or MASTERCARD
.
squareup: CardPrepaidType
CardPrepaidType
Indicates a card's prepaid type, such as NOT_PREPAID
or PREPAID
.
squareup: CardSquareProduct
CardSquareProduct
squareup: CardType
CardType
Indicates a card's type, such as CREDIT
or DEBIT
.
squareup: CashDrawerEventType
CashDrawerEventType
The types of events on a CashDrawerShift. Each event type represents an employee action on the actual cash drawer represented by a CashDrawerShift.
squareup: CashDrawerShiftState
CashDrawerShiftState
The current state of a cash drawer shift.
squareup: CatalogCustomAttributeDefinitionAppVisibility
CatalogCustomAttributeDefinitionAppVisibility
Defines the visibility of a custom attribute to applications other than their creating application.
squareup: CatalogCustomAttributeDefinitionSellerVisibility
CatalogCustomAttributeDefinitionSellerVisibility
Defines the visibility of a custom attribute to sellers in Square client applications, Square APIs or in Square UIs (including Square Point of Sale applications and Square Dashboard).
squareup: CatalogCustomAttributeDefinitionType
CatalogCustomAttributeDefinitionType
Defines the possible types for a custom attribute.
squareup: CatalogDiscountModifyTaxBasis
CatalogDiscountModifyTaxBasis
squareup: CatalogDiscountType
CatalogDiscountType
How to apply a CatalogDiscount to a CatalogItem.
squareup: CatalogItemProductType
CatalogItemProductType
The type of a CatalogItem. Connect V2 only allows the creation of REGULAR
or APPOINTMENTS_SERVICE
items.
squareup: CatalogModifierListSelectionType
CatalogModifierListSelectionType
Indicates whether a CatalogModifierList supports multiple selections.
squareup: CatalogObjectType
CatalogObjectType
Possible types of CatalogObjects returned from the Catalog, each
containing type-specific properties in the *_data
field corresponding to the object type.
squareup: CatalogPricingType
CatalogPricingType
Indicates whether the price of a CatalogItemVariation should be entered manually at the time of sale.
squareup: CatalogQuickAmountsSettingsOption
CatalogQuickAmountsSettingsOption
Determines a seller's option on Quick Amounts feature.
squareup: CatalogQuickAmountType
CatalogQuickAmountType
Determines the type of a specific Quick Amount.
squareup: CheckoutOptionsPaymentType
CheckoutOptionsPaymentType
squareup: Country
Country
Indicates the country associated with another entity, such as a business. Values are in ISO 3166-1-alpha-2 format.
squareup: Currency
Currency
Indicates the associated currency for an amount of money. Values correspond to ISO 4217.
squareup: CustomerCreationSource
CustomerCreationSource
Indicates the method used to create the customer profile.
squareup: CustomerInclusionExclusion
CustomerInclusionExclusion
Indicates whether customers should be included in, or excluded from, the result set when they match the filtering criteria.
squareup: CustomerSortField
CustomerSortField
Specifies customer attributes as the sort key to customer profiles returned from a search.
squareup: DayOfWeek
DayOfWeek
Indicates the specific day of the week.
squareup: DeviceCodeStatus
DeviceCodeStatus
DeviceCode.Status enum.
squareup: DisputeEvidenceidsItemsString
DisputeEvidenceidsItemsString
squareup: DisputeEvidenceType
DisputeEvidenceType
The type of the dispute evidence.
squareup: DisputeReason
DisputeReason
The list of possible reasons why a cardholder might initiate a dispute with their bank.
squareup: DisputeState
DisputeState
The list of possible dispute states.
squareup: EcomVisibility
EcomVisibility
Determines item visibility in Ecom (Online Store) and Online Checkout.
squareup: EmployeeStatus
EmployeeStatus
The status of the Employee being retrieved.
squareup: ErrorCategory
ErrorCategory
Indicates which high-level category of error has occurred during a request to the Connect API.
squareup: ErrorCode
ErrorCode
Indicates the specific error that occurred during a request to a Square API.
squareup: ExcludeStrategy
ExcludeStrategy
Indicates which products matched by a CatalogPricingRule will be excluded if the pricing rule uses an exclude set.
squareup: GiftCardActivityAdjustDecrementReason
GiftCardActivityAdjustDecrementReason
squareup: GiftCardActivityAdjustIncrementReason
GiftCardActivityAdjustIncrementReason
squareup: GiftCardActivityBlockReason
GiftCardActivityBlockReason
squareup: GiftCardActivityClearBalanceReason
GiftCardActivityClearBalanceReason
squareup: GiftCardActivityDeactivateReason
GiftCardActivityDeactivateReason
squareup: GiftCardActivityType
GiftCardActivityType
squareup: GiftCardActivityUnblockReason
GiftCardActivityUnblockReason
squareup: GiftcardCustomeridsItemsString
GiftcardCustomeridsItemsString
squareup: GiftCardGANSource
GiftCardGANSource
Indicates the source that generated the gift card account number (GAN).
squareup: GiftCardStatus
GiftCardStatus
Indicates the gift card state.
squareup: GiftCardType
GiftCardType
squareup: InlineTypes
InlineTypes
Object types to inline under their respective parent object in certain connect v2 responses
squareup: InventoryAlertType
InventoryAlertType
Indicates whether Square should alert the merchant when the inventory quantity of a CatalogItemVariation is low.
squareup: InventoryChangeType
InventoryChangeType
Indicates how the inventory change was applied to a tracked product quantity.
squareup: InventoryState
InventoryState
Indicates the state of a tracked item quantity in the lifecycle of goods.
squareup: InvoiceAutomaticPaymentSource
InvoiceAutomaticPaymentSource
Indicates the automatic payment method for an invoice payment request.
squareup: InvoiceCustomFieldPlacement
InvoiceCustomFieldPlacement
Indicates where to render a custom field on the Square-hosted invoice page and in emailed or PDF copies of the invoice.
squareup: InvoiceDeliveryMethod
InvoiceDeliveryMethod
Indicates how Square delivers the invoice to the customer.
squareup: InvoicePaymentReminderStatus
InvoicePaymentReminderStatus
The status of a payment request reminder.
squareup: InvoiceRequestMethod
InvoiceRequestMethod
Specifies the action for Square to take for processing the invoice. For example,
email the invoice, charge a customer's card on file, or do nothing. DEPRECATED at
version 2021-01-21. The corresponding request_method
field is replaced by the
Invoice.delivery_method
and InvoicePaymentRequest.automatic_payment_source
fields.
squareup: InvoiceRequestType
InvoiceRequestType
Indicates the type of the payment request. For more information, see Payment requests.
squareup: InvoiceSortField
InvoiceSortField
The field to use for sorting.
squareup: InvoiceStatus
InvoiceStatus
Indicates the status of an invoice.
squareup: JobAssignmentPayType
JobAssignmentPayType
Enumerates the possible pay types that a job can be assigned.
squareup: LocationCapability
LocationCapability
The capabilities a location may have.
squareup: LocationStatus
LocationStatus
The status of the location, whether a location is active or inactive.
squareup: LocationType
LocationType
A location's physical or mobile type.
squareup: LoyaltyAccountMappingType
LoyaltyAccountMappingType
The type of mapping.
squareup: LoyaltyeventlocationfilterLocationidsItemsString
LoyaltyeventlocationfilterLocationidsItemsString
squareup: LoyaltyEventSource
LoyaltyEventSource
Defines whether the event was generated by the Square Point of Sale.
squareup: LoyaltyEventType
LoyaltyEventType
The type of the loyalty event.
squareup: LoyaltyProgramAccrualRuleType
LoyaltyProgramAccrualRuleType
The type of the accrual rule that defines how buyers can earn points.
squareup: LoyaltyprogramLocationidsItemsString
LoyaltyprogramLocationidsItemsString
squareup: LoyaltyProgramRewardDefinitionScope
LoyaltyProgramRewardDefinitionScope
Indicates the scope of the reward tier. DEPRECATED at version 2020-12-16. Discount details are now defined using a catalog pricing rule and other catalog objects. For more information, see Get discount details for the reward.
squareup: LoyaltyProgramRewardDefinitionType
LoyaltyProgramRewardDefinitionType
The type of discount the reward tier offers. DEPRECATED at version 2020-12-16. Discount details are now defined using a catalog pricing rule and other catalog objects. For more information, see Get discount details for the reward.
squareup: LoyaltyProgramStatus
LoyaltyProgramStatus
Indicates whether the program is currently active.
squareup: LoyaltyRewardStatus
LoyaltyRewardStatus
The status of the loyalty reward.
squareup: MeasurementUnitArea
MeasurementUnitArea
Unit of area used to measure a quantity.
squareup: MeasurementUnitGeneric
MeasurementUnitGeneric
squareup: MeasurementUnitLength
MeasurementUnitLength
The unit of length used to measure a quantity.
squareup: MeasurementUnitTime
MeasurementUnitTime
Unit of time used to measure a quantity (a duration).
squareup: MeasurementUnitUnitType
MeasurementUnitUnitType
Describes the type of this unit and indicates which field contains the unit information. This is an ‘open’ enum.
squareup: MeasurementUnitVolume
MeasurementUnitVolume
The unit of volume used to measure a quantity.
squareup: MeasurementUnitWeight
MeasurementUnitWeight
Unit of weight used to measure a quantity.
squareup: MerchantStatus
MerchantStatus
squareup: OrderFulfillmentPickupDetailsScheduleType
OrderFulfillmentPickupDetailsScheduleType
The schedule type of the pickup fulfillment.
squareup: OrderFulfillmentState
OrderFulfillmentState
The current state of this fulfillment.
squareup: OrderFulfillmentType
OrderFulfillmentType
The type of fulfillment.
squareup: OrderLineItemDiscountScope
OrderLineItemDiscountScope
Indicates whether this is a line-item or order-level discount.
squareup: OrderLineItemDiscountType
OrderLineItemDiscountType
Indicates how the discount is applied to the associated line item or order.
squareup: OrderLineItemItemType
OrderLineItemItemType
Represents the line item type.
squareup: OrderLineItemTaxScope
OrderLineItemTaxScope
Indicates whether this is a line-item or order-level tax.
squareup: OrderLineItemTaxType
OrderLineItemTaxType
Indicates how the tax is applied to the associated line item or order.
squareup: OrderServiceChargeCalculationPhase
OrderServiceChargeCalculationPhase
Represents a phase in the process of calculating order totals. Service charges are applied after the indicated phase.
squareup: OrderServiceChargeType
OrderServiceChargeType
squareup: OrderState
OrderState
The state of the order.
squareup: Product
Product
Indicates the Square product used to generate an inventory change.
squareup: ProductType
ProductType
squareup: RefundStatus
RefundStatus
Indicates a refund's current status.
squareup: RegisterDomainResponseStatus
RegisterDomainResponseStatus
The status of the domain registration.
squareup: RiskEvaluationRiskLevel
RiskEvaluationRiskLevel
squareup: SearchCatalogItemsRequestStockLevel
SearchCatalogItemsRequestStockLevel
Defines supported stock levels of the item inventory.
squareup: SearchOrdersSortField
SearchOrdersSortField
Specifies which timestamp to use to sort SearchOrder
results.
squareup: ShiftfilterLocationidsItemsString
ShiftfilterLocationidsItemsString
squareup: ShiftFilterStatus
ShiftFilterStatus
Specifies the status
of Shift
records to be returned.
squareup: ShiftfilterTeammemberidsItemsString
ShiftfilterTeammemberidsItemsString
squareup: ShiftSortField
ShiftSortField
Enumerates the Shift
fields to sort on.
squareup: ShiftStatus
ShiftStatus
Enumerates the possible status of a Shift
.
squareup: ShiftWorkdayMatcher
ShiftWorkdayMatcher
Defines the logic used to apply a workday filter.
squareup: SortOrder
SortOrder
The order (e.g., chronological or alphabetical) in which results from a request are returned.
squareup: SubscriptionCadence
SubscriptionCadence
Determines the billing cadence of a Subscription
squareup: SubscriptionEventInfoCode
SubscriptionEventInfoCode
The possible subscription event info codes.
squareup: SubscriptionEventSubscriptionEventType
SubscriptionEventSubscriptionEventType
The possible subscription event types.
squareup: SubscriptionStatus
SubscriptionStatus
Possible subscription status values.
squareup: TaxCalculationPhase
TaxCalculationPhase
When to calculate the taxes due on a cart.
squareup: TaxInclusionType
TaxInclusionType
Whether to the tax amount should be additional to or included in the CatalogItem price.
squareup: TeamMemberAssignedLocationsAssignmentType
TeamMemberAssignedLocationsAssignmentType
Enumerates the possible assignment types that the team member can have.
squareup: TeamMemberInvitationStatus
TeamMemberInvitationStatus
Enumerates the possible invitation statuses the team member can have within a business.
squareup: TeamMemberStatus
TeamMemberStatus
Enumerates the possible statuses the team member can have within a business.
squareup: TenderCardDetailsEntryMethod
TenderCardDetailsEntryMethod
Indicates the method used to enter the card's details.
squareup: TenderCardDetailsStatus
TenderCardDetailsStatus
Indicates the card transaction's current status.
squareup: TenderType
TenderType
Indicates a tender's type.
squareup: TransactionProduct
TransactionProduct
Indicates the Square product used to process a transaction.
squareup: TransactionType
TransactionType
The transaction type used in the disputed payment.
squareup: V1CreateRefundRequestType
V1CreateRefundRequestType
squareup: V1EmployeeRolePermissions
V1EmployeeRolePermissions
squareup: V1EmployeeStatus
V1EmployeeStatus
squareup: V1ListEmployeesRequestStatus
V1ListEmployeesRequestStatus
squareup: V1ListSettlementsRequestStatus
V1ListSettlementsRequestStatus
squareup: V1OrderHistoryEntryAction
V1OrderHistoryEntryAction
squareup: V1OrderState
V1OrderState
squareup: V1PaymentItemizationItemizationType
V1PaymentItemizationItemizationType
squareup: V1PaymentSurchargeType
V1PaymentSurchargeType
squareup: V1PaymentTaxInclusionType
V1PaymentTaxInclusionType
squareup: V1RefundType
V1RefundType
squareup: V1SettlementEntryType
V1SettlementEntryType
squareup: V1SettlementStatus
V1SettlementStatus
squareup: V1TenderCardBrand
V1TenderCardBrand
The brand of a credit card.
squareup: V1TenderEntryMethod
V1TenderEntryMethod
squareup: V1TenderType
V1TenderType
squareup: V1UpdateOrderRequestAction
V1UpdateOrderRequestAction
squareup: Weekday
Weekday
The days of the week.
Import
import ballerinax/squareup;
Metadata
Released date: about 1 year ago
Version: 1.3.1
License: Apache-2.0
Compatibility
Platform: any
Ballerina version: 2201.4.1
GraalVM compatible: Yes
Pull count
Total: 0
Current verison: 0
Weekly downloads
Keywords
Commerce/eCommerce
Cost/Paid
Contributors