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
- caption string? - A caption that describes what is shown in the image. Displayed in the Square Online Store. This is a searchable attribute for use in applicable query filters using the SearchCatalogObjects.
- 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[]<